PHPackages sulu/headless-bundle - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. sulu/headless-bundle ActiveSulu-bundle[API Development](/categories/api) sulu/headless-bundle ==================== Bundle that provides controllers and services for using Sulu as headless content management system 3.0.1(1mo ago)56150.4k↓16.7%26[18 issues](https://github.com/sulu/SuluHeadlessBundle/issues)[4 PRs](https://github.com/sulu/SuluHeadlessBundle/pulls)2MITPHPPHP ^8.2CI passing Since Jul 13Pushed 1w ago6 watchersCompare [ Source](https://github.com/sulu/SuluHeadlessBundle)[ Packagist](https://packagist.org/packages/sulu/headless-bundle)[ RSS](/packages/sulu-headless-bundle/feed)WikiDiscussions 3.0 Synced 2w ago READMEChangelog (10)Dependencies (100)Versions (30)Used By (2) SuluHeadlessBundle ================== [](#suluheadlessbundle) [ ![Official Sulu Bundle Badge](https://camo.githubusercontent.com/8ac484ac60dbf97b4f747c6d0f704a16d2c005414d62dfcb2525b7c4cbf82466/68747470733a2f2f73756c752e696f2f75706c6f6164732f6d656469612f383030782f30302f3233302d4f6666696369616c25323042756e646c652532305365616c2e7376673f763d322d3626696e6c696e653d31) ](https://sulu.io/) [ ![GitHub license](https://camo.githubusercontent.com/da5d8cede2252ce868b309f949c85858256453fc57dd078fbeb53070b7e677ee/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f73756c752f53756c75486561646c65737342756e646c652e737667) ](LICENSE) [ ![Test workflow status](https://camo.githubusercontent.com/56149fe812a809e53b1218ad088b9bac71fd40480756c17b7d9d608d62dbabe3/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f73756c752f53756c75486561646c65737342756e646c652f746573742d6170706c69636174696f6e2e79616d6c) ](https://github.com/sulu/SuluHeadlessBundle/actions) [ ![Sulu compatibility](https://camo.githubusercontent.com/b6f672be62bb13e4f8b6dc15fcac42df23b639176f5f1a9e4cfd14c5c6619d3e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f73756c75253230636f6d7061746962696c6974792d2533453d332e302d3532623663612e737667) ](https://github.com/sulu/sulu/releases) The **SuluHeadlessBundle** provides controllers and services for using the [Sulu](https://sulu.io/) content management system in a headless way. To achieve this, the bundle includes a controller that allows to retrieve the content of a **Sulu page as plain JSON content**. Furthermore, the bundle provides APIs for accessing features that are available via Twig extensions in traditional templates such as navigation contexts and snippet areas. The SuluHeadlessBundle is compatible with Sulu **starting from version 2.0**. Have a look at the `require` section in the [composer.json](composer.json) to find an **up-to-date list of the requirements** of the bundle. Please be aware that this bundle is **still under development** and might not cover every use-case yet. Depending on the feedback of the community, future versions of the bundle might contain breaking changes. 🚀 Installation and Usage ------------------------ [](#-installation-and-usage) ### Install the bundle [](#install-the-bundle) Execute the following [composer](https://getcomposer.org/) command to add the bundle to the dependencies of your project: ``` composer require sulu/headless-bundle ``` ### Enable the bundle [](#enable-the-bundle) Enable the bundle by adding it to the list of registered bundles in the `config/bundles.php` file of your project: ``` return [ /* ... */ Sulu\Bundle\HeadlessBundle\SuluHeadlessBundle::class => ['all' => true], ]; ``` ### Include the routes of the bundle [](#include-the-routes-of-the-bundle) Include the routes of the bundle in a new `config/routes/sulu_headless_website.yaml` file in your project: ``` sulu_headless: type: portal resource: "@SuluHeadlessBundle/Resources/config/routing_website.yaml" ``` ### Set the controller of your template [](#set-the-controller-of-your-template) To provide an API for retrieving the content of a page in the JSON format, the controller of the page template must be set to the `HeadlessWebsiteController` included in this bundle: ``` Sulu\Bundle\HeadlessBundle\Controller\HeadlessWebsiteController::indexAction ``` This controller will provide the **content of the page as JSON object** if the page is requested in the JSON format via `{pageUrl}.json`. 💡 Key Concepts -------------- [](#-key-concepts) ### Deliver content of pages with the HeadlessWebsiteController [](#deliver-content-of-pages-with-the-headlesswebsitecontroller) The main use-case of the SuluHeadlessBundle is **delivering the content of a page as a JSON object**. This can be enabled individually per template by setting the controller of the template of the page to `Sulu\Bundle\HeadlessBundle\Controller\HeadlessWebsiteController::indexAction`. When using the `HeadlessWebsiteController`as controller for a template, the content of the page is available as JSON object via `{pageUrl}.json`. Additionally to the content of the page, the JSON object returned by the `HeadlessWebsiteController` contains **meta information** such as the page template and the data of the page excerpt: ``` { "id": "a5181a5a-b030-4933-b3b0-e9faf7ec756c", "type": "page", "template": "headless-template", "content": { "title": "Headless Example Page", "url": "/headless-example", "contacts": [ { "id": 416, "firstName": "Homer", "lastName": "Simpson", "fullName": "Homer Simpson", "title": "Dr. ", "position": "Nuclear safety Inspector at the Springfield Nuclear Power Plan" } ] }, "view": { "title": [], "url": [], "contacts": [] }, "extension": { "seo": { "title": "", "description": "", "keywords": "", "canonicalUrl": "", "noIndex": false, "noFollow": false, "hideInSitemap": false }, "excerpt": { "title": "", "more": "", "description": "", "categories": [], "tags": [], "icon": null, "image": null } }, "author": "2", "authored": "2019-12-03T11:01:38+0100", "changer": 2, "changed": "2020-01-30T07:47:46+0100", "creator": 2, "created": "2019-12-03T11:01:38+0100" } ``` If the content of a page that uses the `HeadlessWebsiteController` is requested without the `.json` suffix, the controller will render Twig template that is set as `view` of the template of the page. In this case, the data that would have been returned in case of a `.json` request is available in the twig template via a `headless` variable. #### Resolve content data to scalar values via ContentTypeResolver [](#resolve-content-data-to-scalar-values-via-contenttyperesolver) Internally, Sulu uses `ContentType` services that are responsible for persisting page content when a page is modified and resolving the data that is passed to the Twig template when a page is rendered. Unfortunately, some `ContentType`services pass non-scalar values such as media entities to the Twig template. As a JSON object must contain only scalar values, the SuluHeadlessBundle cannot use the existing `ContentType` services for resolving the content of a page. To solve this problem, the SuluHeadlessBundle introduces `ContentTypeResolver` services to resolve the content of pages to scalar values. The bundle already includes `ContentTypeResolver` services for various content types. If your project includes custom content types or if you are not satisfied with an existing `ContentTypeResolver`, you can register your own `ContentTypeResolver` by implementing the `ContentTypeResolverInterface` and adding a `sulu_headless.content_type_resolver` tag to the service. ### Provide popular Sulu functionality via JSON APIs [](#provide-popular-sulu-functionality-via-json-apis) The Sulu content management system comes with various services and Twig extensions to simplify the development and the rendering complex websites. This functionality is not available when serving the content of the website in a headless way, therefore the SuluHeadlessBundle includes controllers to **provide JSON APIs for accessing these features**. The APIs are registered as portal URLs and therefore their path is prefixed with the URL of the webspace. If you have configured a language-specific URL for your webspace, the API URL will look something like this: - `https://example.org/en/api/...` #### Navigation [](#navigation) `/api/navigations/{contextKey}` ParameterTypeDefault ValueDescriptiondepthinteger`1`Maximum depth of the navigation tree that is loaded.flatboolean`false`Return navigation as flat list instead of tree.excerptboolean`false`Include excerpt data in the returned navigation.Example: `/api/navigations/main?depth=2&flat=false&excerpt=true` #### Search [](#search) `/api/search?q={searchTerm}` ParameterTypeDefault ValueDescriptionqstringThe text you want to search for.Example: `/api/search?q=CMS` #### Snippet Areas [](#snippet-areas) `/api/snippet-areas/{area}` ParameterTypeDefault ValueDescriptionincludeExtensionboolean`false`Include extension data (e.g. excerpt) in the returned result.Example: `/api/snippet-areas/settings?includeExtension=true` #### Analytics [](#analytics) `/api/analytics.json` ❤️ Support and Contributions ---------------------------- [](#️-support-and-contributions) The Sulu content management system is a **community-driven open source project** backed by various partner companies. We are committed to a fully transparent development process and **highly appreciate any contributions**. In case you have questions, we are happy to welcome you in our official [Slack channel](https://sulu.io/services-and-support). If you found a bug or miss a specific feature, feel free to **file a new issue** with a respective title and description on the [sulu/SuluHeadlessBundle](https://github.com/sulu/SuluHeadlessBundle) repository. 📘 License --------- [](#-license) The Sulu content management system is released under the under terms of the [MIT License](LICENSE). ### Health Score 65 — FairBetter than 99% of packages Maintenance88 Actively maintained with recent releases Popularity48 Moderate usage in the ecosystem Community32 Small or concentrated contributor base Maturity79 Established project with proven stability Bus Factor2 2 contributors hold 50%+ of commits How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~77 days Recently: every ~9 days Total 29 Last Release 55d ago Major Versions 0.10.5 → 1.0.02026-01-28 1.0.0 → 3.0.0-RC12026-01-29 1.1.0 → 3.0.0-RC22026-03-12 1.1.1 → 3.0.12026-06-25 PHP version history (4 changes)0.1.0PHP ^7.2 0.4.0PHP ^7.3 0.4.1PHP ^7.3 || ^8.0 1.0.0PHP ^8.2 ### Community Maintainers ![](https://www.gravatar.com/avatar/5dbafb2ec00aab7a9f476cf2dd77f63923acfda214ec7bf728c662a9e88f39c7?d=identicon)[chirimoya](/maintainers/chirimoya) ![](https://www.gravatar.com/avatar/e43a10984e8ee1687abaac86c26311c6a607b9560e8a3cc3193f8245751618bc?d=identicon)[wachterjohannes](/maintainers/wachterjohannes) ![](https://avatars.githubusercontent.com/u/1698337?v=4)[Alexander Schranz](/maintainers/alexander-schranz)[@alexander-schranz](https://github.com/alexander-schranz) ![](https://avatars.githubusercontent.com/u/25978473?v=4)[Prokyonn](/maintainers/Prokyonn)[@Prokyonn](https://github.com/Prokyonn) --- Top Contributors [![niklasnatter](https://avatars.githubusercontent.com/u/13310795?v=4)](https://github.com/niklasnatter "niklasnatter (63 commits)")[![alexander-schranz](https://avatars.githubusercontent.com/u/1698337?v=4)](https://github.com/alexander-schranz "alexander-schranz (43 commits)")[![Prokyonn](https://avatars.githubusercontent.com/u/25978473?v=4)](https://github.com/Prokyonn "Prokyonn (31 commits)")[![wachterjohannes](https://avatars.githubusercontent.com/u/1464615?v=4)](https://github.com/wachterjohannes "wachterjohannes (23 commits)")[![martinlagler](https://avatars.githubusercontent.com/u/24388840?v=4)](https://github.com/martinlagler "martinlagler (15 commits)")[![luca-rath](https://avatars.githubusercontent.com/u/5758674?v=4)](https://github.com/luca-rath "luca-rath (10 commits)")[![TheCadien](https://avatars.githubusercontent.com/u/9395097?v=4)](https://github.com/TheCadien "TheCadien (8 commits)")[![reyostallenberg](https://avatars.githubusercontent.com/u/3579090?v=4)](https://github.com/reyostallenberg "reyostallenberg (4 commits)")[![thomasduenser](https://avatars.githubusercontent.com/u/3875917?v=4)](https://github.com/thomasduenser "thomasduenser (2 commits)")[![popoplanter](https://avatars.githubusercontent.com/u/30287946?v=4)](https://github.com/popoplanter "popoplanter (1 commits)")[![danrot](https://avatars.githubusercontent.com/u/405874?v=4)](https://github.com/danrot "danrot (1 commits)")[![Jupi007](https://avatars.githubusercontent.com/u/36476595?v=4)](https://github.com/Jupi007 "Jupi007 (1 commits)")[![chalasr](https://avatars.githubusercontent.com/u/7502063?v=4)](https://github.com/chalasr "chalasr (1 commits)")[![mamazu](https://avatars.githubusercontent.com/u/14860264?v=4)](https://github.com/mamazu "mamazu (1 commits)")[![ahoek](https://avatars.githubusercontent.com/u/1233165?v=4)](https://github.com/ahoek "ahoek (1 commits)")[![drakulis](https://avatars.githubusercontent.com/u/1709738?v=4)](https://github.com/drakulis "drakulis (1 commits)") --- Tags bundlehacktoberfestheadlessphpsulusulu-bundlesymfony ### Code Quality TestsPHPUnit Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/sulu-headless-bundle/health.svg) ``` [![Health](https://phpackages.com/badges/sulu-headless-bundle/health.svg)](https://phpackages.com/packages/sulu-headless-bundle) ``` ### Alternatives [easycorp/easyadmin-bundle Admin generator for Symfony applications 4.3k18.3M430](/packages/easycorp-easyadmin-bundle) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)