Phpdox Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require theseer/phpdox --dev
   

   Add to composer.json under require-dev to ensure it’s only installed in development.

2. Basic Configuration Create a phpdox.xml config file in your project root (or use the default via CLI):

   <?xml version="1.0" encoding="UTF-8"?>
   <phpdox>
       <source>
           <directory>src</directory>
       </source>
       <output>
           <directory>docs/api</directory>
       </output>
   </phpdox>
   

3. First Run Generate docs from the command line:

   vendor/bin/phpdox generate
   

   Outputs HTML docs to docs/api by default.

4. Where to Look First

   • CLI Help: Run vendor/bin/phpdox --help for available commands.
   • Config Reference: Check vendor/theseer/phpdox/resources/phpdox.xml for default settings.
   • XSLT Templates: Explore vendor/theseer/phpdox/resources/xslt/ for customization hooks.

Implementation Patterns

Workflows

1. CI/CD Integration Add to .github/workflows/docs.yml:

   - name: Generate Docs
     run: vendor/bin/phpdox generate
   

   Push docs to a gh-pages branch or deploy via Netlify/GitHub Pages.

2. Laravel-Specific Setup

   • Exclude vendor/ and tests/ from source:

     <source>
         <directory>app</directory>
         <directory>config</directory>
         <exclude>*/tests/*</exclude>
     </source>
     

   • Use Laravel’s bootstrap/app.php for autoloading (no extra config needed).

3. Template Customization Override default XSLT templates by copying vendor/theseer/phpdox/resources/xslt/ to resources/views/phpdox/ and updating paths in phpdox.xml:

   <xslt>
       <directory>resources/views/phpdox/xslt</directory>
   </xslt>
   

4. Dynamic Documentation Generate docs per-module by splitting <source> tags:

   <source>
       <directory>app/Http/Controllers</directory>
       <name>API Controllers</name>
   </source>
   

Integration Tips

• Laravel Artisan Command Create a custom command (app/Console/Commands/GenerateDocs.php) to wrap phpdox with Laravel’s logging:

  public function handle()
  {
      $this->info('Generating API documentation...');
      $exitCode = Artisan::call('phpdox:generate');
      if ($exitCode !== 0) $this->error('Failed to generate docs.');
  }
  

  Register in app/Console/Kernel.php and call via php artisan docs:generate.

• Markdown Output Use the markdown output format for easier GitHub/GitLab integration:

  <output>
      <format>markdown</format>
      <directory>docs/markdown</directory>
  </output>
  

Gotchas and Tips

Pitfalls

1. Deprecated Package

   • Last release in 2019; may break with PHP 8.x+ or modern Laravel.
   • Mitigation: Use a Docker container with PHP 7.4 or pin dependencies in composer.json:

     "config": {
         "platform": {
             "php": "7.4"
         }
     }
     

2. DocBlock Parsing Quirks

   • False Positives: @throws tags without exceptions may cause errors. Validate with:

     vendor/bin/phpdox validate
     

   • Laravel-Specific: Ignore @mixin or @method from Blade templates by excluding directories:

     <exclude>resources/views/*</exclude>
     

3. XSLT Caching Issues

   • Clear cached templates if styles don’t update:

     rm -rf docs/api/.cache
     

4. Performance

   • Large codebases (e.g., Laravel + plugins) may timeout. Increase CLI memory:

     php -d memory_limit=2G vendor/bin/phpdox generate
     

Debugging

• Verbose Output Enable debug mode in phpdox.xml:

  <debug>true</debug>
  

  Or via CLI:

  vendor/bin/phpdox generate --debug
  

• Log File Redirect output to a file for CI/CD debugging:

  vendor/bin/phpdox generate > docs/generate.log 2>&1
  

Extension Points

1. Custom XSLT Filters Extend templates to highlight Laravel-specific elements (e.g., route annotations):

   <!-- resources/views/phpdox/xslt/class.xsl -->
   <xsl:template match="annotation[@name='route']">
       <div class="laravel-route">
           <strong>Route:</strong> <code><xsl:value-of select="."/></code>
       </div>
   </xsl:template>
   

2. Pre/Post-Generate Hooks Use Laravel’s finished event to process docs after generation:

   // app/Providers/AppServiceProvider.php
   public function boot()
   {
       if ($this->app->runningInConsole()) {
           Artisan::command('phpdox:generate')->listen(function () {
               // Post-process (e.g., deploy to S3)
           });
       }
   }
   

3. Dynamic Source Filtering Exclude files dynamically via a custom SourceFilter class (extend phpDox\Source\SourceFilter). Example:

   class LaravelSourceFilter extends \phpDox\Source\SourceFilter
   {
       public function filter(\SplFileInfo $file)
       {
           return !str_contains($file->getPathname(), 'vendor/laravel/framework');
       }
   }
   

   Register in phpdox.xml:

   <sourceFilter>App\Filters\LaravelSourceFilter</sourceFilter>
   

4. Integration with Laravel Scout Auto-generate docs for search indexes by parsing the output XML:

   $xml = simplexml_load_file('docs/api/phpdox.xml');
   foreach ($xml->classes->class as $class) {
       Scout::index($class->name, ['content' => $class->description]);
   }