Wordpress Stubs Laravel Package

Technical Evaluation

Architecture Fit

• Static Analysis Focus: The package is exclusively designed for static analysis tools (PHPStan, Psalm, IDE autocompletion) and does not modify runtime behavior. This aligns perfectly with Laravel-based WordPress plugin/theme projects where static typing and early bug detection are priorities.
• WordPress Integration: Since Laravel often interacts with WordPress via APIs (e.g., REST endpoints, custom post types, or hooks), the stubs provide type safety for core WordPress functions/classes without requiring WordPress to be bootstrapped in static analysis environments.
• Laravel Compatibility: Laravel’s dependency injection and service container can 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.

Integration Feasibility

• Low Friction: Installation is a single Composer command (composer require --dev php-stubs/wordpress-stubs), requiring no codebase changes.
• Tooling Agnostic: Works with PHPStan, Psalm, or IDEs (e.g., 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, ensuring compatibility with the WordPress version your Laravel plugin/theme targets.

Technical Risk

• Maintainer Sustainability: The author has signaled intent to abandon the project (see README). Risk mitigation:
  • Fork the repo to self-host updates if WordPress version support becomes critical.
  • Monitor for community forks (e.g., szepeviktor/phpstan-wordpress already depends on it).
• Global Exclusion: Stubs do not include WordPress globals (e.g., $wpdb, $post). Risk:
  • If your Laravel plugin relies on globals, you’ll need custom stubs or runtime checks.
  • Mitigation: Use dependency injection (e.g., pass $wpdb as a service) to avoid globals.
• IDE Limitations: Some IDEs (e.g., VSCode) may ignore stubs without explicit configuration. Risk:
  • Test with your primary IDE/tooling stack pre-integration.
  • Fallback: Use PHPStan/Psalm for critical checks if IDE support is unreliable.

Key Questions

1. WordPress Version Support:
   • What WordPress version does your Laravel plugin/theme target? Ensure the stubs match (e.g., v7.0.0 for WP 6.9).
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? If so, benchmark performance impact (stubs add ~1MB to analysis).
5. Long-Term Maintenance:
   • Is there a backup plan if the maintainer abandons the project? (Forking, alternative tools like johnpbloch/wordpress-core?)

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 (e.g., wp_insert_post()).
• Static Analysis Tools:
  • PHPStan: Pair with szepeviktor/phpstan-wordpress for WordPress-specific rules.
  • 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: Since stubs are a dev dependency, they won’t bloat production builds.

Migration Path

1. Assessment Phase:
   • Run PHPStan/Psalm without stubs to identify current type errors (baseline).
   • Example command:

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

2. Stubs Integration:
   • Add stubs to your 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. Incremental Adoption:
   • Start with critical paths (e.g., plugin initialization, REST endpoints).
   • Gradually expand to legacy code as stubs reveal type issues.
4. 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 (e.g., v7.0.0 for WP 6.9). Ensure your target WordPress version has matching stubs.
• 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).

Sequencing

1. Phase 1: Setup (1–2 days)
   • Install stubs and configure PHPStan/Psalm.
   • Resolve initial false positives (e.g., undefined functions due to missing stubs).
2. Phase 2: Validation (1 week)
   • Run analysis on core plugin logic (e.g., hooks, REST routes).
   • Fix critical type errors (e.g., wrong return types for get_post()).
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 (if version-aligned with WordPress).
  • No runtime maintenance required (pure static analysis).
• Customization:
  • Extend stubs for plugin-specific classes (e.g., custom post types) using php-stubs/generator.
  • Override stubs in vendor/ if needed (not recommended for shared projects).
• Dependency Updates:
  • Monitor WordPress core updates to ensure stub compatibility.
  • Watch for forks if the original package is abandoned.

Support

• Troubleshooting:
  • False positives: Common in early adoption (e.g., WP_Error vs. false return types). Mitigate with:
    • @phpstan-ignore-next-line for known edge cases.
    • Custom PHPStan rules to refine stub behavior.
  • IDE issues: Configure your editor to prioritize stubs over WordPress core parsing.
• Community Resources:
  • GitHub issues for stub accuracy (e.g., missing functions).
  • PHPStan/Psalm docs for tool-specific quirks.

Scaling

• Performance:
  • Analysis overhead: Stubs add ~1MB to static analysis. Benchmark with:
    • vendor/bin/phpstan analyse --memory-limit=512M.
  • CI/CD impact: Minimal if cached (e.g., GitHub Actions cache).
• Team Adoption:
  • Onboarding: Provide a cheat sheet for common stub use cases (e.g., wp_insert_post() return types).
  • Cultural shift: Emphasize static analysis as a safety net, not a blocker.
• Large Codebases:
  • Use incremental analysis (e.g., --autoload-file for Laravel’s PSR-4 paths).
  • Exclude vendor/WordPress from analysis to avoid noise.

Failure Modes