Shim Laravel Package

Getting Started

Minimal Steps

1. Installation: Add the package to your Laravel project via Composer:

   composer require --dev phpdocumentor/shim:^3
   

   This installs the phpdocumentor.phar into vendor/bin/ as phpdocumentor.

2. First Use Case: Generate basic PHPDoc documentation for your Laravel project:

   vendor/bin/phpdocumentor run -d src --target docs
   

   • -d src: Specifies the source directory (Laravel’s app/ or src/).
   • --target docs: Outputs documentation to a docs/ directory.

3. Where to Look First:

   • Official Documentation: phpDocumentor Docs for CLI options and configuration.
   • Laravel-Specific: Focus on app/ or src/ directories, excluding vendor/, node_modules/, and generated files.
   • CI/CD Integration: Add the command to your .github/workflows/ or gitlab-ci.yml for automated documentation.

Implementation Patterns

Usage Patterns

1. Basic Documentation Generation:

   vendor/bin/phpdocumentor run -d app/Http/Controllers -t docs/api
   

   • Generate docs for a specific namespace (e.g., API controllers).

2. Template Customization: Configure phpdocumentor.dist.php in your project root:

   return [
       'source' => ['app'],
       'target' => 'docs',
       'template' => 'vendor/phpdocumentor/templates-twbsbootstrap',
       'cache' => 'var/cache',
       'parser' => [
           'full_fqcn' => true,
           'filter' => ['@ignore'],
       ],
   ];
   

   • Use built-in templates (e.g., twbsbootstrap for Bootstrap-styled docs).
   • Exclude files with @ignore annotations.

3. CI/CD Integration: Add to composer.json scripts for easy execution:

   "scripts": {
       "post-install-cmd": [
           "@phpdoc-install"
       ],
       "phpdoc-install": "php vendor/bin/phpdocumentor/install"
   }
   

   Run in GitHub Actions:

   - name: Generate Documentation
     run: vendor/bin/phpdocumentor run --processes=2
   

4. Artisan Command Integration (Advanced): Create a custom Artisan command to wrap phpdocumentor:

   // app/Console/Commands/GenerateDocs.php
   namespace App\Console\Commands;
   
   use Illuminate\Console\Command;
   use Symfony\Component\Process\Process;
   
   class GenerateDocs extends Command
   {
       protected $signature = 'docs:generate {--target=docs}';
       protected $description = 'Generate PHPDoc documentation';
   
       public function handle()
       {
           $process = new Process(['vendor/bin/phpdocumentor', 'run', '-d', 'app', '--target=' . $this->option('target')]);
           $process->run();
           $this->output->write($process->getOutput());
       }
   }
   

   Register in app/Console/Kernel.php:

   protected $commands = [
       Commands\GenerateDocs::class,
   ];
   

   Run with:

   php artisan docs:generate --target=docs/custom
   

5. Parallel Processing: Speed up generation in CI/CD with multiple processes:

   vendor/bin/phpdocumentor run --processes=4
   

Workflows

1. Developer Workflow:

   • Generate docs locally during development:

     vendor/bin/phpdocumentor run -d app -t docs/dev
     

   • Preview changes before committing.

2. Release Workflow:

   • Automate doc generation on main branch pushes:

     # .github/workflows/docs.yml
     name: Documentation
     on: [push]
     jobs:
       docs:
         runs-on: ubuntu-latest
         steps:
           - uses: actions/checkout@v4
           - uses: actions/setup-php@v2
             with:
               php-version: '8.2'
           - run: composer install --dev
           - run: vendor/bin/phpdocumentor run --processes=2
     

   • Deploy docs/ to a static host (e.g., GitHub Pages, Netlify).

3. Open-Source Workflow:

   • Include docs in README.md:

     ## Documentation
     [View API Docs](docs/index.html)
     

   • Use phpdocumentor to generate OpenAPI specs for API-first projects.

Integration Tips

1. Exclude Files: Use .phpdoc.dist.php to ignore tests, configs, or generated files:

   return [
       'filter' => [
           'exclude' => [
               'tests/*',
               'config/*',
               'storage/*',
           ],
       ],
   ];
   

2. Custom Annotations: Extend PHPDoc with custom tags (e.g., @see, @method) and configure parsing:

   'parser' => [
       'customTags' => ['see', 'method'],
   ],
   

3. Laravel-Specific:

   • Document service providers, facades, and events:

     vendor/bin/phpdocumentor run -d app/Providers app/Facades -t docs/framework
     

   • Use @mixin for trait documentation.

4. Versioning: Tag releases with docs:

   git tag v1.0.0
   vendor/bin/phpdocumentor run --target=docs/v1.0.0
   

Gotchas and Tips

Pitfalls

1. PHP Version Mismatch:

   • Error: phpdocumentor/shim@^3 requires PHP 8.1+. Laravel <8.33 (PHP 8.0) or <9.x (PHP 7.4) will fail.
   • Fix: Pin to phpdocumentor/shim@^3.9 for PHP 8.0 support or upgrade Laravel.

2. Template Path Changes:

   • Error: Old paths like templates/twbsbootstrap no longer work. Use PSR-12 paths:

     'template' => 'vendor/phpdocumentor/templates-twbsbootstrap',
     

   • Fix: Update phpdocumentor.dist.php and clear cache (rm -rf var/cache).

3. Deprecated APIs:

   • Error: Custom commands using \phpDocumentor\Transformer or event listeners will break.
   • Fix: Migrate to phpDocumentor\Processor:

     // Old
     $transformer = new \phpDocumentor\Transformer\DefaultTransformer();
     
     // New
     $processor = new \phpDocumentor\Processor();
     $processor->process($sourceFiles);
     

4. Composer Conflicts:

   • Error: Installing both phpdocumentor/shim and phpdocumentor/phpdocumentor may cause conflicts.
   • Fix: Remove direct phpdocumentor/phpdocumentor dependency and rely on the shim.

5. Parallel Processing Issues:

   • Error: --processes flag may fail on shared CI runners with low memory.
   • Fix: Start with --processes=2 and monitor resource usage.

6. Annotation Parsing Quirks:

   • Error: Custom annotations (e.g., @api) may not render correctly.
   • Fix: Explicitly declare custom tags in config:

     'parser' => [
         'customTags' => ['api', 'deprecated'],
     ],
     

7. Cache Invalidation:

   • Error: Docs don’t update after code changes due to cached templates.
   • Fix: Clear cache before generation:

     rm -rf var/cache
     vendor/bin/phpdocumentor run
     

Debugging

1. Verbose Output: Enable debug mode for troubleshooting:

   vendor/bin/phpdocumentor run -vvv
   

2. Dry Run: Test configuration without generating files:

   vendor/bin/phpdocumentor run --dry-run
   

3. Log File: Redirect output to a log file:

   vendor/bin/phpdocumentor run > docs/generation.log 2>&1
   

Configuration Quirks

1. Default Config Location:

   • The shim looks for phpdocumentor.dist.php in the project root or vendor/phpdocumentor/.
   • Override with --configuration:

     vendor/bin/phpdocumentor run --configuration=custom.phpdoc.php
     

2. Template Overrides:

   • Copy built-in templates to templates/ and modify:

     cp -r vendor/phpdocumentor/templates-twbsbootstrap templates/custom
     

   • Update config:

     'template' => 'templates/custom',
     

3. Parallel Processing Limits:

   • Default: 4 processes. Adjust based on CI runner specs:

     vendor/bin/phpdocumentor run --process