Phpstan Wordpress Laravel Package

Technical Evaluation

Architecture Fit

• Static Analysis Integration: The package extends PHPStan, a static analysis tool, to enforce WordPress-specific coding standards (e.g., hooks, filters, theme functions, and core APIs). This aligns well with Laravel’s emphasis on maintainability and developer experience, especially in projects leveraging WordPress plugins, REST APIs, or custom integrations.
• Complementary to Laravel: While Laravel primarily uses PHPStan via phpstan/extension-installer, this package bridges WordPress-specific logic (e.g., add_action, wp_query, get_template_part) into Laravel’s static analysis pipeline. Useful for:
  • Laravel plugins interacting with WordPress (e.g., headless CMS setups).
  • Hybrid apps using WordPress as a service layer (e.g., via REST API or database).
  • Teams maintaining legacy WordPress codebases while adopting Laravel for new features.
• Non-Invasive: Operates as a PHPStan extension, requiring no core Laravel modifications. Leverages PHPStan’s existing configuration (phpstan.neon), minimizing architectural disruption.

Integration Feasibility

• PHPStan Compatibility: Requires PHPStan v1.10+ (per PHPStan’s WordPress extension docs). Laravel projects using phpstan/extension-installer (v1.1.0+) can auto-install this package via composer require --dev szepeviktor/phpstan-wordpress.
• WordPress Dependency: Critical risk: The package assumes a WordPress environment (e.g., wp-load.php, WP_ globals). In pure Laravel projects, false positives may arise unless:
  • WordPress is bootstrapped (e.g., via wp-load.php in a Laravel service provider).
  • Mocked/stubbed for testing (e.g., using brain/monkey or custom PHPStan stubs).
• Laravel-Specific Challenges:
  • Service Container Conflicts: WordPress’s global $wpdb, $post, etc., may clash with Laravel’s dependency injection. Mitigate via:
    • Namespacing WordPress globals (e.g., WP\ prefix).
    • Conditional loading (e.g., only enable extension in WordPress-integrated modules).
  • Dynamic Hooks: PHPStan struggles with dynamically registered hooks (e.g., add_action called at runtime). Requires manual @method annotations or custom rules.

Technical Risk

Key Questions

1. Scope of WordPress Usage:
   • Is WordPress used as a standalone CMS, a headless backend, or a plugin within Laravel?
   • Are there plans to gradually migrate away from WordPress?
2. CI/CD Integration:
   • How will static analysis results be surfaced (e.g., GitHub PR checks, SonarQube)?
   • Will WordPress-specific rules block PRs, or are they advisory?
3. Team Expertise:
   • Does the team have experience with PHPStan extensions or WordPress internals?
   • Is there budget for custom rule development if gaps are found?
4. Legacy Codebase:
   • What percentage of the codebase interacts with WordPress?
   • Are there existing PHPStan configurations to build upon?
5. Tooling Stack:
   • Is PHPStan already integrated into the project (e.g., via rector, pestphp, or custom scripts)?
   • Are other static analyzers (e.g., Psalm) in use that could conflict?

Integration Approach

Stack Fit

• Primary Use Case: Laravel projects with any of the following:
  • WordPress plugins/themes using Laravel for backend logic.
  • Headless WordPress setups where Laravel consumes the REST API.
  • Hybrid applications sharing a codebase between WordPress and Laravel (e.g., via wp-load.php in a Laravel service provider).
• Secondary Use Case: Teams adopting Laravel while maintaining legacy WordPress codebases, using PHPStan to enforce consistency.
• Unsuitable For:
  • Pure Laravel projects with no WordPress integration.
  • Projects using alternative static analyzers (e.g., Psalm) without PHPStan.

Migration Path

1. Assessment Phase:
   • Audit the codebase for WordPress dependencies (e.g., wp_, add_action, get_posts).
   • Identify modules where WordPress logic resides (isolate if possible).
2. PHPStan Setup:
   • Install phpstan/extension-installer (if not present):

     composer require --dev phpstan/extension-installer
     

   • Add to composer.json:

     "extra": {
       "phpstan": {
         "extension-classes": ["szepeviktor\\phpstan_wordpress\\extension"]
       }
     }
     

   • Configure phpstan.neon:

     includes:
       - vendor/szepeviktor/phpstan-wordpress/extension.neon
     

3. Incremental Rollout:
   • Start with a subset of WordPress-integrated files/modules.
   • Use --level=5 (strict) for new code; --level=3 for legacy.
   • Gradually expand coverage as false positives are resolved.
4. Customization:
   • Override default rules in phpstan.neon:

     rules:
       szepeviktor\WordPress\Rules\DisallowDirectQuery::class: false
     

   • Add @var annotations for dynamic hooks:

     /** @var array<string, callable> $wp_filter */
     

Compatibility

• PHPStan Versions: Tested with PHPStan 1.10+. Downgrade may require manual rule adjustments.
• WordPress Versions: Assumes modern WordPress (5.0+). Older versions may need stubs for missing classes.
• Laravel Versions: No direct conflicts, but:
  • Laravel 10+ uses PHP 8.1+, which PHPStan 1.10+ fully supports.
  • Avoid conflicts with Laravel’s App facade by namespacing WordPress globals.
• Tooling Conflicts:
  • Rector: May need exclusion for WordPress-specific rules.
  • PestPHP: Ensure test suites don’t trigger WordPress bootstrapping.

Sequencing

1. Phase 1: Validation (1–2 weeks)
   • Run PHPStan with default config to identify false positives/negatives.
   • Document known limitations (e.g., unsupported hooks).
2. Phase 2: Configuration (1 week)
   • Customize phpstan.neon to exclude non-WordPress files.
   • Add @var annotations for dynamic logic.
3. Phase 3: CI Integration (1 week)
   • Add PHPStan to CI pipeline (e.g., GitHub Actions):

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

   • Set up as a required check for PRs.
4. Phase 4: Iterative Refinement
   • Address false positives via:
     • Rule overrides.
     • Custom PHPStan rules (e.g., for proprietary hooks).
   • Monitor performance impact (aim for <5s per run).

Operational Impact

Maintenance

• Dependency Updates:
  • Monitor szepeviktor/phpstan-wordpress for breaking changes (MIT license allows forks if needed).
  • Update PHPStan annually (e.g., align with Laravel’s PHP version support).
• Rule Maintenance:
  • Custom rules may require updates if WordPress APIs evolve (e.g., new hook names).
  • Document unsupported features (e.g., "Dynamic add_action with runtime callbacks not analyzed").
• Tooling Drift:
  • If Laravel adopts new static analysis tools (e.g., Psalm), evaluate migration effort.

Support

• Debugging:
  • False positives may require deep WordPress knowledge. Allocate time for:
    • Tracing hook origins (e.g., add_action called in a plugin).
    • Stubbing missing WordPress classes (e.g., WP_Query).
  • Use --generate-baseline to suppress known issues temporarily.
• Community Resources:
  • Limited official docs; rely on:
    • PHPStan WordPress Extension GitHub (if available).
    • WordPress Stack Exchange for hook-specific queries.
    • Laravel/PHPStan communities for hybrid setups.
• Vendor Lock-in:
  • Low risk: MIT license allows forking. However, custom rules may become proprietary.