Markdowndocs Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev victorjonsson/markdowndocs
   

   This adds the package to require-dev and places the phpdoc-md executable in vendor/bin/.

2. First Use Case: Document a single class (e.g., App\Models\User) or an entire directory (e.g., app/):

   ./vendor/bin/phpdoc-md generate App\Models\User > docs/User.md
   

   Or for all classes in app/:

   ./vendor/bin/phpdoc-md generate app/ > docs/api.md
   

3. Verify Output: Open docs/api.md to confirm the generated Markdown includes:

   • Class descriptions (from @class or file-level DocBlocks).
   • Public/protected methods with parameters and return types.
   • Ignored methods (marked with @ignore).

Implementation Patterns

Workflows

1. CI/CD Integration: Add a script to composer.json to auto-generate docs on post-update-cmd:

   "scripts": {
       "post-update-cmd": [
           "@phpdoc-md generate app/ > docs/api.md"
       ]
   }
   

   Trigger via:

   composer update
   

2. Partial Documentation: Document only critical classes (e.g., API controllers):

   ./vendor/bin/phpdoc-md generate App\Http\Controllers\\*,App\Services\\* > docs/public-api.md
   

3. Bootstrapping: For non-Composer projects or custom autoloading:

   ./vendor/bin/phpdoc-md generate --bootstrap=bootstrap/app.php src/ > docs/api.md
   

Laravel-Specific Tips

• Namespace Handling: Use Laravel’s app/ namespace directly (e.g., App\Models\User). Avoid relative paths (e.g., ./Models/User)—the tool relies on Composer autoloading.

• DocBlock Standardization: Align with Laravel’s conventions (e.g., @param string $name instead of @param $name string). Example:

  /**
   * Fetches a user by ID.
   * @param int $id
   * @return \App\Models\User|null
   * @throws \Exception If user not found.
   */
  public function findUser(int $id) { ... }
  

• Output Customization: Pipe output to a Laravel Blade template for dynamic rendering:

  ./vendor/bin/phpdoc-md generate app/ | ./vendor/bin/blade > docs/api.blade.md
  

Gotchas and Tips

Pitfalls

1. File Naming:

   • Error: src/UserModel.php for class App\Models\User.
   • Fix: Rename to User.php or use --bootstrap to override autoloading.

2. Ignored Directories:

   • Issue: Docs include tests/ or vendor/ despite --ignore.
   • Fix: Use absolute paths in --ignore:

     ./vendor/bin/phpdoc-md generate --ignore=/full/path/to/tests app/ > docs/api.md
     

3. Return Type Guessing:

   • Problem: Missing @return causes ambiguous type hints (e.g., array vs. stdClass).
   • Fix: Explicitly declare return types in DocBlocks.

4. Protected Methods:

   • Behavior: Only public/protected methods are included. Use @internal to exclude protected methods entirely.

Debugging

• Verbose Mode: Add -v for debugging:

  ./vendor/bin/phpdoc-md generate -v app/
  

  Outputs skipped classes/files and reflection errors.

• Reflection Errors:

  • Symptom: Class not found for namespaced classes.
  • Solution: Ensure the class is listed in composer.json under autoload:

    "autoload": {
        "psr-4": { "App\\": "app/" }
    }
    

Extension Points

1. Custom Templates: Override the Markdown template by modifying the package’s src/Template.php (fork the repo or patch locally).

2. Pre/Post-Processing: Use Laravel’s Artisan::command() to wrap phpdoc-md:

   Artisan::command('docs:generate', function () {
       $output = shell_exec('vendor/bin/phpdoc-md generate app/');
       file_put_contents('docs/api.md', $output);
   });
   

3. Git Hooks: Auto-generate docs on pre-commit (via husky or Laravel Git hooks):

   ./vendor/bin/phpdoc-md generate --ignore=tests app/ > docs/api.md
   git add docs/api.md
   

Config Quirks

• Line Endings: Generated Markdown may use \n (Unix) or \r\n (Windows). Normalize with:

  unix2dos docs/api.md  # or dos2unix
  

• PHP 7+ Compatibility: The package targets PHP 5.3.2 but works with Laravel’s PHP 7.4+. Test edge cases (e.g., void return types) manually.