Headless Bundle Laravel Package

Technical Evaluation

Architecture fit This is not a Laravel package. sulu/SuluHeadlessBundle is a Symfony bundle that exposes Sulu CMS content as headless JSON endpoints. Adopting it means introducing a second PHP runtime and framework (Symfony/Sulu) alongside the Laravel application, with Laravel acting as a consumer or BFF rather than a host. The bundle is only a fit if the organisation is willing to operate Sulu as a separate content service; it should not be treated as a drop-in Laravel CMS component.

Integration feasibility Feasible but indirect. Laravel would talk to Sulu's content endpoints over HTTP using the existing HTTP client, a typed content mapper, and an application-level cache. The 3.0.2 release is a patch: it aligns expected response payloads with media properties introduced in Sulu 3.0.9 and adds Symfony 8 support. Both changes are low-effort to adopt, but the media-property change signals that the response contract is coupled to the Sulu core version — consumers must pin and verify payload shapes per upgrade.

Technical risk

• Framework mismatch (high): no Laravel service provider, config, or published contracts; all integration glue is ours to build and maintain.
• Contract drift (medium): response expectations moved with Sulu 3.0.9 media properties. Any strict DTO or deserialiser on the Laravel side could fail on newly added fields.
• Version coupling (medium): Symfony 8 support typically implies a modern PHP floor and an active upgrade treadmill; the bundle tracks Sulu and Symfony minors closely.
• Operational surface (medium): a second application, database, and deployment pipeline enter the estate.

Key questions

1. Is Sulu already the selected CMS, or is this bundle being evaluated as a way to get content into Laravel? If the latter, a native Laravel CMS or a SaaS headless CMS is likely a better fit.
2. What is the PHP version floor implied by Symfony 8 support, and does it match our Laravel runtime?
3. Which media properties changed in Sulu 3.0.9, and do our consumers deserialise strictly or tolerantly?
4. Do we need Sulu's preview/versioning workflow in the Laravel front end, and how is draft content authenticated?
5. Who owns the Sulu instance operationally — is there existing Symfony/Sulu capability in the team?

Integration Approach

Stack fit Laravel remains the delivery application; Sulu runs as an independent, separately deployed content service. The integration layer is a thin Laravel-side content client: HTTP transport, response mapping to application DTOs, cache decorator, and a preview-mode switch. Do not attempt to load the bundle inside a Laravel application — the bundle assumes Symfony's kernel, container, and bundle registration.

Migration path Route-by-route cutover rather than a big-bang move. Stand up Sulu, model content types, build the Laravel content client, then migrate page templates incrementally behind a feature flag, keeping the existing content source authoritative until parity is confirmed for each route group.

Compatibility Verify the PHP floor introduced by Symfony 8 support against the Laravel runtime before committing; if the floor exceeds the application's PHP version, stay on the 3.0.x line that matches the current Symfony major. Pin both the bundle and Sulu core to explicit versions and treat any Sulu minor as a potential payload contract change. Media property additions should be validated against the Laravel mapping layer in CI.

Sequencing

1. Spike: stand up Sulu + headless bundle, confirm endpoint shape and media payload for a representative content type.
2. Define the Laravel content client contract and tolerant deserialisation strategy.
3. Build caching (application cache + CDN) and preview handling.
4. Migrate one low-traffic route group; measure latency and cache hit rate.
5. Expand coverage; decommission the legacy content path per group.

Operational Impact

Maintenance Two codebases, two dependency graphs, two upgrade cadences. The bundle's tight coupling to Sulu core means Sulu upgrades and bundle upgrades must ship together; budget a recurring maintenance slot per Sulu minor rather than treating this as install-and-forget. The Laravel content client is our code and will need versioning whenever the payload contract moves.

Support No vendor support path; reliance on upstream maintainers and community issue response. Internal ownership must be explicit — nominally the Laravel team owns the client, but Sulu instance ownership requires Symfony skills that a Laravel-only team will not have by default.

Scaling Content delivery scales well if cached: Sulu is read-mostly, so application-level caching plus a CDN in front of the Laravel layer absorbs most traffic. The Sulu instance itself scales modestly; the real risk is uncached request fan-out during cache misses or purge storms, particularly on media-heavy pages.

Failure modes

• Sulu endpoint outage or latency spike degrades the Laravel front end unless a stale-cache fallback is in place.
• Cache invalidation lag produces stale content after editorial publish.
• Preview/draft content leaking into a shared production cache.
• Silent payload drift after a Sulu or bundle upgrade breaking mapping or rendering.
• Upgrade deadlock: bundle pinned by Sulu version, Sulu pinned by Symfony version, Symfony pinned by PHP version.

Ramp-up Non-trivial. The Laravel team can absorb the consumer side quickly (HTTP, caching, DTOs), but content modelling and any Sulu-side changes require Symfony/Sulu competence. Plan for a spike plus at least one engineer with Symfony familiarity, or accept a slower initial delivery and heavier reliance on upstream documentation.