Documenter Laravel Package

Getting Started

endroid/documenter is a small, low-maturity library that generates technical documentation from annotated source files (class diagrams, object descriptions, and similar artifacts). The README is thin — the Usage section is literally empty — so treat the source and tests as the primary documentation.

Minimal steps:

1. Install and pin it. Because the README explicitly warns that backwards-compatible changes are kept to a minimum but can occur, pin an exact version:

   composer require endroid/documenter:^x.y
   

2. Read the source before writing code. Start in src/ to identify:
   • the main generator/entry-point class,
   • the annotation (or attribute) classes you are expected to place on your source files,
   • any interfaces intended for extension (renderers, generators).
3. Check .install/symfony. The package targets Symfony via endroid/installer; those config files show how the library expects to be wired. They are a useful reference even in Laravel, but they are not a Laravel integration.
4. Run one end-to-end example. Annotate a single small class, invoke the generator directly from a tinker session or a throwaway script, and inspect the output. Don't start with your whole domain.

First real use case: annotate a handful of domain/service classes that are stable and public-facing, generate docs into a dedicated docs/generated/ directory, and diff the result in a PR. That gives you a feel for signal vs. noise before committing to it.

For Laravel specifically, assume no auto-discovery. You will need a small service provider binding and an Artisan command wrapper (see below).

Implementation Patterns

1. Annotation-driven documentation on selected classes. Use the package's annotations on the classes you actually want documented — typically domain models, public services, and integration points. Resist annotating everything: generated docs are only useful when the annotated surface is intentional.

// Illustrative — verify the exact annotation names in src/
#[Document(resource: 'billing')]
class InvoiceService
{
    // ...
}

2. Artisan command as the daily entry point. Wrap the generator in a command so the team has a single, memorable invocation:

class GenerateDocsCommand extends Command
{
    protected $signature = 'docs:generate {--output=docs/generated}';

    public function handle(Documenter $documenter): int
    {
        $documenter->generate($this->option('output'));
        $this->info('Documentation generated.');
        return self::SUCCESS;
    }
}

Bind the documenter as a singleton in AppServiceProvider, reading paths and options from config/documenter.php. This keeps configuration out of the command and makes it environment-aware.

3. CI as the source of truth. Generate docs in CI and either commit them or publish them as an artifact. A typical workflow:

• annotate on the feature branch,
• run php artisan docs:generate in CI,
• fail the build if the generated output differs from the committed docs (or always publish as an artifact).

This prevents documentation drift and makes review diffs meaningful.

4. Keep generated output out of application code. Generate into a dedicated directory (docs/generated, build/docs) and exclude it from autoloading. If the tool emits class diagrams, verify whether an external binary (e.g., Graphviz) is required and install it in CI explicitly.

5. Layer with existing docs, not instead of them. Use endroid/documenter for the structural/class-level view and keep hand-written README/ADR content for the narrative. Where the generated output is weak, supplement with phpDocumentor or your existing tooling rather than trying to force this package to do everything.

Gotchas and Tips

• The README has no usage section. Budget real time to read src/ and tests/. Tests are usually the most accurate usage examples in packages like this.
• Symfony-first, Laravel-second. The installer integration is Symfony-only. In Laravel you must wire services manually; do not expect package discovery, a published config, or a facade.
• Versioning is explicitly unstable. The README says BC breaks can occur. Pin versions, read the changelog before upgrading, and run your generation command in CI so upgrades surface output changes immediately.
• Very low adoption. One star and zero dependents means few eyeballs on edge cases. Treat it as an internal-risk dependency: consider vendoring or forking if it becomes load-bearing, and have a fallback plan.
• Annotation parsing quirks. Verify whether the package uses Doctrine annotations, PHP 8 attributes, or both. Doctrine annotations are deprecated in newer PHP ecosystems; if attributes aren't supported, you may hit friction on modern Laravel/PHP versions.
• Start with one class when debugging. If generation fails or produces empty output, reduce to a single annotated class, confirm the parser sees it, then expand. Most failures here are annotation discovery or path issues, not the generator itself.
• Output path and permissions. Ensure the target directory exists and is writable by the CLI user; CI containers frequently differ from local setups here.
• Look for extension points before patching. Check for interfaces around generators/renderers and decorate or implement them rather than editing vendor/. That keeps upgrades survivable.
• Don't make it the only documentation. With this maturity level, generated docs should be a supplement. Keep critical architecture notes in version-controlled markdown that doesn't depend on the package working.