Weave Code
Headless Bundle Laravel Package
sulu/headless-bundle
SuluHeadlessBundle provides controllers and services for using the Sulu CMS in a headless way. It exposes page content as plain JSON and offers APIs for navigation contexts and snippet areas, replacing Twig template features. Compatible with Sulu 2.0 and later.
Bundle that provides controllers and services for using Sulu as headless content management system
Frequently asked questions about Headless Bundle
- Can I use sulu/headless-bundle with Laravel instead of Symfony?
- No. SuluHeadlessBundle is a Symfony bundle that expects Symfony's kernel, container, and bundle registration, so it cannot be loaded inside a Laravel application. Run Sulu as a separate content service and have Laravel consume its JSON endpoints over HTTP with the Laravel HTTP client.
- How do I get Sulu page content as JSON for a Laravel frontend?
- Install the bundle in the Sulu project, enable it in config/bundles.php, and include its portal routes in config/routes/sulu_headless_website.yaml. The bundle then exposes a controller that returns Sulu page content as plain JSON. In Laravel, call that endpoint with the HTTP client, map the payload to your own DTOs, and cache the result.
- Which Sulu, Symfony, and PHP versions does sulu/headless-bundle support?
- The README states compatibility with Sulu 2.0 and newer, while the compatibility badge targets Sulu 3.0 and above; always check the require section of composer.json for the current constraints. Release 3.0.2 adds Symfony 8 support, which typically implies a modern PHP floor, so verify it against your Laravel runtime before committing. If the PHP floor is too high, pin a 3.0.x release that matches your Symfony major.
- How do I install and enable SuluHeadlessBundle?
- Run composer require sulu/headless-bundle in the Sulu project, then add Sulu\Bundle\HeadlessBundle\SuluHeadlessBundle::class to config/bundles.php. Create config/routes/sulu_headless_website.yaml with type portal and the bundle resource, and clear the cache. This is Sulu-side configuration; there is no Laravel service provider or config file to publish.
- How do I access navigation contexts and snippet areas through the headless API?
- The bundle provides APIs for navigation contexts and snippet areas that replace the Twig extensions used in traditional Sulu templates. From Laravel, call those endpoints over HTTP, map the responses to your navigation and snippet DTOs, and cache them with the same policy as page content. Validate the payload shape per Sulu upgrade because these responses are coupled to Sulu core.
- Is sulu/headless-bundle stable enough for production use?
- Treat it as under development: the README warns that future versions may contain breaking changes depending on community feedback. Pin both the bundle and Sulu core to explicit versions, and treat every Sulu minor as a potential payload contract change. Operationally you also take on a second application, database, and deployment pipeline.
- What changed in sulu/headless-bundle 3.0.2 and will it break Laravel consumers?
- Release 3.0.2 is a patch that aligns expected response payloads with media properties introduced in Sulu 3.0.9 and adds Symfony 8 support. Tolerant consumers that ignore unknown fields should be fine, but strict DTOs or deserialisers on the Laravel side can fail when new media properties appear. Pin versions and validate payloads against the Laravel mapping layer in CI.
- How do I test Sulu headless API responses in a Laravel test suite?
- Use Laravel's HTTP client with a fake or a recorded fixture of the Sulu endpoint, then assert your mapper and cache decorator behaviour rather than the bundle itself. Include contract tests that deserialise real payloads from the pinned Sulu version and fail on unexpected shape changes. Also test preview-mode authentication and cache bypass paths.
- How should I handle caching and preview mode for Sulu headless content in Laravel?
- Cache page, navigation, and snippet responses in the Laravel application and at the CDN, using a cache decorator around the content client. Add a preview-mode switch that bypasses the cache and authenticates draft content against Sulu. Measure latency and cache hit rate during the first route-group migration.
- What are the alternatives to sulu/headless-bundle for a headless CMS in Laravel?
- If Sulu is not already the selected CMS, a native Laravel CMS package or a SaaS headless CMS is usually a simpler fit than adding a Symfony application to the estate. Choose SuluHeadlessBundle when Sulu is already the content platform and Laravel is the delivery application. Otherwise, you own the integration glue, two dependency graphs, and two upgrade cadences.
Weaver
How can I help you explore Laravel packages today?