Legacy Api Laravel Package

Technical Evaluation

Architecture fit. bagisto/legacy-api is a compatibility shim, not a platform component. It re-exposes Bagisto's pre-upgrade REST conventions — catalog, search, cart, checkout, customer accounts, orders, invoices — on top of current core services, so it belongs in the integration tier of the architecture, running alongside the current API rather than replacing it. That is a good structural fit for a strangler-style migration: legacy and modern surfaces coexist behind distinct route prefixes, distinct middleware groups, and distinct rate limiters, and one can be retired without touching the other. What it is not is a versioned public API. There is no contract governance, no deprecation policy, and no supported-version matrix baked into the package — those become internal obligations the moment we install it.

Integration feasibility. Mechanically simple: a standard Laravel service provider, package discovery, a publishable config, and a Composer install. v1.0.0 (the only release, 2021-11-19) deliberately removed the module service-provider dependency and pulled JWT handling out of Bagisto core and into this package — which tightens the coupling to the JWT library but simplifies bootstrapping. The gating question is the three-version matrix: Bagisto core version, Laravel/PHP runtime, and the JWT dependency constraint must all be read off the 1.0.0 tag before engineering time is committed. If the bagisto/* constraint excludes our current major, this is a fork project, not an install project, and the estimate changes accordingly.

Technical risk. Ranked:

1. Silent response drift (highest). Legacy payloads are rendered from live core models and serializers. A Bagisto upgrade that renames a field or changes a cast breaks mobile clients with no deploy on our side. This fails quietly, in pagination envelopes, null handling, and error codes — not with a stack trace.
2. Zero upstream assurance. One release in 2021, five stars, zero dependents. Nobody is contract-testing this against current Bagisto, and no security policy exists. Assume community-only and internally owned.
3. Auth blast radius. v1.0.0 concentrates JWT issuance, expiry, and revocation inside this package. JWT divergence presents as blanket 401s that look like client bugs, and a missed secret rotation on the legacy guard is a full outage of the bridge.
4. Route shadowing. A legacy prefix of api can steal or lose routes to the current API depending on registration order and config cache state.
5. Dependency resolution. Composer conflicts trace to the JWT constraint; the fix is usually a loosened fork, not a different package.

Key questions for the team.

• What is the exact Bagisto / Laravel / PHP / JWT version tuple on the 1.0.0 tag, and does it admit our stack?
• Who are the named consumers of each legacy endpoint, and which endpoints have no consumer (and should therefore never be registered)?
• Do we have, or can we produce within one sprint, golden-response fixtures for every endpoint we expose?
• Is the JWT secret and TTL for the legacy guard distinct from APP_KEY and from the primary API's guard?
• Who is the internal owner for patches, advisories, and Bagisto-version compatibility — by name, not by team?
• Does a replacement API exist on the roadmap, and what is the client-migration plan that makes the sunset date executable?

Integration Approach

Stack fit. Laravel-native and conventional: service provider, published config, middleware pipeline, standard guard configuration. It slots into an existing Bagisto deployment without a new runtime, new datastore, or new deploy target. That is the main reason to prefer it over reproducing legacy conventions in-house — the glue is cheap; the ongoing ownership is not.

Migration path. Frame this as a time-boxed strangler bridge, approved as a migration ticket with an owner, a contract-test artifact, and a sunset date attached — not as a routine composer require.

1. Pin the version matrix and read the 1.0.0 composer.json constraints.
2. Install exact: composer require bagisto/legacy-api:1.0.0 --with-all-dependencies. No caret range — there is no release cadence to benefit from, and this ships auth-adjacent code.
3. Publish config, clear caches (config:clear, route:clear, optimize:clear), and verify routes materialized via route:list, noting the actual prefix.
4. Configure, in order: explicit legacy-flavoured route prefix (legacy/api, api/v1-legacy), a dedicated middleware group, and explicit JWT secret/TTL via env.
5. Prove one read endpoint end-to-end (product or category listing), capture the raw response to a fixture, and diff it against what the shipped clients actually parse. This is the day-one cost discovery, and day one is the right day for it.
6. Then, and only then, enable cart and checkout flows.

Compatibility. Two compatibility axes, both owned internally:

• Coexistence: separate prefix, middleware group, and throttle:legacy rate limiter so a runaway mobile client cannot degrade the primary API. Assert in CI (via route:list --json) that no URI is duplicated across legacy and current route collections.
• Contract stability: golden-response fixtures — real captured payloads asserted for envelope shape, field names, and pagination — run as a mandatory step on every Bagisto core bump. This artifact is the thing that makes the bridge safe, and it is ours to build and own.

Sequencing.

• Guard isolation first when migrating auth: land the legacy JWT guard as its own entry in config/auth.php with its own provider and secret, keep it mutually exclusive with any Sanctum migration, and do not stack the two. One lands, then the other.
• Endpoint surface second: treat the package's full route list as a menu, not a contract. Maintain an inventory — endpoint → consuming client → named owner — and gate route registration on it. Every route left on is a promise not to break it plus an auth surface to audit.
• Sequence tests third: cart and checkout are stateful (create cart → add item → shipping → payment → order) and depend on the client echoing a cart identifier. Per-endpoint tests will pass while the sequence is broken; wrap the whole walkthrough in one integration test.
• Vendoring decision in parallel, not later: MIT plus zero upstream cadence means buy-then-own. Stand up a VCS fork repository (dev-main as 1.0.0) early so JWT constraints or serializers can be patched without waiting for a release that will not come.
• Ship a kill switch with the install: one env-guarded config flag that stops registering legacy routes, so the surface can be disabled during an incident and the sunset date is executable rather than aspirational.

Operational Impact

Maintenance. This is an internal maintenance line item, not a vendor dependency — budget it that way from the start. The recurring work is: JWT security advisories, dependency bumps against a 2021 constraint set, drift fixes when Bagisto internals move, and fork rebases. Expect the Composer friction to concentrate on the JWT library; keep composer why-not in the runbook. A bridge with no named owner degrades into a permanently unsupported second API surface, at which point removing it is a client-release coordination problem rather than a config change.

Support. Community-only. No vendor SLA, no published security policy, no supported-version matrix, no upstream contract testing. Escalation for upstream silence is internal by default. The compensating controls are the contract-fixture suite (our detection mechanism for silent drift) and the fork (our remediation mechanism). Both must exist before go-live, not after the first incident.

Scaling. The bridge itself is thin — it translates requests onto core services — so it scales roughly with the primary API and adds middleware overhead, not a second application tier. The real scaling concern is isolation: a separate rate-limit bucket sized to actual legacy traffic, and a separate log channel and metrics dashboard tagged by route prefix. That separation is what keeps the blast radius visible when the bridge misbehaves or is attacked, without querying primary-API telemetry.

Failure modes to instrument explicitly.

• Blanket 401s → JWT divergence (wrong secret, resolved JWT library version, TTL outside client assumptions, missed rotation). Alert on 401 rate per legacy endpoint; that signal distinguishes auth divergence from genuine client errors.
• Schema drift → clients break with no deploy on our side. Detected only by the fixture suite; make its run mandatory on every core upgrade even when nothing looks wrong.
• Route shadowing → current API loses or wins routes unexpectedly. Inspect route:list -v after every config change.
• Inconsistent route registration across environments → provider boot order or stale config cache after the module-provider removal. optimize:clear first, artisan about second.
• Broken cart sequences → per-endpoint green, end-to-end red. Covered by the sequence test.
• Orphaned surface → no consumers, no owner, no sunset. Prevented by the endpoint inventory and the kill switch.

Ramp-up. Low code-learning curve, high process-learning curve. An engineer familiar with Laravel service providers and Bagisto's domain can be productive on the package in a day; the expensive knowledge is operational — which guard signs which token, which prefix maps to which surface, what the fixtures cover, and what the rotation procedure is. Write the runbook the day you install it: secret rotation procedure, per-endpoint kill switch, contract-fixture update process, fork-and-patch procedure, and an escalation path that assumes upstream stays quiet. Plan for roughly one sprint to reach a trustworthy first-endpoint-plus-fixtures milestone, and treat cart/checkout enablement as a separate, later commitment gated on the sequence test passing.