Doctum Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: Doctum remains a dedicated API documentation generator for PHP/Laravel, ideal for RESTful APIs, microservices, and legacy systems. The new @category tag (v5.6.0) enhances logical grouping of endpoints (e.g., auth, payments), improving navigation in tools like Swagger UI.
• Laravel Synergy: Continues to leverage Laravel’s service container, events, and configuration. New features like PHPStan doc parsing (v5.6.0) align with modern PHP tooling, reducing manual annotation effort.
• Output Flexibility: Supports OpenAPI 3.0, JSON Schema, and Markdown unchanged, but @category tags enable better tooling integration (e.g., Swagger UI’s tag-based filtering).

Integration Feasibility

• Low-Coupling Design: Unchanged—remains a standalone tool with minimal dependencies. New PHP 8.1+ requirement aligns with Laravel’s current LTS support.
• Configuration Override: @category tags add zero-config grouping for routes, reducing manual Markdown maintenance. PHPStan parsing (v5.6.0) may alter error reporting (see Key Questions).
• Extensibility: Hooks into Laravel events remain intact; new Symfony v7/v8 support broadens compatibility for non-Laravel PHP projects.

Technical Risk

Key Questions

1. PHP Version Upgrade:
   • Are all CI/CD environments (e.g., GitHub Actions, self-hosted) running PHP 8.1+?
   • Will legacy Laravel 7/8 projects (PHP 7.4/8.0) require parallel maintenance?
2. Annotation Tooling:
   • Should PHPStan parsing replace or supplement existing annotation validation?
   • How will @category tags be mapped to Swagger UI/Redoc (e.g., via tags field in OpenAPI)?
3. Symfony Compatibility:
   • Are any non-Laravel Symfony components in use that may conflict with dropped versions (e.g., Symfony 5.1)?
4. Performance Impact:
   • Does PHPStan parsing add significant overhead to doc generation?
   • Should @category tags trigger incremental regeneration for large APIs?
5. Deprecation Handling:
   • How will dropped PHPUnit 7/8 and Symfony 3.4–5.3 support affect internal tooling?

Integration Approach

Stack Fit

• PHP/Laravel Ecosystem:
  • Native Support: Unchanged—works with Laravel 8+/Lumen. PHP 8.1+ requirement aligns with Laravel’s LTS.
  • Composer Dependency: Updated to support PHPUnit 10–12, Symfony 5.4+, and php-parser v5.
• Tooling Compatibility:
  • OpenAPI: @category tags enable Swagger UI/Redoc grouping without manual Markdown edits.
  • PHPStan: Native parsing may reduce false positives in annotations (e.g., missing @param).
  • CI/CD: PHP 8.1+ is now a hard requirement; update pipelines accordingly.
• CI/CD Readiness:
  • Validation: Add phpstan checks to CI to catch annotation issues early.
  • Gating: Fail builds if @category tags are missing for critical endpoints.

Migration Path

1. Pre-Upgrade Audit:
   • Verify PHP 8.1+ support across all environments.
   • Check for Symfony 3.4–5.3 or PHPUnit 7/8 dependencies (e.g., legacy tests).
2. Pilot Phase:
   • Test @category tags on a single module (e.g., /api/v1/auth).
   • Validate PHPStan parsing against existing annotations (may surface new errors).
3. Incremental Rollout:
   • Phase 1: Update composer.json to PHP 8.1+, PHPUnit 10+, Symfony 5.4+.
   • Phase 2: Migrate annotations to PHPStan format (if using new parsing).
   • Phase 3: Roll out @category tags for logical grouping in docs.
4. Post-Upgrade:
   • Run composer update to pull v5.6.0.
   • Regenerate docs and validate OpenAPI output with swagger-cli.

Compatibility

Sequencing

1. Pre-Integration:
   • Freeze composer.json to current versions (pre-upgrade).
   • Backup existing docs (docs/ directory).
2. Upgrade Dependencies:

   composer require php:^8.1 phpunit/phpunit:^10 symfony/*:^5.4
   

3. Test Pilot Module:
   • Add @category to a route (e.g., @category Auth).
   • Regenerate docs: php artisan doctum:generate.
   • Validate OpenAPI output for tags field.
4. Full Rollout:
   • Update all annotations to PHPStan-compatible format (if needed).
   • Regenerate docs and deploy.
5. Post-Deployment:
   • Monitor CI/CD for PHPStan-related failures.
   • Update Swagger UI/Redoc to reflect @category groupings.

Operational Impact

Maintenance

• Annotation Management:
  • Pros:
    • @category tags reduce manual grouping in Markdown/OpenAPI.
    • PHPStan parsing may catch errors earlier (e.g., missing @param).
  • Cons:
    • PHP 8.1+ requirement adds upgrade friction.
    • PHPStan changes may require CI adjustments (e.g., new error formats).
  • Tooling:
    • Use PHPStorm’s PHPDoc inspection or pre-commit hooks to enforce annotations.
    • Add phpstan to CI for annotation validation.
• Configuration Drift:
  • Centralized doctum.php remains unchanged; version pinning in composer.json mitigates drift.
  • Symfony/PHPUnit updates may require vendor config tweaks (e.g., phpunit.xml).

Support

• Troubleshooting:
  • Common Issues:
    • PHP 8.1 deprecations: Enable error_reporting(E_ALL) in doctum.php for debugging.
    • PHPStan parsing errors: Review Doctum’s PHPStan docs for migration tips.
    • Missing @category in OpenAPI: Verify tags field in generated openapi.json.
  • Debugging:
    • Enable DOCTUM_DEBUG=true for verbose logs.
    • Use php artisan doctum:validate to catch OpenAPI schema errors.
• Community Resources:
  • Active Development: 352+ stars; check **