Api Model Laravel Package

Product Decisions This Supports

Correcting the scope before it gets funded. The package description reads "Generate Laravel-like Api Models," but nothing is generated — no artisan command, no controllers, no routes, no migrations, no request validation pipeline. What actually ships is one small abstract base class that hydrates a decoded JSON array into a read-only, Eloquent-flavoured object: $user->company->geo->lat, declarative $cast_model mapping, lazy hasOne/belongsTo/hasMany relations, included_default eager loading, cast_dates/date_timezone, and a thin $requiredParameters existence check. Any business case phrased as "ship endpoints faster" is the wrong case and will fail at review. The defensible case is narrower and real: make third-party payloads legible, reviewable, and cheap to change at the integration boundary.

The build-vs-buy call at the integration edge. Every product that consumes someone else's JSON — CRM, HRIS, payments, partner feeds, internal service-to-service calls — accretes an ad-hoc layer of $data['company']['geo']['lat'] ?? null spelunking. The genuine decision set is: hand-rolled arrays, a bespoke in-house DTO, spatie/laravel-data, JsonResource, or this. MIT licensing means this option is a capped-cost experiment, not an architectural commitment — you can try it without mortgaging the roadmap.

Roadmap sequencing for integration work. It supports a deliberate "ship the integration, defer the clean domain model" sequence: get partner data visible in the product, then decide separately whether the access pattern has earned typed DTOs. Lazy relation loading means you don't pay for relationship graphs you never traverse — which matters commercially when a slow vendor returns fat nested payloads and you want a page to render without a hydration tax.

Vendor-swap and schema-drift resilience — with an explicit caveat. Nested objects are addressed by name, not array offset, so replacing one upstream provider with another becomes a mapping change (a $cast_model line plus a few relationship methods) rather than a codebase-wide hunt. That gives a commercial decision — "we're switching vendors" — an estimable engineering cost, which is often the thing that makes the switch politically possible. The caveat is material: unknown fields return null silently, so upstream schema drift is indistinguishable from a legitimately absent optional field until something breaks. Fixture-based contract tests are the compensating control and must be treated as part of the adoption cost, not an optional extra.

A house-style decision across teams. Adopting it establishes one convention for consuming external APIs that any Eloquent-literate engineer can read on day one — model classes are 10–30 lines, one file per upstream resource, and a reviewer sees the entire API contract on a single screen. That is a real onboarding and code-review argument in a Laravel shop, and it is directly comparable to a laravel-data convention, so it should be decided as a convention, not as a dependency.

Best-fit use cases to fund. Internal tooling, admin surfaces, prototypes, timeboxed integration spikes, and low-traffic read-only integrations where payloads are deeply nested and relational. Not a fit for: write paths, round-trip serialization, request building, or customer-facing SLA paths where maintenance risk cannot be absorbed.

Where it must not drive a decision. It says nothing about API versioning, auth, rate limiting, caching, retries, or endpoint design — transport is deliberately out of scope, and the companion "API Call library" referenced in the README has never shipped. Treat it as read-path convenience only, and keep it behind a thin internal interface (ApiGateway, per-integration repository, or service returning native arrays/your own DTOs) so the build-vs-buy decision stays reversible.

When to Consider This Package

Consider it when:

• You are on Laravel or Laravel-adjacent PHP and the team already thinks in Eloquent — the entire value proposition is "the access pattern is already familiar."
• You are consuming JSON, yours or a vendor's, and only reading it. There is no write path.
• Payloads are deeply nested and relational (data.company.geo.lat, posts.data[]) — exactly the shape where bracket access becomes unreadable.
• You want the mapping declared, not generated: a small App\Api\Models namespace of short classes. A plus if reviewability matters to you; a minus if the sponsor expected scaffolding.
• The work is internal tooling, an admin surface, a prototype, or a timeboxed integration spike where being wrong later is cheap to undo.
• You need a Carbon/date-and-timezone convention for external payloads and are content to adopt theirs.
• You can vendor the small surface you depend on (MIT makes this legal and cheap) or explicitly accept fork risk.

Look elsewhere when:

• Adoption signal is the deciding factor — and it is near zero. Four stars, zero dependents, a single-org namespace, and an unshipped companion library. Read that honestly: this is a published internal library. Assume you are also the maintainer, with no community answers, no tutorials, and a real chance the next Laravel major breaks it with nobody upstream fixing it.
• You need two-way traffic. No documented request building, outbound validation, or resource serialization. For request/response DTOs, spatie/laravel-data or plain JsonResource remain the mature answers.
• Static analysis has to hold. Attribute access is dynamic property resolution; without @property docblocks you lose IDE completion and PHPStan confidence. If contract-typed models are the goal, an OpenAPI-driven generator is stronger; for ergonomic API connectors specifically, Saloon.
• You need guarantees at the edges. $requiredParameters is effectively a "this model must exist" check, not field-level validation. Real validation, error semantics, and retry policy are yours to write.
• Performance is load-bearing. Dynamic property resolution and lazy hydration across large collections have no published benchmark; you must own that measurement before wiring it into a hot path.
• You cannot absorb maintenance risk on a customer-facing SLA path — or you are not on PHP/Laravel at all.
• You need a documented support matrix. Compatibility and breaking-change history are thin; verify release timestamps against actual tags before planning around them.

How to Pitch It (Stakeholders)

For executives — one paragraph. This is a small, MIT-licensed Laravel helper that makes third-party API responses readable in code. It does not generate endpoints, controllers, or validation, and it should not be sold as a delivery accelerator. It is a low-cost, reversible standard for the read side of integrations — the place where vendor payload handling currently rots into unreadable array access. The ask is not "adopt this"; the ask is "fund a two-day spike and a convention decision," with a defined exit if it doesn't beat the alternative.

For engineering — the honest framing. One abstract base class, no service provider, no config, no migrations, no HTTP. You hydrate a decoded payload at the boundary and read it with Eloquent-style access; relations are lazy; dates route through Carbon::parse(). The name is a trap — nothing is generated. The base class is small enough to read in one sitting, which is the strongest practical argument for vendoring it: the moment this touches anything that matters, fork it into packages/ and treat it as your own code.

The risk story, stated plainly. Four adoption risks, all manageable, none free:

1. Silent nulls. Unknown or renamed keys return null indistinguishable from a legitimately absent field. Mitigation: $requiredParameters plus one fixture-based contract test per model asserting every field and relation the app touches. This is non-negotiable and is the first thing built.
2. Thin validation. $requiredParameters is an existence check, not field validation. You write the real validation and error handling.
3. No static analysis by default. Add @property docblocks from the first model class — retrofitting across a dozen classes is tedious.
4. Unmaintained upstream. Four stars, zero dependents, no support matrix. Mitigation: vendor it, and keep it behind an internal interface so a swap to spatie/laravel-data is a one-file change.

The decision we're asking for. Approve a two-day spike, scoped tightly: pick one low-traffic, deeply nested, read-only endpoint (not the most important customer-facing call), build two or three real payloads behind an internal gateway interface, add the fixture tests, and run them head-to-head against a laravel-data DTO of identical shape. If the Eloquent ergonomics don't win clearly, we've spent two days instead of a quarter. If they do, we adopt it as a house style for read-only external API consumption, document the @property and fixture-test conventions, and vendor the dependency before it reaches anything with an SLA.

The one-line version for the roadmap deck. "A cheap, forkable convention for reading partner payloads — reversible by design, funded as an experiment, not adopted as architecture."