Api Laravel Base Laravel Package

Technical Evaluation

Architecture fit

experteam/api-laravel-base positions itself as authentication/base helper for Laravel APIs, adjacent to — not inside — the framework's own auth stack (Sanctum for tokens, Passport for OAuth2, Breeze/Fortify for scaffolding). The TPM question remains "what does it add that Sanctum does not."

Release 2.3.0 adds a useful data point here. The declared compatibility additions are illuminate/support ^12.0 and illuminate/http ^12.0 — not Sanctum or Passport. That is a meaningful signal: the package appears to sit at the framework/HTTP-helper layer rather than wrapping a specific auth implementation. If so, it is lower blast-radius than an auth-guard replacement but also lower value — it may be a base-class/response-handling layer whose overlap with our own conventions is the real evaluation question, not its security surface. This assumption should be confirmed by reading composer.json and the source in the spike; do not plan on it.

The plug-in mechanics are unchanged: service provider, publishable config, possibly migrations, guard/middleware registration. What matters is whether it wraps framework primitives with opinionated defaults (low risk, easy exit) or reimplements hashing/guard resolution (high risk, we own it forever).

Integration feasibility

Improved but not resolved. 2.3.0 states support for Laravel 9 through 12 and PHP 8.3, which materially widens the candidate surface and means our Laravel 12 / PHP 8.3 target is nominally supported. Two caveats: the release claims backward compatibility across four framework majors, which is a wide constraint surface that is only credible if backed by a CI matrix testing each combination — verify before trusting the claim; and 2.3.0 is the first release claiming Laravel 12, so it is unproven in the field with a zero-dependent install base. Mechanical integration remains composer require, publish, migrate, register.

Technical risk

The dominant risk is unchanged and is not code quality — it is signal. Zero stars, zero dependents, single-source maintainer, no third-party bug reports, no downstream project proving production survival. Adoption cost remains asymmetric: days of integration now versus a fork-and-own later.

What 2.3.0 does move is the framework compatibility risk: a maintainer who ships Laravel 12 support within the release cycle is at least tracking the ecosystem, and dropping "we're stuck on a framework major" from the top of the risk list is worth something. It does not move the abandonment risk, the bus-factor risk, or the security-review requirement. Auth-adjacent code still has the highest blast radius in an API.

New secondary risk introduced by this release: a four-major support window plus PHP 8.3 means more version combinations than a single maintainer can realistically test. "Supported" on paper and "tested" in CI are different claims; treat untested combinations as unsupported for our purposes.

Key questions

• Which Laravel and PHP versions are in the require block? Partially answered: Laravel 9–12, PHP 8.3 stated. Confirm exact constraint strings and whether a CI matrix actually runs each major.
• Does the package depend on Sanctum, Passport, both, or neither? The 2.3.0 notes name only illuminate/* — clarify whether auth is in scope at all, or whether the "auth helper" framing is ours rather than theirs.
• What does it actually own: guards, token lifecycle, refresh/revocation, rate limiting, response formatting, exception mapping, base classes?
• Are migrations and config publishable, or is a fixed schema assumed?
• Is there a documented public API surface (interfaces/contracts) we can code against, so we can swap implementations later?
• Commit cadence and issue responsiveness beyond this one release; bus factor beyond a single maintainer.
• Was 2.3.0's Laravel 12 support validated against a real app or only against a dependency bump? Changelog wording reads as constraint expansion, not feature work.
• License consistency per file (MIT declared, verify).

Integration Approach

Stack fit

Unchanged: API edge layer only — authentication, token issuance, auth-related middleware, and (per the dependency signal) possibly response/HTTP conventions. It must not reach into domain or persistence code. Our application keeps authorization (policies/gates) and user modeling. Blurring that line remains a disqualifier, not a customization task.

Migration path

Still two paths, decided before code is written:

1. Adopt as-is — if the spike confirms it is thin, framework-level helpers with a clear surface. Effort: one spike, one integration branch, low ongoing cost.
2. Adopt behind an internal seam — our own AuthService interface wrapping the package, so guard and token issuance are swappable to native Sanctum later. Costs roughly a sprint-week of extra design, converts an unknown-maintainer dependency into a reversible decision. Still recommended, and if the spike confirms the package is not auth-critical, the seam can be narrower (a thin adapter around the response/HTTP helpers rather than the whole auth path).

Path 3 (immediate fork) remains wrong — 2.3.0 is evidence the maintainer is active, which is precisely the argument against forking pre-emptively.

Compatibility

Pin 2.3.0 explicitly; do not float a range. Because this is the first release claiming Laravel 12, allow a bake period — if 2.3.1 or 2.3.2 lands within a few weeks, prefer the patch-level release, and in either case lock the transitive illuminate/* constraints at the same time. Verify resolution in a throwaway branch against our real PHP and Laravel versions; composer resolving on a greenfield app proves nothing about ours. Confirm published migrations are additive and do not collide with existing users / personal_access_tokens schema. If CI does not exercise Laravel 12, treat Laravel 12 support as claimed-but-unverified and test it ourselves in the spike.

Sequencing

1. Discovery spike (1–2 days): read composer.json and source, confirm the auth-vs-helpers scope, map the public surface, run the test suite, inspect CI matrix (does it cover 9/10/11/12 and 8.3?) and issue history. Output: go/no-go memo, re-scoped if the package turns out not to be auth-critical.
2. Isolated integration (3–5 days): sandbox branch with the seam in place; contract tests covering token issue, refresh, revoke, expired token, malformed token — plus whatever surface the spike identifies if auth is out of scope.
3. Security review (1–2 days): hashing, expiry, revocation, rate-limit behavior against our baseline. Scope down if the package owns no credential logic; do not skip outright.
4. Pilot (1 sprint): single non-critical API surface in staging with load and failure injection, on Laravel 12 / PHP 8.3 specifically.
5. Production rollout: behind a feature flag, native Sanctum (or plain framework helpers) as the documented fallback.

Operational Impact

Maintenance

Slightly improved outlook. Shipping Laravel 12 support in-cycle is the behaviour we want from a dependency and suggests we will not be the ones chasing the next major — though one release is not a cadence, and the actual lag on the previous major is worth checking in git history. The seam still means we can drop to native Sanctum within a sprint without touching call sites. Keep the standing line item — a few hours per quarter for version-bump verification — and keep the package on the security-adjacent dependency review list.

Support

No commercial support, effectively no community. Internal support falls to whoever integrates it, who must document the surface and leave runbook notes. Escalation path: open an issue, and if unanswered within X days, execute the fallback. Define X now — two weeks remains reasonable. Note that 2.3.0 being a recent, non-trivial compatibility release gives a natural responsiveness check: how the maintainer handles issues filed against the new major is a good proxy for the whole relationship.

Scaling

Unchanged in substance. Auth/HTTP helpers are rarely the bottleneck; token validation should be O(1) lookups per request. The questions are extra per-request queries (guard resolution duplicating a user lookup our middleware already does) and whether any revocation list is cached or hits the database on every call. Measurable in the pilot with a simple load test; profile rather than assume. If the package proves to be response-formatting only, scaling impact is negligible and this section collapses to "no material concern."

Failure modes

• Maintainer abandonment — highest likelihood, high impact; mitigated by the seam and a pre-scoped fork plan. 2.3.0 reduces the near-term probability but does not remove it.
• Silent security regression in a patch release — version pinning, lockfile discipline, changelog review before bumping.
• Framework incompatibility on a future Laravel major — partially mitigated by the demonstrated in-cycle support; the seam still provides the exit.
• Claimed-but-untested version combinations — new/elevated: a 9–12 × PHP 8.3 support window is more surface than one maintainer likely tests. Our contract tests must own the specific combination we run.
• First-release-on-a-major defects — 2.3.0 is the initial Laravel 12 claim; prefer a follow-up patch or extra soak time in the pilot.
• Schema collision — publishable migrations conflicting with existing auth tables; caught in the spike.
• Undocumented behaviour drift — response shapes or error codes changing between minors; caught by contract tests in step 2.
• Bus factor of one — no second reviewer; our own review and tests carry the assurance burden.

Ramp-up

Low and essentially unchanged for any Laravel-fluent engineer: standard idioms — service provider, config publish, guard, middleware. Under a day to a first working integration; two to three days to genuine confidence, provided the spike resolves whether auth is actually in scope. The cost is not learning the package; it is the test coverage and the seam that make the package non-load-bearing. Onboard around the contract tests, not the README — with zero dependents, our tests remain the only external validation this code will get.