Wordpress Stubs Laravel Package

Technical Evaluation

Architecture Fit

• Static Analysis Focus: The package remains exclusively designed for static analysis tools (PHPStan, Psalm, IDE autocompletion) and does not modify runtime behavior. This aligns with Laravel-based WordPress plugin/theme projects where static typing and early bug detection are priorities.
• WordPress Integration: Laravel often interacts with WordPress via APIs (REST endpoints, custom post types, hooks), and the stubs provide type safety for core WordPress functions/classes without requiring WordPress to be bootstrapped in static analysis environments.
• Laravel Compatibility: Laravel’s DI container and service providers benefit from static analysis to catch misused WordPress functions (e.g., get_post(), wp_insert_post()). The stubs do not conflict with Laravel’s autoloading or service providers.
• New Release (v7.1.2): Stubs now target WordPress 7.1.2 and include several type‑accuracy fixes (e.g., conditional return types for paginate_links and absint, removal of duplicated tags/shape keys, and corrections for sealed arrays). These improvements increase static‑analysis precision but may surface new type errors in existing code.

Integration Feasibility

• Low Friction: Installation remains a single Composer command (composer require --dev php-stubs/wordpress-stubs), requiring no codebase changes.
• Tooling Agnostic: Works with PHPStan, Psalm, or IDEs (PHPStorm, VSCode with Intelephense). Laravel’s existing static analysis setup can absorb this with minimal configuration.
• Version Alignment: Stubs are version‑locked to WordPress core. The new release (v7.1.2) aligns with WordPress 7.1.2. Ensure your target WordPress version matches; if you are on an older WordPress version, you may need to pin an earlier stub release or accept potential false positives for newer functions.

Technical Risk

• Maintainer Sustainability: The project now shows active maintenance (recent PRs from multiple contributors, including IanDelMar and PeterSmith8nss). The previous assessment noted an abandonment signal; that risk is significantly reduced but not eliminated. Continue to monitor release cadence and consider a fork as a contingency.
• Global Exclusion: Stubs do not include WordPress globals (e.g., $wpdb, $post). If your Laravel plugin relies on globals, you’ll need custom stubs or refactoring (e.g., dependency injection for $wpdb).
• IDE Limitations: Some IDEs may ignore stubs without explicit configuration. Test with your primary IDE/tooling stack pre‑integration; fallback to PHPStan/Psalm for critical checks.
• Static Analysis Drift: The type‑accuracy fixes in v7.1.2 (e.g., conditional return types) may change inferred types and cause new PHPStan/Psalm errors in previously clean code. Plan for a re‑baseline after upgrading.

Key Questions

1. WordPress Version Support: Does your project target WordPress 7.1.2? If yes, v7.1.2 is the correct stub version. If not, pin to the stub version matching your target.
2. Static Analysis Maturity: Does your team already use PHPStan/Psalm? If not, assess ramp‑up effort (configuration, learning curve).
3. Global Dependencies: Does your code rely on WordPress globals (e.g., $wp_query)? If yes, evaluate custom stubs or refactoring.
4. CI/CD Integration: Will static analysis run in CI pipelines? Benchmark performance impact (stubs add ~1MB to analysis).
5. Upgrade Impact: After upgrading to v7.1.2, re‑run static analysis and review new type errors introduced by more precise return types (especially around paginate_links, absint, and sealed arrays).

Integration Approach

Stack Fit

• Laravel + WordPress: Ideal for plugins/themes using Laravel’s routing, Eloquent ORM, or Blade templates alongside WordPress core. Example: a Laravel‑powered custom block editor or REST API plugin can use stubs to validate WordPress function calls.
• Static Analysis Tools:
  • PHPStan: Pair with szepeviktor/phpstan-wordpress.
  • Psalm: Configure <stubs> in psalm.xml to include wordpress-stubs.php.
  • IDE Autocompletion: Useful for VSCode/PhpStorm if WordPress core parsing is slow.
• Composer Workflow: Stubs are a dev dependency; they won’t bloat production builds.
• New Release Compatibility: v7.1.2 is a drop‑in replacement for prior versions, but because it includes type refinements, expect new static‑analysis findings (not runtime breaks).

Migration Path

1. Assessment Phase:
   • Run PHPStan/Psalm without stubs to establish a baseline.
   • Example:

     composer require --dev phpstan/phpstan php-stubs/wordpress-stubs
     vendor/bin/phpstan analyse --level=5 src/
     

2. Stubs Integration:
   • Add stubs to static analysis config:
     • PHPStan: Install szepeviktor/phpstan-wordpress.
     • Psalm: Update psalm.xml:

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

   • Exclude WordPress core files from analysis to avoid conflicts.
3. Upgrade to v7.1.2:
   • Update the stub package: composer update php-stubs/wordpress-stubs.
   • Re‑run static analysis, review new errors, and adjust code or suppress known false positives.
4. Incremental Adoption:
   • Start with critical paths (plugin initialization, REST endpoints).
   • Gradually expand to legacy code as stubs reveal type issues.
5. CI/CD Pipeline:
   • Add static analysis as a pre‑commit hook or CI gate (e.g., GitHub Actions):

     - name: Run PHPStan
       run: vendor/bin/phpstan analyse --level=5
     

Compatibility

• PHP Version: Requires PHP 7.4+ (aligns with Laravel 8+/WordPress 5.6+).
• WordPress Version: Stubs are version‑specific; v7.1.2 targets WordPress 7.1.2. Verify your plugin/theme’s target WordPress version before upgrading.
• Tooling Conflicts:
  • Avoid mixing stubs with WordPress core’s built‑in PHPDoc (stubs override runtime behavior in static analysis only).
  • Test with Laravel Mix/Vite if using custom build steps (stubs are pure PHP, no conflicts).
• Type Refinements: v7.1.2 changes several type signatures (e.g., paginate_links conditional return, absint conditional return). These are static‑analysis‑only changes and do not affect runtime, but they may require code adjustments to satisfy stricter type checks.

Sequencing

1. Phase 1: Setup (1–2 days)
   • Install stubs and configure PHPStan/Psalm.
   • Resolve initial false positives.
2. Phase 2: Upgrade & Validation (1 week)
   • Upgrade to v7.1.2.
   • Run analysis on core plugin logic (hooks, REST routes).
   • Fix critical type errors surfaced by the new stubs.
3. Phase 3: Expansion (Ongoing)
   • Extend to legacy code or third‑party integrations.
   • Customize stubs if needed (e.g., for plugin‑specific globals).

Operational Impact

Maintenance

• Low Effort: Stubs are automatically updated via Composer. No runtime maintenance required.
• Active Project: Recent releases and community PRs indicate healthy maintenance. Still, monitor for forks or changes in cadence.
• Customization: Extend stubs for plugin‑specific classes using php-stubs/generator. Avoid overriding vendor stubs directly.

Support

• Troubleshooting:
  • New type errors: After upgrading to v7.1.2, expect additional findings from stricter conditional return types. Use @phpstan-ignore-next-line for known edge cases or update code to match accurate types.
  • IDE issues: Configure your editor to prioritize stubs over WordPress core parsing.
• Community Resources: GitHub issues for stub accuracy; PHPStan/Psalm docs for tool‑specific quirks.

Scaling

• Performance: Stubs add ~1MB to static analysis. Benchmark with --memory-limit=512M. CI/CD impact is minimal if cached.
• Team Adoption: Provide a cheat sheet for common stub use cases (e.g., wp_insert_post() return types). Emphasize static analysis as a safety net.
• Large Codebases: Use incremental analysis and exclude vendor/WordPress from analysis to avoid noise.

Failure Modes