Weave Code
Dog Laravel Package
klitsche/dog
Dog is a lightweight source code documentation generator for PHP libraries. Built on phpDocumentor/reflection and Twig, it analyzes code and phpdoc, validates documentation with configurable rules, and outputs Markdown suitable for MkDocs and similar tools.
Source Code Documentation Generator for PHP Libraries
Frequently asked questions about Dog
- Can I use Dog to document Laravel controllers, Facades, and service classes?
- Yes, Dog is designed for PHP libraries and works perfectly with Laravel’s public API. Configure `srcPaths` in `.dog.yml` to target `app/Http/Controllers/`, `app/Facades/`, or custom service directories. Exclude internal files like `app/Providers/` to focus on your public interface.
- How do I install Dog in a Laravel project?
- Run `composer require --dev klitsche/dog` to install Dog as a dev dependency. Create a `.dog.yml` config file in your project root with paths to your source files and optional rules. No Laravel-specific setup is required beyond this.
- Does Dog support Laravel-specific PHPDoc tags like @route or @middleware?
- Dog doesn’t natively support Laravel tags out of the box, but you can extend it using custom **enrichers** or **rules**. The package’s extensible architecture lets you validate `@route` annotations or middleware stacks by writing a custom rule or enricher for your project.
- Will Dog work with Laravel’s built-in phpDocumentor or conflict with it?
- Dog uses `phpdocumentor/reflection` (v3.x) independently of Laravel’s bundled `phpdocumentor/phpdocumentor`. To avoid conflicts, pin the exact version in `composer.json` and test in a staging environment. Dog is designed to be a lightweight alternative for focused documentation tasks.
- How do I integrate Dog’s Markdown output with Laravel’s documentation?
- Place generated Markdown in `resources/docs/` and serve it via Laravel’s web routes or embed it in a custom `/docs` endpoint. For richer docs, use tools like `mkdocs-material` to host the output on GitHub Pages or integrate it with Laravel Forge’s static file hosting.
- Can I run Dog in CI/CD to enforce documentation standards?
- Yes, Dog supports CI/CD integration via GitHub Actions, Laravel Forge, or custom scripts. Configure it to fail builds on documentation errors by setting `issueLevel: 'error'` for critical rules. Run `dog:analyze` in your CI pipeline to validate docs before merging.
- Does Dog work with Laravel 10, 9, or older versions?
- Dog requires PHP 8.0+ and is framework-agnostic, so it works with any Laravel version supporting PHP 8.0. Test compatibility by checking the `phpdocumentor/reflection` and Twig versions in `composer.lock` against your Laravel project’s dependencies.
- How do I customize Dog’s validation rules for my Laravel project?
- Extend or override default rules in `.dog.yml` by specifying `class`, `issueLevel`, and `match` criteria. For example, disable `PublicFileDocBlockMissingRule` for legacy code or add a custom rule to enforce Laravel-specific PHPDoc tags like `@inject` or `@middleware`.
- Is Dog slow for large Laravel codebases? How can I optimize performance?
- Dog uses reflection, which can be slow for large projects. Mitigate this by caching analysis results in `storage/dog/` or running it in parallel with `--analyze` and `--generate` flags. Schedule heavy documentation tasks during off-peak CI hours or nightly builds.
- What are the alternatives to Dog for Laravel documentation?
- For Laravel-specific documentation, consider `spatie/laravel-api-docs` (for API routes) or `phpdocumentor/phpdocumentor` (full-featured but heavier). Dog is ideal if you need lightweight, customizable Markdown output with PSR-19 validation, especially for libraries or internal tools.
Weaver
How can I help you explore Laravel packages today?