Phpdoc Markdown Public Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require --dev cvuorinen/phpdoc-markdown-public
   

   Ensure phpDocumentor is installed globally or via Composer:

   composer global require phpdocumentor/phpdocumentor
   

2. First Use Case Generate Markdown docs for a Laravel project:

   vendor/bin/phpdoc -d ./app -t ./docs/api --template cvuorinen/phpdoc-markdown-public
   

   • -d: Source directory (e.g., ./app for Laravel models/controllers).
   • -t: Output directory (e.g., ./docs/api).
   • --template: Specify the Markdown template.

3. Where to Look First

   • Template Config: Check vendor/cvuorinen/phpdoc-markdown-public/config.php for customization options.
   • Output Structure: Generated Markdown files will mirror your project’s namespace hierarchy (e.g., Models/User.md).
   • Laravel-Specific: Focus on app/Http/Controllers/, app/Models/, and app/Services/ for public API docs.

Implementation Patterns

Workflows

1. CI/CD Integration Add a script to composer.json for automated doc generation:

   "scripts": {
     "docs": "php vendor/bin/phpdoc -d ./app -t ./docs/api --template cvuorinen/phpdoc-markdown-public"
   }
   

   Trigger via:

   composer docs
   

   • Tip: Use GitHub Actions to deploy docs to a gh-pages branch or Netlify.

2. Laravel-Specific Patterns

   • Controllers: Document routes and request/response examples:

     /**
      * @OA\Get(
      *     path="/api/users",
      *     summary="Get all users",
      *     @OA\Response(response="200", description="List of users")
      * )
      */
     public function index() { ... }
     

   • Models: Use @property and @method tags for Eloquent methods:

     /**
      * @property int $id
      * @method static \Illuminate\Database\Eloquent\Collection|User[] all()
      */
     class User extends Model { ... }
     

3. Custom Templates Extend the template by copying vendor/cvuorinen/phpdoc-markdown-public to templates/phpdoc-markdown-custom and modifying:

   • config.php: Adjust Markdown formatting (e.g., enable/disable @see links).
   • theme/: Override CSS/JS for styling (e.g., add Laravel-specific badges).

4. Integration with Laravel Tools

   • Laravel IDE Helper: Generate PHPDoc blocks for autocompletion:

     vendor/bin/php artisan ide-helper:generate
     

   • Postman/Newman: Use generated Markdown as a spec for API testing.

Gotchas and Tips

Pitfalls

1. Namespace Collisions

   • Issue: Generated files may conflict if namespaces aren’t unique (e.g., App\Models\User vs. App\Services\User).
   • Fix: Use --ignore to exclude directories:

     vendor/bin/phpdoc -d ./app --ignore=*/Tests/* -t ./docs/api
     

2. PHPDoc Parsing Quirks

   • Issue: Complex PHPDoc tags (e.g., @OA\*) may not render correctly.
   • Fix: Simplify tags or use a separate tool like Zircote/Swagger-PHP for OpenAPI specs.

3. Performance

   • Issue: Large codebases slow down generation.
   • Fix: Exclude non-public code:

     vendor/bin/phpdoc -d ./app/Http -t ./docs/api
     

4. Template Caching

   • Issue: Changes to config.php require re-running phpdoc.
   • Fix: Use --cache for faster subsequent runs (but clear cache if configs change):

     vendor/bin/phpdoc --cache ./phpdoc-cache
     

Debugging

• Verbose Output: Enable debug mode:

  vendor/bin/phpdoc -vvv
  

• Dry Run: Test with --parse-only to validate PHPDoc parsing:

  vendor/bin/phpdoc --parse-only -d ./app
  

Extension Points

1. Custom Markdown Processors Hook into the template’s MarkdownProcessor class to modify output (e.g., add Laravel-specific syntax highlighting):

   // In a custom template's config.php
   $template->setProcessor(new \MyApp\CustomMarkdownProcessor());
   

2. Post-Processing Scripts Use a script to transform Markdown after generation (e.g., add table of contents):

   # Example: Add TOC to each file
   find ./docs/api -name "*.md" -exec sed -i '/^#/!b;n;I\\[TOC\\]\n' {} \;
   

3. Git Hooks Auto-generate docs on pre-commit (for critical paths):

   # In .git/hooks/pre-commit
   #!/bin/sh
   composer docs || exit 1
   

Laravel-Specific Tips

• Route Documentation: Pair with laravel/api-doc to auto-generate OpenAPI specs from routes.
• Dynamic Content: Exclude dynamic methods (e.g., Eloquent accessors) with @internal:

  /**
   * @internal
   */
  public function getFullNameAttribute() { ... }
  

• Monorepos: Use --directory to scope generation to a single package:

  vendor/bin/phpdoc -d ./packages/my-package -t ./docs/api