Laravel Relation Parser Laravel Package

Product Decisions This Supports

• Build vs. buy for relationship introspection. If a roadmap item needs to know "what relations does this model have, and what type are they?" (dynamic eager loading, include/embed query params, graphQL-style field selection, ERD/lineage tooling, admin scaffolding, data export with nested resources), this package replaces a hand-rolled regex/AST file-scanner that is easy to start and expensive to keep correct. Default to buying unless relationships are defined dynamically at runtime, which this class of package generally cannot see.
• Feature: API sparse-fieldsets and ?include= support. Parsing model relations at boot lets you validate requested relations against what actually exists, fail fast with 422s instead of N+1s or runtime errors, and build an allowlist per endpoint — a common enterprise/API-contract requirement that otherwise gets duplicated per resource.
• Feature: schema visualization and documentation artifacts. Feeds auto-generated ERDs, onboarding docs, and impact analysis ("who joins to orders?") without a separate diagram tool drifting out of date.
• Roadmap signal: Laravel 13 readiness. v1.4.0 is a compatibility release adding Laravel 13 support. For planning purposes this is the key fact: the package tracks framework majors, so it will not silently block your Laravel upgrade — but it also carries no new product capability, so it should not move the roadmap.
• Risk-management decision. This is a single-maintainer package with a narrow scope. Treat adoption as a small, contained dependency: fine to build on top of, not fine to build a core platform capability on without an internal fallback.

When to Consider This Package

Adopt when:

• Your Eloquent models declare relations conventionally (typed method signatures, $this->hasMany(...) / belongsTo(...) returns) and are the single source of truth for the data graph.
• You are on, or actively migrating to, Laravel 13 — v1.4.0 is the release that unblocks that upgrade path. Pin ^1.4 rather than ^1.3 if Laravel 13 is on your horizon.
• You need this in support of a bounded feature (API includes, docs generation, admin tooling) and can tolerate the parser being unable to resolve relations defined in traits, dynamic loops, config-driven definitions, or non-standard return types.
• You want to avoid owning an AST parser. nikic/php-parser is the heavier foundation if you ever need to go deeper, but it is a much larger commitment than this package's surface area.

Look elsewhere (or build in-house) when:

• Relations are resolved at runtime through magic methods, service providers, or database-driven definitions — static parsing will miss them, and partial correctness is worse than none for access-control or validation use cases.
• The need is purely runtime and already served by core Laravel: Model::getRelation(), getRelations(), resolveRelationUsing(), and with() accept dynamic input on an instantiated model without any extra dependency. Prefer core if you can instantiate the model.
• You require long-term vendor support, SLAs, or a security review of every dependency — a single-maintainer package should go through your standard third-party intake, including a check on release cadence and CI coverage.
• Performance is on a hot path: parsing model source files is a build/boot-time activity, not a per-request one. Cache the parsed output if you are tempted to call it in a request cycle.

How to Pitch It (Stakeholders)

For executives: We are evaluating a small open-source Laravel package that lets our application read its own data model — which tables relate to which — instead of us maintaining custom parsing code. It unlocks API features customers ask for (choosing which related records come back in one call) and auto-generated data diagrams for onboarding and audits. The v1.4.0 release is a maintenance update that adds Laravel 13 compatibility, which means adopting it now does not jeopardize our framework upgrade. Cost is near zero; the main risk is that it is maintained by one person, so we are scoping it to non-critical features with a plan to swap it out if it stalls.

For engineering: This is a narrow, well-bounded utility — it parses Eloquent model classes to enumerate relations and their types. Use it for ?include= allowlist validation, ERD/doc generation, and admin scaffolding. Do not put it on a request hot path; parse once at build/deploy and cache the result. It is a static analysis of model source, so anything dynamic (traits, config-driven relations, resolveRelationUsing) will be invisible — validate that assumption against our model inventory before committing. Where we only need relations on a live instance, core Laravel methods already do the job and we should not add the dependency. v1.4.0 is a Laravel 13 compatibility bump with no API changes, so the upgrade is low-risk; pin ^1.4 and add it to the third-party dependency review queue given single-maintainer status.