Template Zend Laravel Package

Getting Started

1. Verify Compatibility Confirm your project uses Zend Framework 2.x and phpDocumentor2 (not phpDocumentor3). This template is not compatible with Laravel’s default stack or modern PHP versions.

2. Installation Add the package to your composer.json:

   composer require phpdocumentor/template-zend
   

   Note: This requires phpDocumentor2 (phpdocumentor/phpdocumentor:2.*) and Zend Framework 2.x dependencies.

3. First Use Case Generate documentation for a Zend Framework 2.x project:

   vendor/bin/phpdoc -d /path/to/zf2-project -t docs/output --template="vendor/phpdocumentor/template-zend"
   

   Output will include Zend Framework 2.x-specific styling (e.g., dark/light themes, ZF2 UI elements).

Implementation Patterns

Workflows

1. Legacy Documentation Workflow

   • Use this template only for Zend Framework 2.x projects in maintenance mode.
   • Integrate with Laravel via static asset hosting:

     // routes/web.php
     Route::get('/zf2-docs/{path?}', function ($path = null) {
         return response()->file(storage_path('docs/zf2/' . ($path ?: 'index.html')));
     })->where('path', '.*');
     

2. Template Customization Override the template’s Twig files:

   • Copy vendor/phpdocumentor/template-zend/templates/ to resources/views/phpdoc/.
   • Reference the local path in phpdoc.dist.xml:

     <template path="resources/views/phpdoc" />
     

3. CI/CD Automation Add a GitHub Actions step to generate docs on push:

   - name: Generate Zend Framework 2 Docs
     run: |
       docker run --rm -v $(pwd):/app composer:php5.6-cli composer require phpdocumentor/phpdocumentor:2.*
       docker run --rm -v $(pwd):/app composer:php5.6-cli vendor/bin/phpdoc -d app -t docs/zf2 --template="vendor/phpdocumentor/template-zend"
   

Laravel Integration Tips

• Isolate Dependencies Use a separate Composer workspace or Docker container for phpDocumentor2 to avoid conflicts with Laravel’s PHP 7.2+ requirements.

• Static Asset Pipeline Serve generated docs via Laravel’s Storage facade or a CDN:

  // app/Providers/AppServiceProvider.php
  public function boot() {
      $this->publishes([
          storage_path('docs/zf2') => public_path('zf2-docs'),
      ], 'docs');
  }
  

Gotchas and Tips

Pitfalls

1. PHP Version Mismatch

   • This template requires PHP 5.3–5.6 (Zend Framework 2.x era). Laravel 5.8+ uses PHP 7.2+.
   • Fix: Use Docker with php:5.6-apache or a separate machine.

2. Dependency Conflicts

   • phpdocumentor/unified-asset-installer (v1.1) may pull in unmaintained libraries.
   • Fix: Pin dependencies in composer.json or use --ignore-platform-reqs.

3. No phpDocumentor3 Support

   • This template only works with phpDocumentor2. Modern Laravel projects should use phpDocumentor3.
   • Fix: Migrate to phpDocumentor3 with a custom template.

4. Archived Package Risks

   • No updates or security patches. Avoid using this in production-critical systems.
   • Fix: Treat as a one-time asset extraction tool.

Debugging

• Template Not Loading? Ensure the <template> path in phpdoc.dist.xml is correct and points to the unzipped template directory.

• CSS/JS Errors The template relies on Zend Framework 2.x assets. If missing, manually copy files from vendor/zendframework/zendframework to public/zf2-assets.

Extension Points

1. Custom Annotations Extend the template to support Zend Framework 2.x-specific annotations (e.g., @Zend\Mvc\Controller\AbstractActionController).

2. Dark/Light Mode Toggle Modify the Twig templates to add a client-side theme switcher using JavaScript.

3. Search Functionality Integrate Lunr.js or Algolia for search if the default template lacks it.

Laravel-Specific Quirks

• Artisan Command Conflicts Avoid naming custom commands phpdoc to prevent clashes with the package’s CLI tool.

• Storage Permissions Ensure storage/docs/zf2 is writable:

  chmod -R 775 storage/docs/zf2
  

Performance Tips

• Cache Generated Docs Use Laravel’s Cache facade to store the last-generated docs and avoid regenerating on every request:

  $docs = Cache::remember('zf2_docs', now()->addDays(1), function () {
      return Artisan::call('phpdoc:generate');
  });
  

• Exclude Unnecessary Files Configure phpdoc.dist.xml to skip tests or vendor files:

  <filter>
      <exclude name="*/tests/*" />
      <exclude name="*/vendor/*" />
  </filter>