Phpdoc Md Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require evert/phpdoc-md
   

   No additional configuration is required for basic usage.

2. First Use Case: Generate Markdown from PHPDoc Use the Evert\PhpdocMd\PhpdocMd class to convert PHPDoc blocks to Markdown:

   use Evert\PhpdocMd\PhpdocMd;
   
   $phpdocMd = new PhpdocMd();
   $markdown = $phpdocMd->parse('/**
    * @param string $name The user\'s name
    * @return void
    */');
   echo $markdown;
   

   Output:

   - `$name` **string** The user's name
   

3. Where to Look First

   • Source Code: src/PhpdocMd.php (core logic).
   • Tests: tests/ for edge cases and examples.
   • README: Basic usage and CLI examples.

Implementation Patterns

Core Workflows

1. Parsing PHPDoc in Laravel Integrate with Laravel’s service providers or helpers to auto-generate Markdown from PHPDoc:

   // app/Helpers/PHPDocHelper.php
   use Evert\PhpdocMd\PhpdocMd;
   
   class PHPDocHelper {
       public static function toMarkdown(string $phpdoc): string {
           return (new PhpdocMd())->parse($phpdoc);
       }
   }
   

   Use in controllers/views:

   $markdown = PHPDocHelper::toMarkdown(file_get_contents('path/to/Class.php'));
   

2. CLI Integration Use the package’s built-in CLI for batch processing:

   vendor/bin/phpdoc-md generate src/ --output docs/
   

   • Customize output: Extend the CLI command or wrap it in an Artisan command.

3. Dynamic Documentation Generation Hook into Laravel’s events (e.g., Illuminate\Foundation\Application\Booted) to generate Markdown on demand:

   // app/Providers/AppServiceProvider.php
   public function boot() {
       $this->app->booted(function () {
           $markdown = PHPDocHelper::toMarkdown(file_get_contents(app_path('Http/Controllers/UserController.php')));
           cache()->forever('user_controller_docs', $markdown);
       });
   }
   

4. Integration with IDE/Editor Plugins Use the package to pre-process PHPDoc before sending to tools like VS Code’s Markdown preview or Swagger/OpenAPI generators.

Advanced Patterns

1. Custom Tag Handlers Extend PhpdocMd to support custom PHPDoc tags:

   $phpdocMd = new PhpdocMd();
   $phpdocMd->addTagHandler('custom', function ($tag) {
       return "**Custom Tag:** {$tag['description']}";
   });
   

2. Template-Based Output Combine with Laravel’s Blade for structured documentation:

   // resources/views/docs.blade.php
   @php
       $markdown = PHPDocHelper::toMarkdown($phpdoc);
   @endphp
   @markdown($markdown)
   

3. API Response Documentation Auto-generate Markdown for API responses using Laravel’s route model binding and PHPDoc:

   /**
    * @return \Illuminate\Http\JsonResponse
    * @response {
    *     "success": true,
    *     "data": {
    *         "id": 1,
    *         "name": "John Doe"
    *     }
    * }
    */
   public function show(User $user) { ... }
   

Gotchas and Tips

Pitfalls

1. Nested PHPDoc Parsing

   • The parser may struggle with multi-line tags or complex nested structures. Test with real-world PHPDoc blocks.
   • Workaround: Use trim() or regex to clean input before parsing.

2. Unsupported PHPDoc Syntax

   • Some less common tags (e.g., @mixin, @template) may not render correctly.
   • Fix: Extend PhpdocMd or pre-process tags with a regex.

3. Performance with Large Files

   • Parsing entire codebases (e.g., app/ directory) can be slow.
   • Optimization: Cache results or process files incrementally.

4. Markdown Escaping Issues

   • Special characters (e.g., *, _) in descriptions may break Markdown.
   • Solution: Use htmlspecialchars() or the package’s built-in escaping.

Debugging Tips

1. Enable Verbose Output Use the --verbose flag in CLI mode to debug parsing:

   vendor/bin/phpdoc-md generate src/ --output docs/ --verbose
   

2. Inspect Parsed Tokens Dump the internal token array for debugging:

   $phpdocMd = new PhpdocMd();
   $tokens = $phpdocMd->tokenize('/**
    * @param string $name
    */');
   dd($tokens);
   

3. Test Edge Cases

   • Empty PHPDoc: parse('') → Should return null or empty string.
   • Malformed Tags: @param without type/description.
   • Unicode Characters: Ensure non-ASCII descriptions render correctly.

Extension Points

1. Custom Output Formatters Override PhpdocMd::formatTag() to change how tags are rendered:

   $phpdocMd = new PhpdocMd();
   $phpdocMd->setFormatter(function ($tag) {
       return "[$tag[type]] $tag[description]";
   });
   

2. Integration with Laravel Scout Use generated Markdown for searchable documentation:

   Scout::searchable(function ($model) {
       $model->searchableData['docs'] = PHPDocHelper::toMarkdown($model->phpdoc);
   });
   

3. GitHub/GitLab Wiki Auto-Updates Hook into Laravel’s queue workers to auto-update wiki pages with PHPDoc Markdown:

   // app/Console/Commands/UpdateWiki.php
   public function handle() {
       $markdown = PHPDocHelper::toMarkdown(file_get_contents('src/Class.php'));
       $this->updateGitHubWiki($markdown);
   }
   

4. Laravel Nova Tool Integration Display PHPDoc Markdown in a custom Nova tool for real-time documentation:

   // app/Nova/Tools/DocumentationTool.php
   public function render() {
       $markdown = PHPDocHelper::toMarkdown($this->resource->phpdoc);
       return view('nova.documentation-tool', ['markdown' => $markdown]);
   }
   

Config Quirks

• No Config File: The package is zero-config by default. All behavior is controlled via code.
• Default Tag Order: Tags are parsed in the order they appear in PHPDoc. Use addTagHandler() to reorder or filter tags.