From 13139c7d5ba382fa7137735b148010ad6849c840 Mon Sep 17 00:00:00 2001
From: Marian <42134098+IanDelMar@users.noreply.github.com>
Date: Wed, 29 Oct 2025 05:03:49 +0100
Subject: [PATCH] Narrow $callback parameter type for add_shortcode()

---
 functionMap.php                    |  2 +-
 tests/ParameterTypeTest.php        |  8 +++++++-
 tests/data/param/add-shortcode.php | 33 +++++++++++++++++++++++++-----
 wordpress-stubs.php                |  1 +
 4 files changed, 37 insertions(+), 7 deletions(-)

diff --git a/functionMap.php b/functionMap.php
index 85de493..dca33bb 100644
--- a/functionMap.php
+++ b/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"],
diff --git a/tests/ParameterTypeTest.php b/tests/ParameterTypeTest.php
index c6a615e..883c3fe 100644
--- a/tests/ParameterTypeTest.php
+++ b/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],
+
             ]
         );
     }
diff --git a/tests/data/param/add-shortcode.php b/tests/data/param/add-shortcode.php
index b4895e1..d62c241 100644
--- a/tests/data/param/add-shortcode.php
+++ b/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();}
diff --git a/wordpress-stubs.php b/wordpress-stubs.php
index 26f4c88..d9ebb07 100644
--- a/wordpress-stubs.php
+++ b/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)