Narrow $callback parameter type for add_shortcode()

Author: IanDelMar

functionMap.php

@@ -49,7 +49,7 @@
     'add_pages_page' => [null, 'callback' => "''|callable"],
     'add_plugins_page' => [null, 'callback' => "''|callable"],
     'add_posts_page' => [null, 'callback' => "''|callable"],
-    'add_shortcode' => [null, 'tag' => 'non-empty-string'],
+    'add_shortcode' => ['void', 'tag' => 'non-empty-string', 'callback' => 'callable(array<string>, string|null, string): string'],
     'add_submenu_page' => [null, 'callback' => "''|callable"],
     'add_theme_page' => [null, 'callback' => "''|callable"],
     'add_users_page' => [null, 'callback' => "''|callable"],

tests/ParameterTypeTest.php

@@ -57,8 +57,14 @@ public function testAddShortcode(): void
             [
                 ['Parameter #1 $tag of function add_shortcode expects non-empty-string, 1 given.', 10],
                 ["Parameter #1 \$tag of function add_shortcode expects non-empty-string, '' given.", 11],
-                // Maybes
                 ['Parameter #1 $tag of function add_shortcode expects non-empty-string, string given.', 14],
+                ['Parameter #2 $callback of function add_shortcode expects callable(array<string>, string|null, string): string, Closure(): void given.', 17],
+                ['Parameter #2 $callback of function add_shortcode expects callable(array<string>, string|null, string): string, Closure(string): string given.', 18],
+                ['Parameter #2 $callback of function add_shortcode expects callable(array<string>, string|null, string): string, Closure(array, string): string given.', 19],
+                ['Parameter #2 $callback of function add_shortcode expects callable(array<string>, string|null, string): string, Closure(array, string|null, bool): string given.', 20],
+                ["Parameter #2 \$callback of function add_shortcode expects callable(array<string>, string|null, string): string, 'addShortcodeVoid' given.", 21],
+                ["Parameter #2 \$callback of function add_shortcode expects callable(array<string>, string|null, string): string, 'addShortcodeIntDoc' given.", 22],
+
             ]
         );
     }

tests/data/param/add-shortcode.php

@@ -1,10 +1,10 @@
-<?php
+<?php // phpcs:disable
 
 declare(strict_types=1);
 
-namespace PhpStubs\WordPress\Core\Tests;
+use PhpStubs\WordPress\Core\Tests\Faker;
 
-use function add_shortcode;
+$tag = Faker::nonEmptyString();
 
 // Incorrect $tag
 add_shortcode(1, Faker::callable());
@@ -13,8 +13,31 @@
 // Maybe incorrect $tag
 add_shortcode(Faker::string(), Faker::callable());
 
+// Incorrect $callback
+add_shortcode($tag, static function(): void {}); // Incorrect return type
+add_shortcode($tag, static function(string $atts): string {return Faker::string();}); // Incorrect $atts type
+add_shortcode($tag, static function(array $atts, string $content): string {return Faker::string();}); // Incorrect $content type (must accept null)
+add_shortcode($tag, static function(array $atts, ?string $content, bool $tag): string {return Faker::string();}); // Incorrect $tag type
+add_shortcode($tag, 'addShortcodeVoid'); // Incorrect callback return type
+add_shortcode($tag, 'addShortcodeIntDoc'); // Incorrect callback return type
+
 // Correct $tag
 add_shortcode('0', Faker::callable()); // '0' is a valid tag
 add_shortcode('tag', Faker::callable());
-add_shortcode(Faker::nonEmptyString(), Faker::callable()); // '0' is a valid tag
-add_shortcode(Faker::nonFalsyString(), Faker::callable());
+add_shortcode($tag, Faker::callable());
+
+// Correct $callback
+add_shortcode($tag, static function(): string {return '';});
+add_shortcode($tag, static function(array $atts): string {return '';});
+add_shortcode($tag, static function(array $atts, ?string $content): string {return '';});
+add_shortcode($tag, static function(array $atts, ?string $content, string $tag): string {return '';});
+add_shortcode($tag, 'addShortcodeStringDoc');
+
+function addShortcodeVoid(): void {}
+function addShortcodeString(): string {return Faker::string();}
+
+/** @return int */
+function addShortcodeIntDoc() {return Faker::int();}
+
+/** @return string */
+function addShortcodeStringDoc() {return Faker::string();}

wordpress-stubs.php

@@ -137606,6 +137606,7 @@ function wp_default_script_modules()
      *                           or null if not set (`$content`), and finally the shortcode tag
      *                           itself (`$shortcode_tag`), in that order.
      * @phpstan-param non-empty-string $tag
+     * @phpstan-param callable(array<string>, string|null, string): string $callback
      * @phpstan-return void
      */
     function add_shortcode($tag, $callback)