Wordpress Stubs Laravel Package

Getting Started

Minimal Setup for Laravel + WordPress Plugin/Theme Development

1. Install the stubs in your Laravel project (or WordPress plugin/theme):

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

   Place this in dev-dependencies to avoid bloating production builds.

2. Configure PHPStan (if using it):

   • Install the WordPress extension:

     composer require --dev szepeviktor/phpstan-wordpress
     

   • Add to phpstan.neon:

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

3. First Use Case: Run PHPStan on a WordPress plugin file:

   ./vendor/bin/phpstan analyse app/Plugins/MyPlugin/Classes/MyClass.php
   

   Expect warnings about undefined WordPress functions/classes (e.g., wp_insert_post()) to disappear.

Quick IDE Integration (VSCode/PhpStorm)

• VSCode (Intelephense): Add to .intelephense.config.js:

  module.exports = {
      stubs: ['vendor/php-stubs/wordpress-stubs/wordpress-stubs.php'],
  };
  

• PhpStorm: Go to Settings > PHP > Include Paths and add the stubs file.

Implementation Patterns

1. Static Analysis Workflows

Laravel + WordPress Plugin Hybrid Projects

• Directory Structure:

  /app
    /Plugins
      /MyPlugin
        /Classes
          MyCustomPostType.php  <-- Target for static analysis
        my-plugin.php          <-- WordPress plugin bootstrap
  

• PHPStan Configuration (phpstan.neon):

  parameters:
      level: 8
      paths:
          - app/Plugins
      excludePaths:
          - vendor
          - node_modules
  includes:
      - vendor/szepeviktor/phpstan-wordpress/extension.neon
  

Workflow:

1. Develop: Write WordPress logic in Laravel classes (e.g., MyCustomPostType::create()).
2. Analyze:

   ./vendor/bin/phpstan analyse --memory-limit=1G app/Plugins
   

3. Fix: Resolve stub-related errors (e.g., missing @param tags for wp_insert_post()).

2. Integration with Laravel Services

Example: WordPress Repository Pattern

// app/Services/WPPostService.php
namespace App\Services;

use WP_Post;

class WPPostService {
    public function createPost(array $data): WP_Post {
        $post_id = wp_insert_post($data); // No IDE warnings now!
        return get_post($post_id);
    }
}

• Static Analysis Benefit: PHPStan will validate:
  • Return type of wp_insert_post() (int).
  • Parameter types for $data (e.g., array{title: string, content: string}).

3. Psalm Integration

psalm.xml Configuration:

<projectFiles>
    <directory name="app/Plugins" />
    <exclude-name>*.blade.php</exclude-name>
</projectFiles>
<stubs>
    <file name="vendor/php-stubs/wordpress-stubs/wordpress-stubs.php" />
</stubs>

• Key: Exclude WordPress core files from <projectFiles> to avoid conflicts.

4. CI/CD Pipeline

Add to .github/workflows/phpstan.yml:

name: PHPStan
on: [push, pull_request]
jobs:
  phpstan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
      - run: composer install --dev
      - run: ./vendor/bin/phpstan analyse --memory-limit=1G app/Plugins

Gotchas and Tips

Pitfalls

1. Globals Are Excluded:

   • Stubs do not include WordPress globals like $wpdb, $post, or $wp_query.
   • Workaround: Use dependency injection or static analysis tools like Psalm’s @var annotations.

     /** @var \wpdb $wpdb */
     global $wpdb;
     

2. Private Methods Missing:

   • Stubs exclude private methods (e.g., WP_Query::privateMethod()).
   • Workaround: Use interfaces or abstract classes for public APIs.

3. Version Mismatches:

   • Stubs are tied to WordPress versions. If your project uses WordPress 6.9.1 but stubs are for 6.8.0, expect errors.
   • Fix: Update stubs or pin the WordPress core version in your project.

4. IDE Lag:

   • Large stub files (e.g., wordpress-stubs.php) can slow down IDEs like PhpStorm.
   • Tip: Use .phpstorm.meta.php to exclude the stubs file from indexing:

     return [
         'exclude' => [
             'vendor/php-stubs/wordpress-stubs/wordpress-stubs.php',
         ],
     ];
     

Debugging Tips

1. False Positives:

   • If PHPStan flags wp_insert_post() as "undefined," ensure:
     • The stubs are loaded (check composer.json).
     • The WordPress extension (szepeviktor/phpstan-wordpress) is installed.
   • Debug Command:

     ./vendor/bin/phpstan analyse --debug app/Plugins/MyPlugin.php
     

2. Custom WordPress Functions:

   • For custom functions (e.g., my_custom_function()), add PHPDoc blocks:

     /**
      * @param string $arg
      * @return int
      */
     function my_custom_function(string $arg): int { ... }
     

3. Psalm-Specific Issues:

   • If Psalm complains about "undefined class WP_Post," ensure:
     • The stubs file is listed in <stubs>.
     • WordPress core files are not in <projectFiles>.

Extension Points

1. Custom Stubs:

   • Extend stubs for your plugin’s classes. Example:

     // app/Stubs/MyPluginStubs.php
     namespace App\Stubs;
     
     /**
      * @method static \App\Plugins\MyPlugin\MyClass create()
      */
     class MyPluginStubs {}
     

   • Load in PHPStan:

     includes:
         - vendor/szepeviktor/phpstan-wordpress/extension.neon
         - app/Stubs/MyPluginStubs.php
     

2. PHPStan Rules:

   • Create custom rules to enforce WordPress-specific patterns:

     // rules/MyPlugin/NoDirectWPFunctionsRule.php
     namespace MyPlugin\Rules;
     
     use PHPStan\Rules\Rule;
     use PHPStan\Node\Expr\FuncCallNode;
     
     class NoDirectWPFunctionsRule implements Rule {
         public function getNodeTypeNames(): array {
             return [FuncCallNode::class];
         }
     
         public function processNode(FuncCallNode $node): array {
             $functionName = $node->getFunction()->getName();
             if (str_starts_with($functionName, 'wp_')) {
                 return [$node->getFunction(), "Avoid direct WP functions; use services instead."];
             }
             return [];
         }
     }
     

3. Generating Stubs for Custom WordPress Versions:

   • Fork the generator repo and regenerate stubs for your WordPress version:

     git clone https://github.com/php-stubs/generator
     cd generator
     composer require johnpbloch/wordpress:6.9.1
     ./generate.sh
     

Performance Tips

1. Cache Stubs:

   • PHPStan/Psalm cache stubs between runs. Clear caches if stubs update:

     ./vendor/bin/phpstan clear-cache
     

2. Exclude Tests:

   • Add to phpstan.neon:

     excludePaths:
         - tests/
         - vendor/
     

3. Parallel Analysis:

   • Use --parallel for large codebases:

     ./vendor/bin/phpstan analyse --parallel --memory-limit=2G app/Plugins