Entity Draw Laravel Package

Getting Started

jawira/entity-draw is a standalone CLI static-analysis tool, not a Laravel package: it scans PHP source and emits class/entity diagrams (primarily PlantUML). There is no service provider, no config/entity-draw.php, and no facade — you drive it from the shell or a Composer script.

1. Install as a dev dependency (v2 requires PHP 8.2+, so Laravel 10/11 on a modern PHP runtime):

   composer require --dev jawira/entity-draw:^2.0
   

2. Look first at the binary's own help output — it is the most reliable contract, since options changed in v2:

   vendor/bin/entity-draw --help
   vendor/bin/entity-draw list   # available writers/formats
   

   Then read the README section on filters (the v2 addition) and the jawira/contracts v2 docs for writer/output behaviour.
3. First use case — diagram your domain layer, not the whole app:

   vendor/bin/entity-draw app/Models -o build/erd.puml
   

4. Render it. Either locally with PlantUML (plantuml -tsvg build/erd.puml) or via the PlantUML server — but only for non-proprietary code.

Add a Composer script immediately so the command is discoverable and consistent across the team:

"scripts": {
    "diagrams": "entity-draw app/Models app/Domain -o build/erd.puml"
}

Implementation Patterns

Scope by directory, refine with filters. The realistic workflow is one diagram per bounded context, not one diagram for app/. Point the tool at app/Domain/Sales, app/Models, etc., and use the v2 include filters to trim noise (framework base classes, traits, DTOs) rather than post-editing the .puml.

Composer script as the single entry point. Wrap the invocation in a script (or several: diagrams:models, diagrams:domain) so CI, docs builds, and developers all run the identical command with identical flags. Never document raw ad-hoc invocations in the README — they drift.

CI artifact generation. Run the script in a CI job and upload the .puml/.svg as a build artifact, or publish to a docs site. Keep the rendering step separate: the tool produces text, PlantUML (Java) or a container image renders it. Use the official PlantUML Docker image rather than installing Java on the runner.

- run: composer diagrams
- run: docker run --rm -v $PWD/build:/data plantuml/plantuml -tsvg /data/erd.puml

Pair it with a hand-written architecture doc. Auto-generated class diagrams are excellent for spotting accidental coupling and orphaned classes; they are poor at communicating intent. Generate them, commit or publish them, and narrate them in prose.

Custom Artisan wrapper (optional). If you want php artisan diagrams, write a thin command that shells out with Symfony\Component\Process\Process and the same flags. This is the correct integration point — do not expect first-party Laravel support.

Diff-friendly output. Generate into a dedicated build/ or docs/diagrams/ directory, and treat the output as a generated artifact. If you commit it, add a .gitattributes entry or reviewer convention so ordering churn doesn't dominate PR diffs.

Gotchas and Tips

• v2.0.0 is a breaking release. It requires PHP 8.2+ (PHP 8.2 language features are now used) and depends on jawira/contracts v2. If another Jawira tool in your require-dev still pins contracts v1 (e.g. a PlantUML client), Composer will refuse to resolve both. Check with composer why jawira/contracts before upgrading, and be prepared to upgrade sibling packages in the same PR.
• Pin the major version. ^2.0 — a * or dev constraint here will silently break your CI diagram job on the next major.
• Static analysis only. Eloquent relations declared via magic ($this->hasMany(...) returning untyped properties), morphTo, model attributes, and anything resolved at runtime will not appear as associations. You get classes, methods, and declared types — set expectations accordingly, and don't try to make it an ERD generator for your schema (use doctrine/dbal / schema:dump for that).
• Diagram explosion. A naive run over app/ produces an unreadable hairball. Always scope to a directory + namespace/include filter. If the diagram is unreadable, the fix is a narrower input path, not a bigger canvas.
• Output paths are relative to the working directory and the writer generally expects the target directory to exist — mkdir -p build in the script rather than relying on the tool.
• No config file means no environment-specific behaviour. Every nuance is a CLI flag, so encode them in the Composer script; otherwise contributors will run subtly different commands and produce inconsistent artifacts.
• Exit codes matter in CI. Parse/IO failures surface as non-zero exits — let the job fail rather than uploading a stale diagram.
• Rendering is a separate dependency. PlantUML needs Java or Docker. Sending source-derived diagrams to the public PlantUML server leaks class names and relationships; keep it local or in a private runner.
• Extension points live in jawira/contracts v2. Custom output formats/templates are done by implementing the contracts and invoking the tool with your writer, not by hooking into Laravel. Check list output for available writers before writing one.