Facade Documenter Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require laravel/facade-documenter --dev
   

   Register the service provider in config/app.php under providers (if not auto-discovered):

   Laravel\FacadeDocumenter\ServiceProvider::class,
   

2. First Use Case Run the facades:document command to generate docblocks for all Laravel facades in your project:

   php artisan facades:document
   

   This will create/update app/Facades/ with documented facade stubs.

3. Where to Look First

   • Check the generated app/Facades/ directory for updated stubs.
   • Review the config/facade-documenter.php for customization options.
   • Inspect the src/Documenter.php for core logic if extending functionality.

Implementation Patterns

Usage Patterns

1. Generating Facade Stubs

   • Run php artisan facades:document to update all facades.
   • Exclude specific facades by adding them to config/facade-documenter.php:

     'exclude' => [
         'Auth',
         'Cache',
     ],
     

2. Customizing Docblock Format Modify the template in resources/views/vendor/facade-documenter/facade.blade.php to adjust docblock structure, e.g., adding @throws or @method tags.

3. Integrating with IDE

   • Place generated stubs in app/Facades/ (IDE-aware path).
   • Use php artisan facades:document in your CI/CD pipeline to keep stubs updated.

4. Workflow Integration

   • Add a post-update hook in composer.json to auto-generate stubs:

     "scripts": {
         "post-update-cmd": "php artisan facades:document"
     }
     

5. Testing Facades Use the generated stubs in tests to avoid runtime dependency issues:

   use App\Facades\AuthFacade; // Auto-complete works here
   

Workflows

• Onboarding New Developers: Generate stubs once and commit to version control.
• Refactoring: Update stubs after modifying facades to reflect new methods.
• Legacy Projects: Backfill stubs for existing facades to enable IDE features.

Gotchas and Tips

Pitfalls

1. Stub Overwrites

   • Generated files in app/Facades/ may be overwritten on re-generation. Commit them to avoid surprises.
   • Use php artisan facades:document --force to skip existing files (not recommended for production).

2. Dynamic Facades

   • Facades with dynamic methods (e.g., Facade::method($param)) may not document correctly. Exclude or manually stub these.

3. IDE Caching

   • Some IDEs (e.g., PHPStorm) cache stubs aggressively. Restart the IDE or invalidate caches after updates.

4. Namespace Conflicts

   • Ensure app/Facades/ is in your autoload path (composer.json). Add if missing:

     "autoload": {
         "psr-4": {
             "App\\Facades\\": "app/Facades/"
         }
     }
     

Debugging

• Missing Methods: Verify the facade’s underlying class has the method (e.g., Auth::attempt() relies on Illuminate\Auth\AuthManager).
• Template Errors: Check resources/views/vendor/facade-documenter/ for syntax issues.
• Command Failures: Run with --verbose for debug output:

  php artisan facades:document --verbose
  

Tips

1. Partial Updates Use --facade to update a single facade:

   php artisan facades:document --facade=Auth
   

2. Custom Templates Override the default template by publishing it:

   php artisan vendor:publish --tag=facade-documenter-views
   

3. Exclude Non-Laravel Facades Filter out third-party facades by adjusting the config/facade-documenter.php:

   'facades' => [
       'Illuminate\\*',
       'App\\Facades\\*',
   ],
   

4. CI/CD Optimization Skip docblock generation in CI if stubs are committed:

   if [ "$CI" != "true" ]; then php artisan facades:document; fi
   

5. Legacy Facades For facades not auto-detected, manually add their class paths to the config:

   'facades' => [
       'App\\Facades\\CustomFacade' => 'App\\Services\\CustomService',
   ],