- How do I install ostico/phpdoc-md in a Laravel project?
- Run `composer require ostico/phpdoc-md` in your project directory. Ensure your Laravel app uses PHP 8.0+ and phpDocumentor v3+ (pin versions in composer.json to avoid conflicts). No Laravel-specific setup is required beyond basic Composer installation.
- Can ostico/phpdoc-md convert PHPDoc from Laravel controllers or Eloquent models?
- Yes, the package processes standard PHPDoc blocks, including those in Laravel controllers, Eloquent models, and custom classes. It preserves tags like `@param`, `@return`, and `@throws` while formatting them into readable Markdown.
- Does this package support Laravel’s custom PHPDoc tags (e.g., @route or @middleware)?
- Out of the box, it handles standard PHPDoc tags. For Laravel-specific tags (e.g., `@route`), you’ll need to extend the package via a custom service provider or wrapper class to map them to Markdown output.
- How can I integrate ostico/phpdoc-md into Laravel’s CI/CD pipeline?
- Wrap the package in a custom Artisan command (e.g., `php artisan docs:generate`) and trigger it in your CI (e.g., GitHub Actions). Use it to auto-generate Markdown on pushes to `main` and commit the output to a `docs/` branch.
- Will this work with Laravel 10.x or older versions like 8.x?
- The package requires PHP 8.0+, so it’s compatible with Laravel 8.x (LTS) and 10.x. Test with your specific Laravel version to ensure phpDocumentor dependencies align, and pin versions in `composer.json` if needed.
- Can I use ostico/phpdoc-md to generate API documentation for Laravel APIs?
- Yes, it converts PHPDoc from API controllers into Markdown, which you can then integrate with tools like Swagger/OpenAPI or publish directly. For dynamic APIs, combine it with runtime data (e.g., route lists) for richer docs.
- How do I customize the Markdown output format (e.g., add Laravel-specific templates)?
- Extend the package by creating a custom service provider or wrapper class. Override methods like `generateMarkdown()` to inject Laravel-specific templates (e.g., for auth flows or Eloquent models) into the output.
- Is ostico/phpdoc-md suitable for large Laravel codebases (e.g., 10K+ lines)?
- For large projects, test performance first. Cache generated Markdown in Laravel’s `storage/` directory to avoid reprocessing. If slow, consider running it in CI only on specific paths (e.g., `app/Http/Controllers/`).
- Can I validate the generated Markdown for consistency (e.g., with markdownlint)?
- Yes, run the output through tools like `markdownlint` or Laravel validation rules. For CI integration, add a step to lint Markdown files after generation (e.g., using a GitHub Actions workflow).
- What are the alternatives to ostico/phpdoc-md for PHPDoc-to-Markdown conversion?
- Alternatives include `phpDocumentor` (full-featured but heavier) or custom scripts using `ReflectionClass`. For Laravel, consider `spatie/laravel-api-docs` if you need Swagger/OpenAPI integration. Choose based on your need for simplicity vs. advanced features.