From d866d5de72bfd88eb457e550be2411be87cec5c5 Mon Sep 17 00:00:00 2001
From: Mat Lipe <mat@matlipe.com>
Date: Sun, 14 Apr 2024 18:48:41 -0500
Subject: [PATCH] Add PHPStan template annotations for WP_Widget class (#160)

- Support passing the shape for the widget settings.
- Add type for the widget arguments registered from `register_sidebar`.
---
 functionMap.php     | 4 ++++
 wordpress-stubs.php | 6 ++++++
 2 files changed, 10 insertions(+)

diff --git a/functionMap.php b/functionMap.php
index a283757..843c364 100644
--- a/functionMap.php
+++ b/functionMap.php
@@ -131,4 +131,8 @@
     'get_bookmark' => ["null|(\$output is 'ARRAY_A' ? array<string, mixed> : (\$output is 'ARRAY_N' ? array<int, mixed> : \stdClass))", 'output' => "'OBJECT'|'ARRAY_A'|'ARRAY_N'"],
     'get_category' => ["(\$category is object ? array<array-key, mixed>|\WP_Term : array<array-key, mixed>|\WP_Term|\WP_Error|null) & (\$output is 'ARRAY_A' ? array<string, mixed>|\WP_Error|null : (\$output is 'ARRAY_N' ? array<int, mixed>|\WP_Error|null : \WP_Term|\WP_Error|null))", 'output' => "'OBJECT'|'ARRAY_A'|'ARRAY_N'"],
     'get_category_by_path' => ["(\$output is 'ARRAY_A' ? array<string, mixed>|\WP_Error|null : (\$output is 'ARRAY_N' ? array<int, mixed>|\WP_Error|null : \WP_Term|\WP_Error|null))", 'output' => "'OBJECT'|'ARRAY_A'|'ARRAY_N'"],
+    'WP_Widget' => [null, '@phpstan-template' => 'T of array<string, mixed>'],
+    'WP_Widget::form' => [null, 'instance' => 'T'],
+    'WP_Widget::update' => [null, 'new_instance' => 'T', 'old_instance' => 'T'],
+    'WP_Widget::widget' => [null, 'instance' => 'T', 'args' => 'array{name:string,id:string,description:string,class:string,before_widget:string,after_widget:string,before_title:string,after_title:string,before_sidebar:string,after_sidebar:string,show_in_rest:boolean,widget_id:string,widget_name:string}'],
 ];
diff --git a/wordpress-stubs.php b/wordpress-stubs.php
index e9d1899..49b09f5 100644
--- a/wordpress-stubs.php
+++ b/wordpress-stubs.php
@@ -55912,6 +55912,7 @@ public function get_widget_key($id_base)
      *
      * @since 2.8.0
      * @since 4.4.0 Moved to its own file from wp-includes/widgets.php
+     * @phpstan-template T of array<string, mixed>
      */
     #[\AllowDynamicProperties]
     class WP_Widget
@@ -55995,6 +55996,8 @@ class WP_Widget
          * @param array $args     Display arguments including 'before_title', 'after_title',
          *                        'before_widget', and 'after_widget'.
          * @param array $instance The settings for the particular instance of the widget.
+         * @phpstan-param T $instance
+         * @phpstan-param array{name:string,id:string,description:string,class:string,before_widget:string,after_widget:string,before_title:string,after_title:string,before_sidebar:string,after_sidebar:string,show_in_rest:boolean,widget_id:string,widget_name:string} $args
          */
         public function widget($args, $instance)
         {
@@ -56012,6 +56015,8 @@ public function widget($args, $instance)
          *                            WP_Widget::form().
          * @param array $old_instance Old settings for this instance.
          * @return array Settings to save or bool false to cancel saving.
+         * @phpstan-param T $new_instance
+         * @phpstan-param T $old_instance
          */
         public function update($new_instance, $old_instance)
         {
@@ -56023,6 +56028,7 @@ public function update($new_instance, $old_instance)
          *
          * @param array $instance Current settings.
          * @return string Default return is 'noform'.
+         * @phpstan-param T $instance
          */
         public function form($instance)
         {