Non Eloquent Laravel Package

Product Decisions This Supports

• Whether "API-first" means "API-only-where-a-table-exists." Every roadmap promising a consistent, spec-compliant API eventually hits endpoints with no table behind them: dashboard aggregations, reporting views, search-index results, third-party integration payloads, feature-flag objects, cached DTOs, computed resources. This package is the decision point between shipping those through the existing JSON:API layer or carving out bespoke controllers and a second, divergent contract.
• Build vs. buy on serialization for non-model resources. The build cost is small per endpoint (a hand-rolled resource class, custom include and relationship handling, one-off pagination) but compounds across an API surface. Buying it — MIT, thin adapter, a few hundred lines — is cheaper than it looks, provided the maturity caveat is accepted and owned.
• Treating the API contract as a product constraint, not a technical detail. If the promise is "one API, one set of conventions," every deviating endpoint becomes a documentation, SDK, and support liability. Adopting this keeps non-Eloquent resources on the same URL structure, include semantics, sparse fieldsets, filtering, sorting, pagination, and error semantics as everything else.
• Rejecting the fake-model anti-pattern as a standing architectural rule. The default workaround — wrapping an external call in a stub Eloquent model — creates invisible coupling, misleading migrations, and query-builder paths that never execute. Choosing this package is a deliberate, documented rejection of that pattern: a product-quality decision (fewer surprise failure modes in production) as much as a code-style one.
• Roadmap sequencing and unblocking. It decouples reporting, dashboard, and integration endpoints from schema and database workstreams. Those features can ship on their own timeline instead of waiting behind data-layer work — directly a delivery-date decision.
• Incremental API migration. Supports moving a legacy surface to JSON:API resource-by-resource — including endpoints that never had a table — rather than a big-bang rewrite gated on data-layer work.
• Constraining scope of adoption. Because this is explicitly an adapter for exceptions, adopting it is also a decision to not re-architect: it keeps the non-Eloquent case a bounded, tactical concern rather than a platform-wide shift away from Eloquent. If most resources end up non-model-backed, the architecture is the thing to question, not to patch.

When to Consider This Package

Adopt it when:

• JSON:API is already the standard and laravel-json-api/json-api is in production. This is an extension, not an entry point — it delivers value only on top of a working implementation with at least one green Eloquent-backed resource.
• A minority, not a majority, of resources are non-Eloquent. It is designed for exceptions.
• You need spec compliance for free on those resources — relationships, includes, pagination, filtering, sorting, query-parameter validation — without maintaining a parallel implementation.
• The endpoint is read-only or lightly writable. The clearest first case is read-only reference data (countries, currencies, categories, feature flags) backed by a static array or external API, implementing only all() and find().
• You have a concrete, time-boxed spike available. With 4 stars and 0 known dependents, treat this as unproven. Validate it in an afternoon against your two hardest cases: a paginated external-API-backed collection, and a resource with a to-many relationship to a real Eloquent model.
• You can own it internally. Pin the package and laravel-json-api versions, add contract tests, and assign a named owner. Budget a small internal fork or wrapper as a plausible outcome, not a disaster. The exit plan is real: keep schemas thin and repositories thick so each schema can be reimplemented as a custom adapter over the same repository.

Look elsewhere when:

• The API isn't JSON:API, or the parent package isn't in use — the package adds nothing on its own.
• Every resource is Eloquent-backed; the complexity buys you nothing.
• You need long-term support, vendor SLAs, or a deep body of community answers. Adoption risk is real: minimal stars, zero known dependents, no ecosystem safety net. You are the compatibility test suite.
• The non-Eloquent case is actually the majority of your surface — that is an architecture signal, not an adapter problem.
• You cannot absorb the security work. Authorization and scoping are not inherited the way they are through the model layer; every non-Eloquent endpoint must be audited for data leakage before it ships. That is ongoing cost, not a one-time setup task.
• The upstream data source is unreliable and you have no tolerance for defining error semantics (timeouts, 5xx, partial payloads must become deliberate JSON:API errors, not 500s).

How to Pitch It (Stakeholders)

For executives — one paragraph. We are being asked to ship API endpoints for things that don't live in a database: dashboard metrics, integration payloads, reference data, cached third-party responses. Today those either get hand-built as one-off endpoints — which fragments our API contract, bloats our docs and SDKs, and creates permanent support surface — or get faked as database models, which hides coupling and produces production failures nobody can trace. This package, MIT-licensed and a few hundred lines, lets those resources flow through the JSON:API layer we already run, so they behave identically to everything else: same includes, pagination, filtering, and error handling. The cost is small and bounded; the risk is that it is a low-adoption package, so we pin it, test the contract, and assign an owner. Recommendation: approve a one-sprint spike on our two hardest cases before committing it to any critical path.

For engineering — the honest version. It's a thin adapter on top of laravel-json-api/json-api that swaps Eloquent storage for your own repository while keeping schema definitions, requests, filtering, sorting, pagination, and relationship conventions intact. Two things to internalize before anyone writes code: (1) get an Eloquent resource green first, or you cannot distinguish a broken schema from a broken base install; (2) the adapter surface is tiny, and almost every bug will live in your field resolvers or your IDs — IDs are entirely our responsibility, and null or unstable IDs break linkage and find() in places far from the cause. Non-obvious costs: authorization is not inherited, so scoping must be wired explicitly and audited; there is no lazy loading, so includes over a remote source fan out per parent unless we batch in the repository; and sparse fieldsets mean a resolver may never run, so no side effects belong in one. Our guardrails: schemas stay thin delegators over repositories, contract tests assert on the serialized JSON:API document rather than schema internals, versions are pinned for both packages, and we feature-flag the rollout on its own server so the response shape can be A/B'd before promotion. If the package stalls, the repositories stay and each schema becomes a custom adapter — the day-to-day code does not move. That is what makes this a safe bet at this maturity level: we are buying conformance, not a dependency we can't get out of.