Wordpress Globals Laravel Package

Getting Started

This package is not a runtime library — it is a static-analysis stub set. Its only job is to teach PHPStan/Psalm about WordPress's ambient globals ($wpdb, $post, $current_user, $wp_query, etc.) and the constants WordPress defines at bootstrap (ABSPATH, WP_CONTENT_DIR, WP_DEBUG, MINUTE_IN_SECONDS, …). Treat it as a dev dependency you wire into your analyzer, not something your plugin ships.

Minimal setup:

1. Install alongside the function/class stubs (the two are complementary):

   composer require --dev php-stubs/wordpress-globals php-stubs/wordpress-stubs
   

2. Register the stub with PHPStan. scanFiles is the correct bucket — it makes the declared symbols visible without executing the file:

   parameters:
       scanFiles:
           - vendor/php-stubs/wordpress-globals/wordpress-globals.php
           - vendor/php-stubs/wordpress-stubs/wordpress-stubs.php
   

3. For Psalm, add it as a stub file:

   <stubs>
       <file name="vendor/php-stubs/wordpress-globals/wordpress-globals.php"/>
   </stubs>
   

Where to look first: open vendor/php-stubs/wordpress-globals/ and grep the single stub file for the exact symbol you're chasing. That file is the entire package — there is no service provider, no runtime code, no config surface. If a constant or global is not in that file, it will not be fixed by the package.

First use case: activating PHPStan on a plugin bootstrapper that references ABSPATH, WP_PLUGIN_DIR, and $wpdb. Before the stubs you get "Constant ABSPATH not found" and "Variable $wpdb might not be defined"; after wiring, those disappear and the remaining errors are real code issues.

Implementation Patterns

• Layer two stub packages, not one. wordpress-stubs covers functions/classes; wordpress-globals covers constants/globals. Register both in the same scanFiles array. Using only one leaves half of WordPress invisible to the analyzer.
• Commit phpstan.neon.dist / psalm.xml with the stub paths, and run analysis in CI (vendor/bin/phpstan analyse --no-progress). This is the day-to-day payoff: every PR gets WordPress-aware static analysis without each developer configuring their editor.
• Type the database global explicitly. The stub declares $wpdb exists, but precise inference inside functions still depends on scope. In hot spots, write:

  global $wpdb;
  /** @var \wpdb $wpdb */
  $rows = $wpdb->get_results( $sql );
  

  This gives you IDE completion and return-type checks on query results.
• Create a project-level stub for third-party globals. WooCommerce, ACF, and other plugins add their own constants. Keep a stubs/project-globals.php in your repo and append it to scanFiles rather than forking this package.
• Baseline first, then ratchet. On a legacy codebase, wire the stubs, run --generate-baseline, commit the baseline, and fail CI on new errors only. This lets you adopt the package without a 3,000-error cleanup.
• Reuse the analyzer config for editors. PhpStorm and the VS Code PHPStan extension read the same phpstan.neon; once the stub paths are committed, in-editor "undefined constant" noise disappears for the whole team.
• Composer script hygiene:

  "scripts": { "analyse": "phpstan analyse" },
  "require-dev": { "php-stubs/wordpress-globals": "^1.0", "php-stubs/wordpress-stubs": "^5.5" }
  

  Keep both in require-dev and deploy with composer install --no-dev.
• Use it as a reference, not just a suppressor. When unsure which constants WordPress guarantees at a given lifecycle point, the stub file is a fast checklist of core-defined names.

Gotchas and Tips

• Staleness is the headline risk. The last release is August 2020 (roughly WordPress 5.5-era constants). Anything added to core since — newer block/theme constants, WP_DEVELOPMENT_MODE, and similar — will be missing. Symptom: "Constant X not found" for a legitimate modern core constant. Fix by adding your own define()/const declarations in a project stub and appending it to scanFiles.
• Never use bootstrapFiles or Composer autoload for this file. bootstrapFiles executes the stub, and if the stub unconditionally defines ABSPATH or other constants it can corrupt WordPress bootstrap order or trigger "already defined" notices. Analysis-only means scanFiles (PHPStan) or <stubs> (Psalm).
• Check the package's composer.json autoload section before deploying. If it ever autoloads the stub file, exclude it in production — the file is meant to be parsed, not run.
• Global variables are only partly solved. PHPStan's model of $GLOBALS is limited. The stub declares that $wpdb exists; it does not make $wpdb magically in-scope inside a function that forgot global $wpdb;. That warning is usually a real bug — fix the code, don't suppress it.
• Unconditional constant declarations hide branching. If your code does if ( defined( 'WP_DEBUG' ) ), the analyzer now assumes it is always defined and may prune the else branch. That's acceptable for analysis but can mask runtime paths; use PHPStan's dynamicConstantNames when a constant is genuinely runtime-defined rather than core-defined.
• scanFiles vs stubFiles: scanFiles adds symbols to the symbol table; stubFiles overrides signatures of things the analyzer already knows. For constants and globals, scanFiles is what you want. Mixing them up produces "symbol already exists" or no effect at all.
• Paths are relative to the config file, not the working directory. If CI reports "File not found" for the stub, that's the usual cause.
• Pin the version. The package is dormant; avoid dev-master drift between local and CI. A tag or commit hash keeps analysis reproducible.
• Don't expect Psalm and PHPStan parity. Constants declared via define() inside a stub are picked up by both, but edge-case inference (conditional defines, $GLOBALS array access) differs. Run both if you use both; don't assume a clean PHPStan run means a clean Psalm run.
• Extension point is just the array. There is no plugin hook or config schema here — extending coverage means adding more stub files to scanFiles. Keep project-specific stubs in your repo so upgrades of this package never overwrite them.
• False confidence warning: silencing "undefined constant" errors is not type safety. Pair this package with a strict rule level and a baseline; otherwise the only thing you've bought is a quieter log.