Phan Extensions Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require drenso/phan-extensions
   

   Add the package to your project's composer.json dependencies.

2. Configure Phan: Update your phan.config.php to include the plugins and stubs:

   return [
       'plugins' => [
           __DIR__ . '/vendor/drenso/phan-extensions/Plugin/Annotation/SymfonyAnnotationPlugin.php',
           __DIR__ . '/vendor/drenso/phan-extensions/Plugin/DocComment/InlineVarPlugin.php',
           __DIR__ . '/vendor/drenso/phan-extensions/Plugin/DocComment/MethodPlugin.php',
       ],
       'directory_list' => [
           __DIR__ . '/vendor/drenso/phan-extensions/Stubs',
       ],
       'exclude_analysis_directory_list' => [
           __DIR__ . '/vendor/drenso/phan-extensions/Stubs',
       ],
   ];
   

3. Run Phan:

   vendor/bin/phan
   

First Use Case

Symfony Annotations: If your project uses Symfony-style annotations (e.g., @Route, @ParamConverter), enable SymfonyAnnotationPlugin to suppress false positives for unused annotations and ensure proper imports are detected.

Implementation Patterns

Plugin Integration

1. SymfonyAnnotationPlugin:

   • Use Case: Projects using Symfony annotations (e.g., Doctrine, SensioFrameworkExtraBundle).
   • Workflow:
     • Add the plugin to phan.config.php.
     • Phan will now recognize and validate Symfony-style annotations (e.g., @Route("/path")).
     • Unused annotations will not trigger warnings if they are correctly imported.
   • Example:

     use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
     
     /**
      * @Route("/example")
      */
     public function exampleAction() {}
     

2. DocComment Plugins:

   • InlineVarPlugin: Fixes false positives for inline type hints in docblocks (e.g., @var string $foo).
     • Scan /src directory for classes and validate inline doc comments.
   • MethodPlugin/ThrowsPlugin: Ensure @method and @throws annotations are respected.
     • Useful for legacy codebases with manual PHPDoc annotations.

3. Stub Integration:

   • Use Case: Extending Phan's type checking for core PHP extensions (e.g., curl, intl).
   • Workflow:
     • Add stubs to directory_list and exclude them from analysis.
     • Phan will now recognize types/methods from these extensions without false positives.
   • Example:

     $ch = curl_init(); // No "Undefined variable" warning
     

Workflow Tips

• Incremental Analysis: Run Phan on a subset of files during development:

  vendor/bin/phan --directory=src/Controller
  

• Custom Stubs: Extend existing stubs for project-specific extensions (e.g., custom PHP libraries).
• CI Integration: Add Phan to your CI pipeline (e.g., GitHub Actions) to catch issues early:

  - name: Run Phan
    run: vendor/bin/phan --allow-testing-code
  

Gotchas and Tips

Pitfalls

1. Plugin Compatibility:

   • SymfonyAnnotationPlugin: Ignores @Annotation, @Target, @Required, and @SuppressWarnings by default. Customize via subclassing if needed.
   • ThrowsPlugin: Obsolete in Phan ≥0.12.3 (use built-in support instead).

2. Stub Conflicts:

   • Overlapping stubs (e.g., custom vs. package stubs) may cause type conflicts. Prioritize stubs in directory_list order.
   • Example: If both pdo stubs exist in Stubs and a vendor package, Phan uses the first match.

3. Performance:

   • Plugins like InlineVarPlugin add overhead. Disable unused plugins in phan.config.php:

     'plugins' => [__DIR__ . '/vendor/drenso/phan-extensions/Plugin/Annotation/SymfonyAnnotationPlugin.php'],
     

Debugging

• False Positives:

  • Use --suppress-issues to ignore specific warnings temporarily:

    vendor/bin/phan --suppress-issues=UnusedPrivateMethod
    

  • Check Phan’s issue tracker for known limitations (e.g., @var in docblocks).

• Plugin Debugging:

  • Enable verbose output to trace plugin execution:

    vendor/bin/phan -vvv
    

  • Inspect Phan’s internal state with --dump-autoloader or --dump-config.

Extension Points

1. Custom Plugins:

   • Extend SymfonyAnnotationPlugin to support additional annotation formats:

     class CustomAnnotationPlugin extends SymfonyAnnotationPlugin {
         protected function getIgnoredAnnotations(): array {
             return array_merge(parent::getIgnoredAnnotations(), ['@CustomAnnotation']);
         }
     }
     

   • Register in phan.config.php:

     'plugins' => [__DIR__ . '/app/Phan/CustomAnnotationPlugin.php'],
     

2. Stub Customization:

   • Override stubs for project-specific extensions (e.g., vendor/custom-lib/Stubs).
   • Example: Add a stub for a custom Monolog handler:

     // vendor/custom-lib/Stubs/Monolog/Handler/CustomHandler.php
     class CustomHandler extends \Monolog\Handler\AbstractHandler {}
     

3. Phan Configuration:

   • Combine with other Phan plugins (e.g., phan/phan for Laravel support):

     'plugins' => [
         __DIR__ . '/vendor/drenso/phan-extensions/Plugin/Annotation/SymfonyAnnotationPlugin.php',
         __DIR__ . '/vendor/phan/phan/Plugin/LaravelPlugin.php',
     ],
     

Maintenance Notes

• Archived Package: Since the project is no longer maintained, consider:
  • Forking and updating for newer Phan versions (e.g., ≥1.0).
  • Replacing with alternatives like phan/phan for active development.
• Phan Version: Ensure compatibility with your Phan version (e.g., phan/phan:^3.0 for modern setups).