Api Bundle Laravel Package

Technical Evaluation

Intake correction first. The request describes this as a "Laravel/PHP package." It is neither a Laravel package nor a standalone library — sylius/api-bundle is a READ-ONLY subtree split of src/Sylius/Bundle/ApiBundle from the Sylius/Sylius monorepo, and it is a Symfony bundle that assumes the Sylius resource registry, Doctrine ORM, the Symfony DI container, and API Platform. The PM action this triggers is to reclassify the intake item before it enters a backlog: it is not an integration candidate for a Laravel codebase, it is a property of a platform decision we may or may not have already made. The 5 stars / 0 dependents / 0.145 score are artifacts of the split-repo publishing model, not adoption signals — do not let a sourcing dashboard rank this against genuine Laravel candidates. Judge it by (a) whether we run Sylius, and (b) which Sylius version we are pinned to.

Architecture fit. Viable in exactly one configuration: the org operates Sylius as a headless commerce backend and a Laravel (or Next.js, or native) application as the client. In that configuration this bundle is not a dependency of the Laravel app at all — it is the API surface of a system we own. In any other configuration the fit is zero, and the correct TPM output is a redirect: if the actual need is "expose commerce data over HTTP from a Laravel app," the comparison set is API Platform used directly, or Laravel-native options (Sanctum + API Resources + a query layer). Conflating the two will produce a scoped project that cannot be built.

Integration feasibility. Low as a package install; moderate as a service integration. The realistic paths, in the order a TPM should fund them:

1. Headless service boundary (recommended). Sylius runs independently; Laravel consumes its REST/JSON-LD surface as an external system with a versioned contract. This is an integration project with a clear client/server split and independent deploy cadence.
2. Contract-reference only. Use this bundle's routing, serialization groups, and operation definitions to derive the API contract, then implement a Laravel-native client. Contract reuse, zero code reuse. Cheapest if we cannot stand up Sylius yet.
3. Platform consolidation. Fold the Laravel app into a Symfony/Sylius application. This is a migration, not an integration; scope and staff it as a multi-quarter program or refuse it.

Technical risk — high, and mostly schedule risk rather than technical risk. The bundle is read-only: issues and PRs are not accepted here, patches go upstream or into a fork of the full monorepo. The REST bundle is also the legacy surface relative to Sylius's API Platform direction, so adoption buys a narrower upgrade runway than the current platform layer. The residual hazard is that we inherit a contract we can observe but not steer.

Key questions to settle before any estimate is written:

• Are we integrating the bundle or the Sylius API contract? They are different projects; only the second is deliverable here.
• Do we actually run Sylius today? If no, this item is a platform-selection question mis-filed as a package evaluation — route it to architecture, not to a sprint.
• Which Sylius version, and is its API the legacy REST bundle or API Platform? The answer changes auth model, serialization semantics, and everything downstream of the estimate.
• Who owns cart, pricing, inventory, and order state? Overlapping ownership between Laravel and Sylius is the dominant long-term defect source and the thing most likely to blow the budget after launch.
• Read-only or write-path? Catalog and order queries are a low-risk read integration; cart mutation, checkout, and payments raise the risk profile by an order of magnitude and must be planned as a separate phase with separate acceptance criteria.
• Who is the escalation path for contract breakage? Today it is us, not the vendor, unless we buy commercial Sylius support.

Integration Approach

Stack fit. Treat the boundary as HTTP and nothing else. Laravel and Sylius share no abstractions — different container, ORM conventions, serialization, routing — so the only durable contract is a versioned API. Reference stack on the Laravel side: a Saloon connector, DTOs (spatie/laravel-data), a per-resource caching decorator, queue-backed webhook ingestion, and a circuit breaker with stale-cache fallback. The TPM deliverable here is the contract ownership plan, not the library list: who regenerates the OpenAPI snapshot, who reviews drift, and what CI gate fails on a breaking change.

Migration path. Gate the work rather than sequencing it as a single project:

1. Decision gate — headless split vs. platform consolidation. Nothing downstream is fundable until this is recorded. This is the TPM's primary leverage point in the whole assessment.
2. Spike (timeboxed). Stand up Sylius in Docker against a seeded catalog and enumerate the endpoints the product actually needs: catalog read, price, stock, cart, checkout, order status. Output is an endpoint inventory with owners, not a demo.
3. Contract capture. Generate and commit an OpenAPI snapshot. This artifact — not the Composer constraint — is what we version against and what we cite in stakeholder updates about the "contract."
4. Client layer with contract tests running against the snapshot; CI fails on drift.
5. Auth as a first-class service (token acquisition/refresh), never inline in controllers.
6. Dual-run. Laravel reads from Sylius while writes stay on the existing path; compare via shadow traffic before promotion.
7. Cutover per domain — catalog → pricing → cart → checkout → orders. Publish this sequence as the roadmap; it gives stakeholders visible milestones and gives engineering a rollback boundary at each step.

Compatibility. Pin an explicit Sylius minor version and record the PHP/Symfony/Doctrine matrix alongside it. Because the bundle is split from the monorepo, constraints resolve against sylius/sylius — verify the transitive resolution before promising an isolated upgrade.

Sequencing constraint to state in the plan. Auth, caching, and error normalization must land before the first write-path integration. Retrofitting them after checkout is wired in is where the schedule overrun lives; put it in the plan as an explicit predecessor, not a hardening task.

Operational Impact

Maintenance. We will not patch this repository. Customization means forking Sylius/Sylius or waiting on upstream — a recurring cost, not a one-time one. Budget a standing ritual of tracking Sylius release notes and re-running contract tests on each upgrade, and make that ritual someone's named responsibility rather than a general expectation.

Support. Community-only for the bundle; commercial Sylius support exists at the platform tier and is worth pricing before commerce becomes revenue-critical, because negotiating leverage is highest pre-commitment. Assume the team is the escalation path for anything contract-related, and staff accordingly.

Scaling. Two systems to deploy, scale, and observe independently. The API layer adds serialization/hydration cost on the Sylius side and network latency on the Laravel side; historically Sylius API collection reads have been prone to N+1 patterns. Mitigations to fund upfront: response caching for catalog, edge caching for anonymous traffic, and enforced pagination discipline on the client.

Failure modes to design for now — these are the risk register entries the TPM owns:

• Contract drift across Sylius upgrades (serialization groups, field renames, pagination defaults) — mitigated by the committed OpenAPI snapshot and CI drift gate.
• Checkout state divergence between Laravel session state and the Sylius cart/order state machine mid-flow — highest-visibility customer-facing failure; requires an explicit recovery/compensation story.
• Inventory race conditions on concurrent add-to-cart and checkout across two systems with no shared transaction boundary.
• Token expiry / auth rotation surfacing as sporadic 401s under load.
• Webhook loss or reordering — order and payment status events must be idempotent and replayable.
• Cascading failure — Sylius latency propagating into Laravel request latency without a breaker and stale-cache fallback.

Ramp-up. The team needs Symfony, Doctrine, and Sylius domain literacy on top of existing Laravel skills — a persistent two-framework cognitive tax, not a one-sprint onboarding cost. Plan for one engineer owning the Sylius side full-time during integration and part-time in steady state, plus a written runbook for the commerce boundary before the first write path ships. For planning honesty: if we cannot justify that dedicated ownership, the honest recommendation is to keep the storefront server-rendered until a second sales channel actually exists, and revisit this item then.