Entity Draw Laravel Package

Product Decisions This Supports

• Documentation-as-code investment. Entity/relationship diagrams generated directly from source let you treat architecture docs as build artifacts instead of hand-maintained artifacts that rot after two sprints. This is a "keep the map honest" capability, not a feature.
• Build vs. buy. The alternative is an in-house PHP parser + diagram renderer, or a paid modeling suite (Lucidchart, Structurizr, Miro). This is the cheap third option: adopt a small, single-maintainer open-source CLI rather than spending engineering weeks on a generator nobody wants to own.
• Onboarding and knowledge-transfer roadmap. Auto-generated entity diagrams are a concrete, low-cost answer to "how do I understand this codebase" for new hires, contractors, and support engineers. Good input to onboarding checklists and internal wikis.
• Architecture review and domain-boundary conversations. The new include filters make it practical to render one bounded context, module, or namespace at a time. That directly supports scoping discussions, modular-monolith boundary decisions, and RFC/ADR attachments.
• PR and release-note enrichment. Regenerating diagrams in CI and attaching the diff to a PR gives reviewers a visual of structural change (new entities, new relationships) without reading every file.
• Client- and stakeholder-facing deliverables. Clean entity diagrams are presentable to non-engineers in discovery or handover material, which is otherwise expensive design labor.
• Tooling consolidation. If teams currently hand-draw ER diagrams in whiteboards or a SaaS tool, this is a defensible "standardize on one generated artifact" decision.

Assessment of v2.0.0: This is a major version bump and the first release worth formally assessing. Four things matter: (1) a breaking dependency upgrade to contracts v2, (2) a PHP 8.2 baseline, (3) a genuinely useful new capability — include filters for scoping output to a subset of entities — and (4) a documentation refresh. The feature is the headline; the breaking changes are cost, not value. Because this is a dev-time CLI tool rather than a production runtime dependency, a major-version break is low risk: the blast radius is a failing diagram job, not an outage. Treat v2.0.0 as the version to adopt if you are not already on v1, and as a scheduled, non-urgent migration if you are.

When to Consider This Package

Adopt when:

• The codebase is PHP 8.2+ and the team is on a current Laravel/PHP stack. v2.0.0 explicitly requires 8.2 language features, so older stacks are out.
• Your domain model lives in PHP source (Eloquent models, entities, value objects) and you want diagrams derived from that source of truth rather than from a database connection.
• You want diagrams in CI and in docs, generated reproducibly — i.e. you accept a docs-as-code workflow, including whatever binary renderer the package shells out to (Graphviz/PlantUML-class tooling) being present in your build image.
• You have a domain large enough that a single diagram is unreadable. The new include filters are the reason to look again: selective rendering is what makes this usable past a dozen entities.
• You are comfortable with a small, single-maintainer open-source dependency in a dev-only capacity, pinned and with a fallback plan.

Look elsewhere when:

• You need live, interactive, or editable diagrams for workshops — a modeling tool or whiteboard wins on collaboration; this package outputs static images.
• You want diagrams of the database schema as deployed. That is an introspection problem, not a source-parsing problem; schema-based ERD tooling is a better fit and avoids drift between migrations and models.
• You are on PHP < 8.2, or you have not yet evaluated the contracts v2 upgrade path for anything else in your dependency graph.
• You need per-commit guarantees inside a heavily customized CI, or your build image cannot add binary renderer dependencies.
• Your architecture documentation is deliberately hand-curated prose plus ADRs. Generated diagrams can add noise; only adopt if the artifact has a named consumer.

Migration note for existing v1 users: the contracts v2 upgrade is a breaking change to the package's public surface. Validate your invocation (CLI flags, config, any programmatic usage) against v2 before bumping, and pin the version in CI so a future major does not silently break your docs pipeline.

How to Pitch It (Stakeholders)

For executives (one paragraph): This is a small, free, open-source developer tool that turns our PHP source code into entity diagrams automatically, so our architecture documentation stays accurate without anyone spending days drawing boxes. The business case is onboarding speed and reduced knowledge silos — new engineers and support staff can see how the domain fits together on day one — plus lower documentation cost. Risk is minimal: it runs only on developer machines and in CI, never in production, so it adds no runtime, security, or uptime exposure. The cost is a pinned dev dependency and a small amount of CI setup.

For engineering leads: Adopt as a dev-only dependency. Requires PHP 8.2+ and a renderer binary in the build image. Generate diagrams on a schedule or on PRs, commit the outputs to a docs folder, and use the new include filters to render per-module views instead of one unreadable graph. v2.0.0 is a breaking major (dependency contracts bump to v2, PHP 8.2 features, new include filters, docs update): do a short spike to confirm our invocation still works, pin the version, and treat the upgrade as low-priority cleanup rather than a fire drill.

For the team using it day to day: The win is include filters — scope a diagram to one namespace or bounded context and get something readable in a review. Keep a single documented command in the repo (or a Composer script) so the diagram is one command away and nobody hand-edits the output.