Template Abstract Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require phpdocumentor/template-abstract
   

   Ensure phpdocumentor/phpdocumentor is also installed (this package is a template for phpDocumentor).

2. Basic Usage:

   • Configure phpDocumentor to use this template in your phpdoc.dist.php or phpdoc.php:

     return [
         'template' => 'phpdocumentor/template-abstract',
         // Other phpDocumentor config...
     ];
     

   • Run phpDocumentor:

     vendor/bin/phpdoc -d src -t docs
     

3. First Use Case: Generate API documentation for a Laravel project:

   vendor/bin/phpdoc -d app/Http -t docs/api --title="My Laravel API Docs"
   

   Output will be a clean, modern HTML template in the docs/api directory.

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline:

   • Add to your GitHub Actions/GitLab CI:

     - name: Generate API Docs
       run: vendor/bin/phpdoc -d src -t docs/api --template=phpdocumentor/template-abstract
     

   • Store generated docs in a gh-pages branch or deploy to a static host (e.g., Netlify).

2. Laravel-Specific Use Cases:

   • Route Documentation: Use phpDocumentor to document controllers, then link to routes in the generated output.

     /**
      * @route GET /api/users
      * @template-extends \phpDocumentor\Template\AbstractTemplate\RouteTemplate
      */
     class UserController extends Controller { ... }
     

   • Service Layer Docs: Document services (e.g., app/Services/UserService.php) with @method tags for clarity.

3. Customization:

   • Override template files by copying from vendor/phpdocumentor/template-abstract/templates to your project’s templates directory.
   • Extend the base template by subclassing phpDocumentor\Template\AbstractTemplate\AbstractTemplate.

4. Theming:

   • Modify CSS/JS in templates/assets/ to match your Laravel project’s brand (e.g., primary colors, fonts).
   • Example: Override _variables.scss for theming.

Gotchas and Tips

Pitfalls

1. Archived Package:

   • The package is archived (no active maintenance). Use with caution; fork if you need updates.
   • Monitor for breaking changes in phpDocumentor/phpdocumentor (this template may lag).

2. Template Overrides:

   • If you override templates, ensure file paths in templates/ match the expected structure. Misplaced files (e.g., index.twig in the wrong dir) will break rendering.
   • Clear the docs/ directory before regenerating to avoid stale files.

3. Laravel-Specific Quirks:

   • Namespaces: phpDocumentor may struggle with Laravel’s App\ namespace. Use @package tags explicitly:

     /** @package App\Http\Controllers */
     

   • Dynamic Content: Avoid documenting dynamic methods (e.g., __call) unless annotated with @method.

4. Performance:

   • Generating docs for large codebases (e.g., full Laravel app) can be slow. Use --processes=4 to parallelize:

     vendor/bin/phpdoc -d src -t docs --processes=4
     

Debugging

1. Template Errors:

   • Enable verbose output:

     vendor/bin/phpdoc -d src -t docs --verbose
     

   • Check phpdoc.log for Twig/rendering errors.

2. Missing Assets:

   • If CSS/JS fails to load, verify the templates/assets/ directory exists and is copied correctly.

Extension Points

1. Custom Templates:

   • Extend the base template by creating a new class:

     use phpDocumentor\Template\AbstractTemplate\AbstractTemplate;
     class MyCustomTemplate extends AbstractTemplate { ... }
     

   • Register it in phpdoc.php:

     'template' => MyCustomTemplate::class,
     

2. Plugin Integration:

   • Use phpDocumentor’s @plugin tag to integrate with tools like phpDocumentor/parser for custom parsing logic.

3. Twig Filters:

   • Add custom Twig filters in your template’s functions.php:

     $twig->addFilter(new \Twig\TwigFilter('laravel_namespace', function ($namespace) {
         return str_replace('App\\', '', $namespace);
     }));