From b921c735f11ee207cad9588c90643de42c3f003b Mon Sep 17 00:00:00 2001 From: Miguel Colmenares Date: Wed, 12 Aug 2026 12:50:40 -0500 Subject: [PATCH 1/2] Adopt silverassist/coding-standards for PHPCS This is a library, not a WordPress plugin (no main plugin file, no plugins_loaded hook, no WordPress dependency in composer.json's require), so PSR-12 (silverassist/coding-standards) applies rather than WordPress-Extra (silverassist/wp-coding-standards) -- confirmed by this repo's own pre-existing ruleset, which already deliberately based itself on PSR12 plus a hand-picked handful of WordPress security/i18n sniffs, not full WordPress-Extra. Adopting the shared SilverAssist ruleset (PSR-12 + mandatory PHPDoc) surfaced 181 violations: - 103 auto-fixed (phpcbf): spacing, boolean->bool, etc. - 72 comments/param descriptions missing terminal punctuation. - 66 missing @return tags -- inferred each one's actual return type from its function signature and inserted the correct tag, not a blanket @return mixed. - 8 missing docblocks entirely (test methods). - 5 untyped params that already had "@param mixed" in their docblock but no matching `mixed` PHP type declaration -- added the real type hint. phpstan.neon deliberately left untouched: this repo has zero CI quality gate today (only Dependabot + CodeQL run), and its committed config already has 29 pre-existing PHPStan errors unrelated to this change (accumulated dependency drift, not something this PR should silently absorb into an unrelated migration). Verified with the real WordPress Test Suite, not just phpcs/phpstan: 58/58 tests passing. --- composer.json | 7 +- phpcs.xml | 27 ++--- src/Updater.php | 47 ++++---- src/UpdaterConfig.php | 12 +- tests/Integration/DownloadFilterTest.php | 8 ++ tests/Integration/UpdaterIntegrationTest.php | 9 ++ tests/Unit/UpdaterConfigTest.php | 21 ++++ tests/Unit/UpdaterEnqueueScriptTest.php | 29 ++++- tests/WordPress/MockPluginTest.php | 15 +++ tests/WordPress/WordPressHooksTest.php | 15 +++ tests/bootstrap.php | 1 + tests/fixtures/mock-plugin/mock-plugin.php | 5 + tests/wordpress-mocks.php | 112 +++++++++---------- 13 files changed, 209 insertions(+), 99 deletions(-) diff --git a/composer.json b/composer.json index d4073bb..accd1dd 100644 --- a/composer.json +++ b/composer.json @@ -32,7 +32,9 @@ "php-stubs/wordpress-tests-stubs": "^6.8 || ^7.0", "phpcompatibility/phpcompatibility-wp": "^2.1", "szepeviktor/phpstan-wordpress": "^1.3", - "yoast/phpunit-polyfills": "^4.0" + "yoast/phpunit-polyfills": "^4.0", + "silverassist/coding-standards": "^1.0", + "dealerdirect/phpcodesniffer-composer-installer": "^1.0" }, "autoload": { "psr-4": { @@ -63,6 +65,9 @@ "optimize-autoloader": true, "allow-plugins": { "dealerdirect/phpcodesniffer-composer-installer": true + }, + "platform": { + "php": "8.2.0" } }, "extra": { diff --git a/phpcs.xml b/phpcs.xml index 830a943..fbf8549 100644 --- a/phpcs.xml +++ b/phpcs.xml @@ -2,21 +2,19 @@ @@ -33,8 +31,7 @@ src tests - - + diff --git a/src/Updater.php b/src/Updater.php index e890e83..2a63eb6 100644 --- a/src/Updater.php +++ b/src/Updater.php @@ -81,7 +81,7 @@ class Updater * * Sets up plugin identification, version information and WordPress hooks. * - * @param UpdaterConfig $config Updater configuration object + * @param UpdaterConfig $config Updater configuration object. * * @since 1.0.0 */ @@ -106,6 +106,7 @@ public function __construct(UpdaterConfig $config) * * * @since 1.0.0 + * @return void */ private function initHooks(): void { @@ -132,12 +133,12 @@ private function initHooks(): void * Compares the current plugin version with the latest GitHub release * and adds update information to the WordPress update transient if needed. * - * @param mixed $transient The update_plugins transient containing current plugin versions + * @param mixed $transient The update_plugins transient containing current plugin versions. * @return mixed The modified transient with update information added if available * * @since 1.0.0 */ - public function checkForUpdate($transient) + public function checkForUpdate(mixed $transient) { if (empty($transient->checked)) { return $transient; @@ -167,9 +168,9 @@ public function checkForUpdate($transient) * Provides detailed plugin information when WordPress requests it, * including version, changelog, and download information. * - * @param false|object|array $result The result object or array - * @param string $action The type of information being requested - * @param object $args Plugin API arguments + * @param false|object|array $result The result object or array. + * @param string $action The type of information being requested. + * @param object $args Plugin API arguments. * @return false|object|array Plugin information object or original result * * @since 1.0.0 @@ -249,9 +250,10 @@ public function getLatestVersion(): string|false /** * Get download URL for a specific version * - * @param string $version The version to download + * @param string $version The version to download. * * @since 1.0.0 + * @return string */ private function getDownloadUrl(string $version): string { @@ -275,7 +277,7 @@ private function getDownloadUrl(string $version): string /** * Get actual asset download URL from GitHub API * - * @param string $version The version to get asset URL for + * @param string $version The version to get asset URL for. * @return string|null Asset download URL or null if not found * * @since 1.1.0 @@ -393,8 +395,9 @@ private function getLastUpdated(): string /** * Clear version cache after update * - * @param WP_Upgrader $upgrader WP_Upgrader instance - * @param array $data Array of update data + * @param WP_Upgrader $upgrader WP_Upgrader instance. + * @param array $data Array of update data. + * @return void */ public function clearVersionCache(WP_Upgrader $upgrader, array $data): void { @@ -407,6 +410,7 @@ public function clearVersionCache(WP_Upgrader $upgrader, array $data): void /** * Manual version check via AJAX + * @return void */ public function manualVersionCheck(): void { @@ -494,6 +498,7 @@ public function dismissUpdateNotice(): void * after a manual version check. * * @since 1.1.4 + * @return void */ public function showUpdateNotice(): void { @@ -556,6 +561,7 @@ public function showUpdateNotice(): void /** * Get plugin data from file + * @return array */ private function getPluginData(): array { @@ -569,6 +575,7 @@ private function getPluginData(): array /** * Get current version * + * @return string */ public function getCurrentVersion(): string { @@ -578,6 +585,7 @@ public function getCurrentVersion(): string /** * Get GitHub repository * + * @return string */ public function getGithubRepo(): string { @@ -587,6 +595,7 @@ public function getGithubRepo(): string /** * Check if update is available * + * @return boolean */ public function isUpdateAvailable(): bool { @@ -602,7 +611,7 @@ public function isUpdateAvailable(): bool * the need for consuming plugins to maintain their own JavaScript files. * The script is loaded once and works for multiple plugins on the same page. * - * @param array $extraStrings Optional extra i18n string overrides + * @param array $extraStrings Optional extra i18n string overrides. * @return string Inline JS to echo (e.g. "wpGithubUpdaterCheckUpdates('myData'); return false;") * * @since 1.3.0 @@ -653,7 +662,7 @@ public function enqueueCheckUpdatesScript(array $extraStrings = []): string * PHP's autoloader loads the class from the first registered vendor directory, but * each plugin instance needs to load assets from its own vendor directory. * - * @param string $assetPath Relative path to asset (e.g., 'assets/js/check-updates.js') + * @param string $assetPath Relative path to asset (e.g., 'assets/js/check-updates.js'). * @return string Full URL to the asset file * * @since 1.3.0 @@ -695,7 +704,7 @@ private function getPackageAssetUrl(string $assetPath): string * Removes or replaces characters that are not valid in JavaScript identifiers. * Used to generate unique global variable names for wp_localize_script. * - * @param string $name Raw name to sanitize + * @param string $name Raw name to sanitize. * @return string Valid JavaScript variable name * * @since 1.3.0 @@ -720,7 +729,7 @@ private function sanitizeJsVarName(string $name): string * Converts basic Markdown syntax to HTML for better changelog display. * Supports headers, bold text, italic text, inline code, lists, and links. * - * @param string $markdown Markdown content to convert + * @param string $markdown Markdown content to convert. * @return string HTML formatted content * * @since 1.0.1 @@ -778,10 +787,10 @@ private function parseMarkdownToHtml(string $markdown): string * - string: Path to an already-downloaded file for WordPress to use * - NEVER return true or any other type! * - * @param boolean|WP_Error $result The result from previous filters - * @param string $package The package URL being downloaded - * @param object $upgrader The WP_Upgrader instance - * @param array $hook_extra Extra hook data + * @param boolean|WP_Error $result The result from previous filters. + * @param string $package The package URL being downloaded. + * @param object $upgrader The WP_Upgrader instance. + * @param array $hook_extra Extra hook data. * @return string|WP_Error|false Path to downloaded file, WP_Error on failure, or false to continue * * @since 1.1.0 @@ -935,7 +944,7 @@ public function maybeFixDownload( * Attempts different approaches to create a temporary file to avoid PCLZIP errors * that can occur with restrictive /tmp directory permissions. * - * @param string $package The package URL being downloaded + * @param string $package The package URL being downloaded. * @return string|WP_Error Path to temporary file or WP_Error on failure * * @since 1.1.4 diff --git a/src/UpdaterConfig.php b/src/UpdaterConfig.php index fc4df19..a1a69b2 100644 --- a/src/UpdaterConfig.php +++ b/src/UpdaterConfig.php @@ -144,9 +144,9 @@ class UpdaterConfig * Initializes the updater configuration with plugin metadata and settings. * Accepts text domain from the consuming plugin for proper i18n support. * - * @param string $pluginFile Main plugin file path - * @param string $githubRepo GitHub repository (owner/repo) - * @param array $options Additional configuration options including text_domain + * @param string $pluginFile Main plugin file path. + * @param string $githubRepo GitHub repository (owner/repo). + * @param array $options Additional configuration options including text_domain. * * @since 1.0.0 */ @@ -179,7 +179,7 @@ public function __construct(string $pluginFile, string $githubRepo, array $optio * Retrieves plugin metadata from the plugin file header. * Falls back to empty array when WordPress functions aren't available. * - * @param string $pluginFile Path to the plugin file + * @param string $pluginFile Path to the plugin file. * @return array Plugin data array * * @since 1.0.0 @@ -197,7 +197,7 @@ private function getPluginData(string $pluginFile): array /** * Translation wrapper for the package * - * @param string $text Text to translate + * @param string $text Text to translate. * @return string Translated text * * @since 1.1.0 @@ -210,7 +210,7 @@ public function __(string $text): string /** * Escaped translation wrapper for the package * - * @param string $text Text to translate and escape + * @param string $text Text to translate and escape. * @return string Translated and escaped text * * @since 1.1.0 diff --git a/tests/Integration/DownloadFilterTest.php b/tests/Integration/DownloadFilterTest.php index 78c3362..0de49f4 100644 --- a/tests/Integration/DownloadFilterTest.php +++ b/tests/Integration/DownloadFilterTest.php @@ -26,6 +26,7 @@ class DownloadFilterTest extends TestCase /** * Set up test environment before each test + * @return void */ protected function setUp(): void { @@ -42,6 +43,7 @@ protected function setUp(): void /** * Clean up after each test + * @return void */ protected function tearDown(): void { @@ -54,6 +56,7 @@ protected function tearDown(): void /** * Test that temporary directory configuration is respected + * @return void */ public function testCustomTempDirectoryIsRespected(): void { @@ -68,6 +71,7 @@ public function testCustomTempDirectoryIsRespected(): void /** * Test that package URL validation works correctly + * @return void */ public function testPackageUrlValidation(): void { @@ -83,6 +87,7 @@ public function testPackageUrlValidation(): void /** * Test file size validation logic + * @return void */ public function testFileSizeValidation(): void { @@ -97,6 +102,7 @@ public function testFileSizeValidation(): void /** * Test that hook_extra validation logic works + * @return void */ public function testHookExtraValidation(): void { @@ -119,6 +125,7 @@ public function testHookExtraValidation(): void /** * Test version comparison logic + * @return void */ public function testVersionComparison(): void { @@ -133,6 +140,7 @@ public function testVersionComparison(): void /** * Test GitHub repository format validation + * @return void */ public function testGitHubRepoFormat(): void { diff --git a/tests/Integration/UpdaterIntegrationTest.php b/tests/Integration/UpdaterIntegrationTest.php index 4858f8c..5cda25a 100644 --- a/tests/Integration/UpdaterIntegrationTest.php +++ b/tests/Integration/UpdaterIntegrationTest.php @@ -25,6 +25,7 @@ class UpdaterIntegrationTest extends TestCase /** * Set up test environment before each test + * @return void */ protected function setUp(): void { @@ -44,6 +45,7 @@ protected function setUp(): void /** * Clean up after each test + * @return void */ protected function tearDown(): void { @@ -56,6 +58,7 @@ protected function tearDown(): void /** * Test that Updater can be instantiated with valid configuration + * @return void */ public function testUpdaterInstantiation(): void { @@ -68,6 +71,7 @@ public function testUpdaterInstantiation(): void /** * Test configuration validation + * @return void */ public function testConfigurationValidation(): void { @@ -79,6 +83,7 @@ public function testConfigurationValidation(): void /** * Test custom temporary directory configuration + * @return void */ public function testCustomTempDirConfiguration(): void { @@ -93,6 +98,7 @@ public function testCustomTempDirConfiguration(): void /** * Test text domain configuration + * @return void */ public function testTextDomainConfiguration(): void { @@ -105,6 +111,7 @@ public function testTextDomainConfiguration(): void /** * Test AJAX configuration + * @return void */ public function testAjaxConfiguration(): void { @@ -116,6 +123,7 @@ public function testAjaxConfiguration(): void /** * Test asset pattern configuration + * @return void */ public function testAssetPatternConfiguration(): void { @@ -128,6 +136,7 @@ public function testAssetPatternConfiguration(): void /** * Test WordPress requirements configuration + * @return void */ public function testWordPressRequirementsConfiguration(): void { diff --git a/tests/Unit/UpdaterConfigTest.php b/tests/Unit/UpdaterConfigTest.php index 33da8a8..e8f6688 100644 --- a/tests/Unit/UpdaterConfigTest.php +++ b/tests/Unit/UpdaterConfigTest.php @@ -9,11 +9,21 @@ class UpdaterConfigTest extends TestCase { private static string $testPluginFile; + /** + * Resolve the shared test plugin fixture path once for the whole class. + * + * @return void + */ public static function setUpBeforeClass(): void { self::$testPluginFile = dirname(__DIR__) . "/fixtures/test-plugin.php"; } + /** + * Test that UpdaterConfig applies its documented defaults. + * + * @return void + */ public function testBasicConfiguration(): void { $config = new UpdaterConfig(self::$testPluginFile, "owner/repo"); @@ -26,6 +36,11 @@ public function testBasicConfiguration(): void $this->assertEquals("wp-github-updater", $config->textDomain); } + /** + * Test that UpdaterConfig applies caller-supplied option overrides. + * + * @return void + */ public function testCustomConfiguration(): void { $options = [ @@ -55,6 +70,12 @@ public function testCustomConfiguration(): void $this->assertEquals("my-custom-plugin", $config->textDomain); } + /** + * Test that UpdaterConfig's translation helper methods exist and + * return strings. + * + * @return void + */ public function testTranslationMethods(): void { $config = new UpdaterConfig(self::$testPluginFile, "owner/repo", [ diff --git a/tests/Unit/UpdaterEnqueueScriptTest.php b/tests/Unit/UpdaterEnqueueScriptTest.php index f110abd..5580b65 100644 --- a/tests/Unit/UpdaterEnqueueScriptTest.php +++ b/tests/Unit/UpdaterEnqueueScriptTest.php @@ -16,11 +16,21 @@ class UpdaterEnqueueScriptTest extends TestCase { private static string $testPluginFile; + /** + * Resolve the shared test plugin fixture path once for the whole class. + * + * @return void + */ public static function setUpBeforeClass(): void { self::$testPluginFile = dirname(__DIR__) . "/fixtures/test-plugin.php"; } + /** + * Test that enqueueCheckUpdatesScript returns valid JavaScript. + * + * @return void + */ public function testEnqueueCheckUpdatesScriptReturnsValidJavaScript(): void { $config = new UpdaterConfig(self::$testPluginFile, "owner/repo", [ @@ -44,6 +54,11 @@ public function testEnqueueCheckUpdatesScriptReturnsValidJavaScript(): void $this->assertMatchesRegularExpression("/wpGithubUpdaterCheckUpdates\('[a-zA-Z0-9_$]+\'\)/", $result); } + /** + * Test that enqueueCheckUpdatesScript honors extra translated strings. + * + * @return void + */ public function testEnqueueCheckUpdatesScriptWithExtraStrings(): void { $config = new UpdaterConfig(self::$testPluginFile, "owner/repo", [ @@ -64,6 +79,12 @@ public function testEnqueueCheckUpdatesScriptWithExtraStrings(): void $this->assertStringContainsString("wpGithubUpdaterCheckUpdates", $result); } + /** + * Test that enqueueCheckUpdatesScript derives its JS variable name from + * the plugin basename. + * + * @return void + */ public function testEnqueueCheckUpdatesScriptUsesPluginBasename(): void { $config = new UpdaterConfig(self::$testPluginFile, "owner/repo", [ @@ -83,6 +104,7 @@ public function testEnqueueCheckUpdatesScriptUsesPluginBasename(): void /** * Test that the method can be called multiple times without errors + * @return void */ public function testEnqueueCheckUpdatesScriptCanBeCalledMultipleTimes(): void { @@ -107,6 +129,7 @@ public function testEnqueueCheckUpdatesScriptCanBeCalledMultipleTimes(): void * This tests the primary path resolution logic for multi-plugin scenarios. * * @since 1.3.1 + * @return void */ public function testAssetUrlResolutionWithStandardVendorStructure(): void { @@ -164,6 +187,7 @@ public function testAssetUrlResolutionWithStandardVendorStructure(): void * to __DIR__-based resolution for development or non-Composer installations. * * @since 1.3.1 + * @return void */ public function testAssetUrlResolutionFallbackForNonStandardInstallation(): void { @@ -215,6 +239,7 @@ public function testAssetUrlResolutionFallbackForNonStandardInstallation(): void * the first loaded instance's directory. * * @since 1.3.1 + * @return void */ public function testAssetUrlResolutionWithMultiplePlugins(): void { @@ -291,7 +316,7 @@ public function testAssetUrlResolutionWithMultiplePlugins(): void /** * Get the src URL of an enqueued script, compatible with both mock and real WordPress * - * @param string $handle Script handle + * @param string $handle Script handle. * @return string|null The script source URL, or null if not found */ private function getEnqueuedScriptSrc(string $handle): ?string @@ -332,7 +357,7 @@ private function clearEnqueuedScripts(): void /** * Recursively remove a directory and its contents * - * @param string $dir Directory path to remove + * @param string $dir Directory path to remove. * @return void */ private function recursiveRemoveDirectory(string $dir): void diff --git a/tests/WordPress/MockPluginTest.php b/tests/WordPress/MockPluginTest.php index 90f5dc0..921d739 100644 --- a/tests/WordPress/MockPluginTest.php +++ b/tests/WordPress/MockPluginTest.php @@ -35,6 +35,7 @@ class MockPluginTest extends WP_UnitTestCase /** * Set up test environment + * @return void */ public function setUp(): void { @@ -57,6 +58,7 @@ public function setUp(): void /** * Test that mock plugin file exists + * @return void */ public function testMockPluginFileExists(): void { @@ -65,6 +67,7 @@ public function testMockPluginFileExists(): void /** * Test that mock plugin can be loaded + * @return void */ public function testMockPluginCanBeLoaded(): void { @@ -80,6 +83,7 @@ function_exists("mock_plugin_get_updater"), /** * Test that updater is initialized + * @return void */ public function testUpdaterIsInitialized(): void { @@ -89,6 +93,7 @@ public function testUpdaterIsInitialized(): void /** * Test updater configuration + * @return void */ public function testUpdaterConfiguration(): void { @@ -102,6 +107,7 @@ public function testUpdaterConfiguration(): void /** * Test WordPress hooks are registered + * @return void */ public function testWordPressHooksAreRegistered(): void { @@ -120,6 +126,7 @@ public function testWordPressHooksAreRegistered(): void /** * Test AJAX actions are registered + * @return void */ public function testAjaxActionsAreRegistered(): void { @@ -138,6 +145,7 @@ public function testAjaxActionsAreRegistered(): void /** * Test plugin activation + * @return void */ public function testPluginActivation(): void { @@ -155,6 +163,7 @@ public function testPluginActivation(): void /** * Test plugin deactivation + * @return void */ public function testPluginDeactivation(): void { @@ -170,6 +179,7 @@ public function testPluginDeactivation(): void /** * Test admin menu is registered + * @return void */ public function testAdminMenuIsRegistered(): void { @@ -187,6 +197,7 @@ public function testAdminMenuIsRegistered(): void /** * Test update check with transient caching + * @return void */ public function testUpdateCheckWithCaching(): void { @@ -208,6 +219,7 @@ public function testUpdateCheckWithCaching(): void /** * Test plugin data retrieval + * @return void */ public function testPluginDataRetrieval(): void { @@ -223,6 +235,7 @@ public function testPluginDataRetrieval(): void /** * Test plugin basename generation + * @return void */ public function testPluginBasename(): void { @@ -234,6 +247,7 @@ public function testPluginBasename(): void /** * Test custom temporary directory configuration + * @return void */ public function testCustomTempDirectoryConfiguration(): void { @@ -247,6 +261,7 @@ public function testCustomTempDirectoryConfiguration(): void /** * Clean up after tests + * @return void */ public function tearDown(): void { diff --git a/tests/WordPress/WordPressHooksTest.php b/tests/WordPress/WordPressHooksTest.php index 51c0658..4a84eb4 100644 --- a/tests/WordPress/WordPressHooksTest.php +++ b/tests/WordPress/WordPressHooksTest.php @@ -25,6 +25,7 @@ class WordPressHooksTest extends TestCase /** * Set up test environment before each test + * @return void */ protected function setUp(): void { @@ -46,6 +47,7 @@ protected function setUp(): void /** * Clean up after each test + * @return void */ protected function tearDown(): void { @@ -58,6 +60,7 @@ protected function tearDown(): void /** * Test configuration object creation + * @return void */ public function testConfigurationCreation(): void { @@ -68,6 +71,7 @@ public function testConfigurationCreation(): void /** * Test plugin homepage configuration + * @return void */ public function testPluginHomepage(): void { @@ -77,6 +81,7 @@ public function testPluginHomepage(): void /** * Test plugin author configuration + * @return void */ public function testPluginAuthor(): void { @@ -93,6 +98,7 @@ public function testPluginAuthor(): void /** * Test cache duration configuration + * @return void */ public function testCacheDuration(): void { @@ -106,6 +112,7 @@ public function testCacheDuration(): void /** * Test transient naming convention + * @return void */ public function testTransientNaming(): void { @@ -119,6 +126,7 @@ public function testTransientNaming(): void /** * Test AJAX action naming convention + * @return void */ public function testAjaxActionNaming(): void { @@ -132,6 +140,7 @@ public function testAjaxActionNaming(): void /** * Test nonce naming convention + * @return void */ public function testNonceNaming(): void { @@ -145,6 +154,7 @@ public function testNonceNaming(): void /** * Test plugin data structure + * @return void */ public function testPluginDataStructure(): void { @@ -156,6 +166,7 @@ public function testPluginDataStructure(): void /** * Test WordPress version requirements + * @return void */ public function testWordPressVersionRequirements(): void { @@ -166,6 +177,7 @@ public function testWordPressVersionRequirements(): void /** * Test PHP version requirements + * @return void */ public function testPHPVersionRequirements(): void { @@ -176,6 +188,7 @@ public function testPHPVersionRequirements(): void /** * Test asset pattern replacement tokens + * @return void */ public function testAssetPatternTokens(): void { @@ -189,6 +202,7 @@ public function testAssetPatternTokens(): void /** * Test translation function wrapper + * @return void */ public function testTranslationFunctionWrapper(): void { @@ -201,6 +215,7 @@ public function testTranslationFunctionWrapper(): void /** * Test GitHub API URL construction + * @return void */ public function testGitHubApiUrlConstruction(): void { diff --git a/tests/bootstrap.php b/tests/bootstrap.php index 074bf99..fd47ab0 100644 --- a/tests/bootstrap.php +++ b/tests/bootstrap.php @@ -49,6 +49,7 @@ * * This loads our mock plugin that integrates the WP GitHub Updater package * into a WordPress environment for real integration testing. + * @return mixed */ function _manually_load_plugin() { diff --git a/tests/fixtures/mock-plugin/mock-plugin.php b/tests/fixtures/mock-plugin/mock-plugin.php index eacca2b..ca2c20a 100644 --- a/tests/fixtures/mock-plugin/mock-plugin.php +++ b/tests/fixtures/mock-plugin/mock-plugin.php @@ -34,6 +34,7 @@ * * This function demonstrates the recommended integration pattern * for the WP GitHub Updater package. + * @return void */ function mock_plugin_init_updater(): void { @@ -82,6 +83,7 @@ function mock_plugin_init_updater(): void /** * Add admin menu for testing + * @return void */ function mock_plugin_admin_menu(): void { @@ -99,6 +101,7 @@ function mock_plugin_admin_menu(): void /** * Admin page for testing + * @return void */ function mock_plugin_admin_page(): void { @@ -184,6 +187,7 @@ function mock_plugin_admin_page(): void /** * Activation hook + * @return void */ function mock_plugin_activate(): void { @@ -194,6 +198,7 @@ function mock_plugin_activate(): void /** * Deactivation hook + * @return void */ function mock_plugin_deactivate(): void { diff --git a/tests/wordpress-mocks.php b/tests/wordpress-mocks.php index 6b8705f..e1b073e 100644 --- a/tests/wordpress-mocks.php +++ b/tests/wordpress-mocks.php @@ -14,8 +14,8 @@ /** * Mock __ function for tests * - * @param string $text Text to translate - * @param string $domain Text domain + * @param string $text Text to translate. + * @param string $domain Text domain. * @return string Translated text (returns original in tests) */ function __(string $text, string $domain = "default"): string @@ -28,8 +28,8 @@ function __(string $text, string $domain = "default"): string /** * Mock esc_html__ function for tests * - * @param string $text Text to translate - * @param string $domain Text domain + * @param string $text Text to translate. + * @param string $domain Text domain. * @return string Escaped and translated text */ function esc_html__(string $text, string $domain = "default"): string @@ -43,11 +43,11 @@ function esc_html__(string $text, string $domain = "default"): string /** * Mock add_filter function for tests * - * @param string $hook_name Hook name - * @param callable $callback Callback function - * @param int $priority Priority - * @param int $accepted_args Accepted arguments - * @return bool Always returns true + * @param string $hook_name Hook name. + * @param callable $callback Callback function. + * @param integer $priority Priority. + * @param integer $accepted_args Accepted arguments. + * @return boolean Always returns true */ function add_filter(string $hook_name, callable $callback, int $priority = 10, int $accepted_args = 1): bool { @@ -59,11 +59,11 @@ function add_filter(string $hook_name, callable $callback, int $priority = 10, i /** * Mock add_action function for tests * - * @param string $hook_name Hook name - * @param callable $callback Callback function - * @param int $priority Priority - * @param int $accepted_args Accepted arguments - * @return bool Always returns true + * @param string $hook_name Hook name. + * @param callable $callback Callback function. + * @param integer $priority Priority. + * @param integer $accepted_args Accepted arguments. + * @return boolean Always returns true */ function add_action(string $hook_name, callable $callback, int $priority = 10, int $accepted_args = 1): bool { @@ -76,7 +76,7 @@ function add_action(string $hook_name, callable $callback, int $priority = 10, i /** * Mock plugin_basename function for tests * - * @param string $file Plugin file path + * @param string $file Plugin file path. * @return string Plugin basename */ function plugin_basename(string $file): string @@ -108,9 +108,9 @@ function plugin_basename(string $file): string /** * Mock get_plugin_data function for tests * - * @param string $plugin_file Path to the plugin file - * @param bool $markup Whether to apply markup - * @param bool $translate Whether to translate + * @param string $plugin_file Path to the plugin file. + * @param boolean $markup Whether to apply markup. + * @param boolean $translate Whether to translate. * @return array Plugin data array */ function get_plugin_data(string $plugin_file, bool $markup = true, bool $translate = true): array @@ -167,8 +167,8 @@ function get_plugin_data(string $plugin_file, bool $markup = true, bool $transla /** * Mock admin_url function for tests * - * @param string $path Path relative to admin URL - * @param string $scheme URL scheme + * @param string $path Path relative to admin URL. + * @param string $scheme URL scheme. * @return string Admin URL */ function admin_url(string $path = "", string $scheme = "admin"): string @@ -181,8 +181,8 @@ function admin_url(string $path = "", string $scheme = "admin"): string /** * Mock site_url function for tests * - * @param string $path Path relative to site URL - * @param string|null $scheme URL scheme + * @param string $path Path relative to site URL. + * @param string|null $scheme URL scheme. * @return string Site URL */ function site_url(string $path = "", ?string $scheme = null): string @@ -195,7 +195,7 @@ function site_url(string $path = "", ?string $scheme = null): string /** * Mock wp_normalize_path function for tests * - * @param string $path Path to normalize + * @param string $path Path to normalize. * @return string Normalized path */ function wp_normalize_path(string $path): string @@ -214,11 +214,11 @@ function wp_normalize_path(string $path): string /** * Mock wp_enqueue_script function for tests * - * @param string $handle Script handle - * @param string $src Script source URL - * @param array $deps Dependencies - * @param string|bool|null $ver Version - * @param bool $in_footer Load in footer + * @param string $handle Script handle. + * @param string $src Script source URL. + * @param array $deps Dependencies. + * @param string|boolean|null $ver Version. + * @param boolean $in_footer Load in footer. * @return void */ function wp_enqueue_script( @@ -246,10 +246,10 @@ function wp_enqueue_script( /** * Mock wp_localize_script function for tests * - * @param string $handle Script handle - * @param string $object_name JavaScript object name - * @param array $l10n Localization data - * @return bool Always returns true + * @param string $handle Script handle. + * @param string $object_name JavaScript object name. + * @param array $l10n Localization data. + * @return boolean Always returns true */ function wp_localize_script(string $handle, string $object_name, array $l10n): bool { @@ -267,7 +267,7 @@ function wp_localize_script(string $handle, string $object_name, array $l10n): b /** * Mock wp_create_nonce function for tests * - * @param string|int $action Action name + * @param string|integer $action Action name. * @return string Nonce token */ function wp_create_nonce($action = -1): string @@ -280,7 +280,7 @@ function wp_create_nonce($action = -1): string /** * Mock plugin_dir_url function for tests * - * @param string $file Plugin file path + * @param string $file Plugin file path. * @return string Plugin directory URL with trailing slash */ function plugin_dir_url(string $file): string @@ -318,11 +318,11 @@ class WP_Error /** * Constructor * - * @param string $code Error code - * @param string $message Error message - * @param mixed $data Error data + * @param string $code Error code. + * @param string $message Error message. + * @param mixed $data Error data. */ - public function __construct(string $code = "", string $message = "", $data = "") + public function __construct(string $code = "", string $message = "", mixed $data = "") { if (!empty($code)) { $this->errors[$code][] = $message; @@ -335,7 +335,7 @@ public function __construct(string $code = "", string $message = "", $data = "") /** * Get error message * - * @param string $code Error code + * @param string $code Error code. * @return string Error message */ public function get_error_message(string $code = ""): string @@ -362,10 +362,10 @@ public function get_error_code(): string /** * Mock is_wp_error function for tests * - * @param mixed $thing Value to check - * @return bool True if WP_Error instance + * @param mixed $thing Value to check. + * @return boolean True if WP_Error instance */ - function is_wp_error($thing): bool + function is_wp_error(mixed $thing): bool { return $thing instanceof WP_Error; } @@ -382,7 +382,7 @@ function is_wp_error($thing): bool * * Uses in-memory storage to simulate WordPress transient behaviour. * - * @param string $transient Transient name + * @param string $transient Transient name. * @return mixed Transient value or false if not set/expired */ function get_transient(string $transient) @@ -404,12 +404,12 @@ function get_transient(string $transient) /** * Mock set_transient function for tests * - * @param string $transient Transient name - * @param mixed $value Transient value - * @param int $expiration Expiration in seconds (0 = no expiration) - * @return bool Always returns true + * @param string $transient Transient name. + * @param mixed $value Transient value. + * @param integer $expiration Expiration in seconds (0 = no expiration). + * @return boolean Always returns true */ - function set_transient(string $transient, $value, int $expiration = 0): bool + function set_transient(string $transient, mixed $value, int $expiration = 0): bool { global $wp_mock_transients; $wp_mock_transients[$transient] = [ @@ -424,8 +424,8 @@ function set_transient(string $transient, $value, int $expiration = 0): bool /** * Mock delete_transient function for tests * - * @param string $transient Transient name - * @return bool Always returns true + * @param string $transient Transient name. + * @return boolean Always returns true */ function delete_transient(string $transient): bool { @@ -443,8 +443,8 @@ function delete_transient(string $transient): bool * Uses PHP file_get_contents with stream context to make real HTTP * requests, mimicking WordPress wp_remote_get() response format. * - * @param string $url URL to fetch - * @param array $args Request arguments + * @param string $url URL to fetch. + * @param array $args Request arguments. * @return array|WP_Error Response array or WP_Error on failure */ function wp_remote_get(string $url, array $args = []) @@ -520,8 +520,8 @@ function wp_remote_get(string $url, array $args = []) /** * Mock wp_remote_retrieve_response_code function for tests * - * @param array|WP_Error $response HTTP response array - * @return int|string Response code or empty string on failure + * @param array|WP_Error $response HTTP response array. + * @return integer|string Response code or empty string on failure */ function wp_remote_retrieve_response_code($response) { @@ -536,7 +536,7 @@ function wp_remote_retrieve_response_code($response) /** * Mock wp_remote_retrieve_body function for tests * - * @param array|WP_Error $response HTTP response array + * @param array|WP_Error $response HTTP response array. * @return string Response body or empty string on failure */ function wp_remote_retrieve_body($response): string @@ -552,7 +552,7 @@ function wp_remote_retrieve_body($response): string /** * Mock wp_remote_retrieve_headers function for tests * - * @param array|WP_Error $response HTTP response array + * @param array|WP_Error $response HTTP response array. * @return array Response headers or empty array on failure */ function wp_remote_retrieve_headers($response): array From 6b6b2b5bd655fb966b5939c0db4b9232aa30443c Mon Sep 17 00:00:00 2001 From: Miguel Colmenares Date: Wed, 12 Aug 2026 13:37:28 -0500 Subject: [PATCH 2/2] fix: correct @return tag for _manually_load_plugin() to void Addresses Copilot review feedback -- the function never returns a value, so documenting it as mixed was inaccurate and contradicted the PR's own goal of inferring return tags from actual behavior, not a blanket fallback. --- tests/bootstrap.php | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tests/bootstrap.php b/tests/bootstrap.php index fd47ab0..d4b7722 100644 --- a/tests/bootstrap.php +++ b/tests/bootstrap.php @@ -49,7 +49,8 @@ * * This loads our mock plugin that integrates the WP GitHub Updater package * into a WordPress environment for real integration testing. - * @return mixed + * + * @return void */ function _manually_load_plugin() {