Doctum Laravel Package

Getting Started

Minimal Setup

1. Installation (PHP 8.1+ required):

   composer require code-lts/doctum --dev
   

   Add to require-dev in composer.json for project-specific docs.

2. Configuration: Publish the config file:

   php artisan vendor:publish --provider="Doctum\DoctumServiceProvider"
   

   Update .env and config/doctum.php to define:

   • source (e.g., app/, src/)
   • output (e.g., docs/)
   • title and theme (default: bootstrap or bootstrap-4)

3. First Run:

   php artisan doctum:generate
   

   Outputs HTML docs to docs/ (or your configured path).

4. Quick Use Case: Generate docs for a single class:

   php artisan doctum:generate --filter=App\Services\PaymentService
   

Implementation Patterns

Workflows

1. CI/CD Integration (PHP 8.1+ required):

   • Run in post-test or build phase:

     # .github/workflows/docs.yml
     - name: Generate Docs
       run: php artisan doctum:generate
     

   • Cache dependencies (composer.lock) to avoid redundant installs.

2. Versioned Documentation:

   • Use --output flag to generate per-branch docs:

     php artisan doctum:generate --output=docs/v1.2
     

   • Symlink to docs/latest for convenience.

3. Incremental Updates:

   • Skip unchanged files with --only-changed (if supported in future versions).
   • Combine with git diff to regenerate only modified classes:

     git diff --name-only HEAD~1 | xargs -I{} php artisan doctum:generate --filter={}
     

Integration Tips

1. Custom Themes: Extend the default theme by copying vendor/doctum/themes/bootstrap to resources/views/vendor/doctum and override templates (e.g., class.blade.php).

2. Enhanced PHPDoc Support:

   • New @category Tag: Group related classes:

     /**
      * @category Authentication
      */
     class LoginController {}
     

   • PHPStan Doc Parsing: Improved error detection (may alter existing error lists).

3. API Annotations: Use PHPDoc blocks for richer metadata:

   /**
    * @method static \App\Models\User findByEmail(string $email)
    * @throws \InvalidArgumentException
    */
   class UserRepository {}
   

4. Excluding Files: Configure in config/doctum.php:

   'exclude' => [
       'app/Exceptions/*',
       'app/Providers/*',
   ],
   

5. Markdown Support: Embed Markdown in PHPDoc @description tags:

   /**
    * @description
    * # Payment Processing
    * - Supports **Stripe** and PayPal.
    * - [See our guide](https://example.com/guide).
    */
   

6. Dynamic Output: Generate docs programmatically in tests or migrations:

   use Doctum\Doctum;
   
   $doctum = new Doctum();
   $doctum->generate();
   

Gotchas and Tips

Pitfalls

1. PHP Version Requirement:

   • Breaking: PHP 7.4 and 8.0 no longer supported. Update to PHP 8.1+.
   • Verify with:

     php -v
     

2. Namespace Conflicts:

   • If your app uses Doctum as a class name, rename the config file to avoid collisions:

     mv config/doctum.php config/doctum_config.php
     

   • Update app/Providers/DoctumServiceProvider accordingly.

3. Circular References:

   • Docs may fail if classes reference each other circularly. Use --filter to generate subsets:

     php artisan doctum:generate --filter=App\Models\*
     

4. Theme Dependencies:

   • Bootstrap themes require bootstrap CSS/JS. Include them in your docs/index.html:

     <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/css/bootstrap.min.css">
     

5. PHPDoc Parsing Quirks:

   • New: PHPStan doc parsing may change error lists. Test thoroughly.
   • Avoid malformed PHPDoc (e.g., unclosed tags, invalid @param syntax).
   • Test with php -l or use phpDocumentor/phpdocumentor for validation.

6. Dependency Conflicts:

   • Breaking: PHPUnit 7/8 and Symfony 3.4–5.3 no longer supported. Update to:
     • PHPUnit 10/11/12
     • Symfony 5.4+ (LTS)
   • Run composer update to resolve conflicts.

7. File Permissions:

   • Ensure storage/ and docs/ are writable:

     chmod -R 775 storage docs
     

Debugging

1. Verbose Output: Enable debug mode in .env:

   DOCTUM_DEBUG=true
   

   Or run with:

   php artisan doctum:generate --verbose
   

2. Log Generation: Check storage/logs/doctum.log for parsing errors.

3. Dry Run: Use --dry-run (if available) to preview changes without writing files.

4. TypeHint Resolution:

   • Fixed: Unions no longer prefixed with namespace (e.g., (string|int) instead of \string|\int).

Extension Points

1. Custom Parsers: Extend Doctum\Parsers\ParserInterface to support custom PHPDoc tags or annotations.

2. Post-Processing: Hook into doctum.generated event in EventServiceProvider:

   protected $listen = [
       'doctum.generated' => [
           'App\Listeners\DeployDocsToS3',
       ],
   ];
   

3. CLI Aliases: Add to composer.json:

   "extra": {
       "laravel": {
           "aliases": {
               "docs:generate": "doctum:generate"
           }
       }
   }
   

4. Git Hooks: Auto-generate docs on pre-commit (use sparingly):

   php artisan doctum:generate --only-changed
   git add docs/
   

5. Localization: Override language files in resources/lang/ to customize doc text (e.g., "Properties" → "Attributes").

6. Version Navigation:

   • New: Attempts to reload the current page when switching versions (client-side fix). Ensure your deployment includes this JS logic.

7. PHPStan Integration: Leverage PHPStan’s improved doc parsing for stricter validation:

   vendor/bin/phpstan analyse --level=max src/