Getting Started

Minimal Steps

Installation: Add the package to your Laravel project via Composer:
```
composer require --dev phpdocumentor/shim:^3
```
This installs the phpdocumentor.phar binary into vendor/bin/, making it immediately available globally in your project.
First Use Case: Generate PHPDoc documentation for your Laravel project:
```
vendor/bin/phpdocumentor -d src --target docs/output
```
This creates a docs/output directory with HTML documentation based on PHPDoc annotations in your src/ directory.
Key Files to Know:
- vendor/bin/phpdocumentor: The executable PHAR file.
- phpdocumentor.dist.php: Default configuration file (located in vendor/phpdocumentor/).
- vendor/phpdocumentor/templates-*: Default template files (e.g., Twig/Mustache).

Where to Look First

phpDocumentor Official Docs: For CLI usage, configuration, and advanced features.
Laravel-Specific Integration Guide: If available, for Laravel-specific tips (e.g., Artisan commands, caching).
phpdocumentor.dist.php: Customize paths, templates, or output formats here.

Implementation Patterns

Usage Patterns

1. CI/CD Integration

Add a step to your GitHub Actions/GitLab CI pipeline to generate docs on push or pull_request:

# .github/workflows/docs.yml
jobs:
  generate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-php@v3
        with:
          php-version: '8.2'
      - run: composer install --dev
      - run: vendor/bin/phpdocumentor -d src --target docs/output --processes=4
      - uses: actions/upload-artifact@v3
        with:
          name: documentation
          path: docs/output

Tip: Use --processes=4 to leverage parallel processing (v3.10.0+).

2. Artisan Command Wrapper

Create a custom Artisan command to abstract phpdocumentor usage:

// app/Console/Commands/GenerateDocs.php
namespace App\Console\Commands;

use Illuminate\Console\Command;
use Symfony\Component\Process\Process;

class GenerateDocs extends Command
{
    protected $signature = 'doc:generate {--target=docs/output : Output directory}';
    protected $description = 'Generate PHPDoc documentation for the Laravel project';

    public function handle()
    {
        $process = new Process(['vendor/bin/phpdocumentor', '-d', 'src', '--target=' . $this->option('target')]);
        $process->run();
        $this->output->write($process->getOutput());
    }
}

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

Now run docs with:

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

3. Template Customization

Override default templates by copying them from vendor/phpdocumentor/templates-* to a local directory (e.g., resources/phpdocumentor/templates) and configuring phpdocumentor.dist.php:

// phpdocumentor.dist.php
return [
    'templates' => [
        'path' => __DIR__ . '/../../resources/phpdocumentor/templates',
    ],
];

4. OpenAPI/Swagger Generation

Use @OA\* annotations in your Laravel controllers and generate OpenAPI specs:

// app/Http/Controllers/API/UserController.php
use OpenApi\Annotations as OA;

/**
* @OA\Get(
*     path="/api/users",
*     summary="Get all users",
*     @OA\Response(response="200", description="List of users")
* )
*/

Generate the OpenAPI spec:

vendor/bin/phpdocumentor -d src --target=docs/openapi --format=openapi

Workflows

Daily Development

Local Documentation:
```
vendor/bin/phpdocumentor -d src --target=docs/dev
```
Serve the output locally with a tool like php -S localhost:8000 -t docs/dev.

Incremental Updates: Use --filter to regenerate only changed files:

vendor/bin/phpdocumentor -d src --target=docs/output --filter="App\\Controllers\\*"

Release Workflows

Pre-Release Check: Add a script to verify documentation builds before merging:

composer require --dev phpdocumentor/shim:^3
vendor/bin/phpdocumentor -d src --target=docs/output --validate

Post-Release Deployment: Automate documentation deployment (e.g., to a static hosting service like Netlify or GitHub Pages):
```
vendor/bin/phpdocumentor -d src --target=docs/output --theme=dark
gh-pages -d docs/output  # Using gh-pages package
```

Integration Tips

Laravel Mix/Webpack: If using Laravel Mix, add a custom webpack rule to process documentation artifacts:
```
// webpack.mix.js
mix.copy('docs/output', 'public/docs');
```

Laravel Forge/Envoyer: Deploy documentation alongside your Laravel app by adding a deploy hook:

# Envoyer post-deploy hook
cd /var/www/project && vendor/bin/phpdocumentor -d src --target=docs/output

Laravel Scout/Algolia: Index PHPDoc metadata for searchability:
```
// Use a custom script to parse PHPDoc and push to Algolia
```

Gotchas and Tips

Pitfalls

PHP Version Mismatch:
- Issue: phpdocumentor/shim requires PHP 8.1+ (v3.10.0+). Older versions (e.g., PHP 8.0) may fail with cryptic errors.
- Fix: Pin to phpdocumentor/shim:^3.9 for PHP 8.0 support or upgrade PHP:
```
composer require phpdocumentor/shim:^3.9 --dev
```
Template Path Changes:
- Issue: In v3.10.0+, default templates moved to vendor/phpdocumentor/templates-*. Custom templates using old paths (e.g., vendor/phpDocumentor/templates) will break.
- Fix: Update phpdocumentor.dist.php:
```
return [
    'templates' => [
        'path' => __DIR__ . '/../../vendor/phpdocumentor/templates-dark', // Example
    ],
];
```
Artisan Command Conflicts:
- Issue: Custom Artisan commands using deprecated phpDocumentor APIs (e.g., Transformer events) will fail.
- Fix: Audit commands and migrate to the new Event System.
PHAR Cache Issues:
- Issue: vendor/bin/phpdocumentor may not update if Composer’s cache is corrupted.
- Fix: Clear Composer cache and reinstall:
```
composer clear-cache && composer install --dev
```
OpenAPI Annotation Parsing:
- Issue: @OA\* annotations may not render correctly if the OpenAPI extension is missing.
- Fix: Ensure the phpdocumentor/openapi package is installed:
```
composer require --dev phpdocumentor/openapi
```
Memory Limits:
- Issue: Large codebases may hit PHP’s memory limit (Allowed memory size of X bytes exhausted).
- Fix: Increase memory in phpdocumentor.dist.php:
```
return [
    'memory_limit' => '2G',
];
```
  Or via CLI:
```
vendor/bin/phpdocumentor -d src --target=docs/output --memory-limit=2G
```

Debugging

Verbose Output: Enable debug mode for detailed logs:

vendor/bin/phpdocumentor -d src --target=docs/output --verbose

Dry Run: Validate configuration without generating output:

vendor/bin/phpdocumentor -d src --target=docs/output --validate

Check PHAR Integrity: Verify the PHAR file isn’t corrupted:
```
vendor/bin/phpdocumentor --version
```
If this fails, reinstall:
```
composer update --dev phpdocumentor/shim
```

Configuration Quirks

Default Configuration: The phpdocumentor.dist.php file is auto-generated in vendor/phpdocumentor/. Customize it by copying

Shim Laravel Package