PHPackages                             roadiz/headless-edition - 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. roadiz/headless-edition

ActiveProject

roadiz/headless-edition
=======================

Roadiz – Headless edition

1.7.3(3y ago)7371[1 issues](https://github.com/roadiz/headless-edition/issues)MITPHPPHP >=7.4

Since Feb 25Pushed 3y ago2 watchersCompare

[ Source](https://github.com/roadiz/headless-edition)[ Packagist](https://packagist.org/packages/roadiz/headless-edition)[ RSS](/packages/roadiz-headless-edition/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (7)Versions (9)Used By (0)

Roadiz *Headless Edition* CMS
=============================

[](#roadiz-headless-edition-cms)

[![Join the chat at https://gitter.im/roadiz/roadiz](https://camo.githubusercontent.com/abe08b740a4156153736f791393ec4da6619c4be73212e75769f52edacc0e2b5/68747470733a2f2f6261646765732e6769747465722e696d2f4a6f696e253230436861742e737667)](https://gitter.im/roadiz/roadiz?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

Roadiz is a modern CMS based on a polymorphic node system which can handle many types of services and contents. Its back-office has been developed with a high sense of design and user experience. Its theming system is built to live independently of back-office allowing easy switching and multiple themes for one content basis. For example, it allows you to create one theme for your desktop website and another one for your mobile, using the same node hierarchy. Roadiz is released under MIT license, so you can reuse and distribute its code for personal and commercial projects.

- [Documentation](#documentation)
- [Headless edition](#headless-edition)
- [Usage](#usage)
    - [Develop with *Docker*](#develop-with-docker)
        - [Issue with Solr container](#issue-with-solr-container)
    - [Develop with *PHP* internal server](#develop-with-php-internal-server)
        - [On Linux](#on-linux)
- [Update Roadiz sources](#update-roadiz-sources)
- [Maximize performances for production](#maximize-performances-for-production)
    - [Optimize class autoloader](#optimize-class-autoloader)
    - [Increase PHP cache sizes](#increase-php-cache-sizes)
- [Build a docker image with Gitlab Registry](#build-a-docker-image-with-gitlab-registry)

Documentation
-------------

[](#documentation)

- *Roadiz* website:
- *Read the Docs* documentation can be found at
- *API* documentation can be found at
- *Forum* can be found at

Headless edition
----------------

[](#headless-edition)

This is the **API-ready edition** for Roadiz. It is meant to set up your *Apache/Nginx* server root to the `web/` folder, keeping your app sources secure, and all your business logic into `src/` folder AKA `\App` PHP namespace.

**Headless edition** does not need any *themes*, so you can build your API schema right into the backoffice and use REST API entry points without any code. A built-in *tree-walker* is configured automatically to walk your node-types children fields to create a JSON graph when requesting a single node (by *id* or by *slug*).

**Headless edition** is heavily based on `roadiz/abstract-api-theme` features, you will find additional information about registered routes and API entry points on its [readme](https://github.com/roadiz/AbstractApiTheme/blob/develop/README.md). *AbstractApiTheme* is already registered for you so you can begin creating your data structure right away. Any additional configuration is available in your `src/AppServiceProvider.php` container service-provider.

Automatic node-source controller resolution is disabled and any request on a node-source path will end up in `src/Controller/NullController.php`, so your application clients have to use your secure API end-points.

### Boilerplate for exposing content API for static-site generators

[](#boilerplate-for-exposing-content-api-for-static-site-generators)

Headless edition has been built to work with a *NuxtJS* application and minimizing API calls.

The most important call you'll make is the *Get single node-source by path* which combine searching a node-source by its path **and** fetching its content in **single** data context.

To retrieve homepage, you can execute `GET /api/1.0/nodes-sources/by-path?path=/`:

```
{
    "slug": "homepage",
    "@type": "Page",
    "node": {
        "nodeName": "homepage",
        "home": true,
        "visible": true,
        "tags": [],
        "attributeValues": []
    },
    "translation": {
        "locale": "en"
    },
    "urlAliases": [],
    "title": "Homepage",
    "metaTitle": "Homepage – Headless",
    "metaKeywords": "",
    "metaDescription": "Homepage – Headless",
    "url": "/",
    "@id": "http://headless.test/api/1.0/page/2/en",
    "head": {
        "siteName": "Headless",
        "homePageUrl": "/"
    }
}
```

This is way more efficient than executing :

- `/api/1.0/nodes-sources?path=/` which is a *hydra:Collection* response
- and then once you know `@id`, you can request a single node-source response: `/api/1.0/page/2/en`

---

You'll find some boilerplate models and controller for serving *common contents* for building menus and finding social links. For example: `/api/1.0/common` will expose `CommonContentResponse` model which can be customized to expose some useful data that could be painful to fetch through *NodesSources* API endpoints, such as hierarchical menu views, or *Roadiz* settings.

```
{
    "mainMenuWalker": {
        "children": [],
        "item": {
            "slug": "main-menu",
            "@type": "Neutral",
            "node": {
                "nodeName": "main-menu",
                "visible": false,
                "tags": []
            },
            "title": "Main menu",
            "@id": "http://headless.test/api/1.0/neutral/1/en"
        },
        "@type": "MenuNodeSourceWalker"
    },
    "head": {
        "siteName": "Headless",
        "homePageUrl": "/"
    }
}
```

Usage
-----

[](#usage)

### Use ready-to-go Docker image

[](#use-ready-to-go-docker-image)

If you do not need any custom code or to version your content schema, you can launch a Roadiz headless with our Docker standalone image and our `docker-compose.standalone.yml` example stack.

Override ./app/conf/config.yaml file if necessary (for Solr configuration or custom monolog handler)

```
docker-compose up -d --force-recreate
docker-compose exec -u www-data app bin/roadiz migration:migrate --allow-no-migration -n
docker-compose exec -u www-data app bin/roadiz install -n --env=install
docker-compose exec -u www-data app bin/roadiz generate:private-key
docker-compose up -d --force-recreate --no-deps app varnish
docker-compose exec -u www-data app bin/roadiz users:create -m johndoe@roadiz.io -b -s -p "supersecretpassword" johndoe
```

Then browse to `https://headless.test/rz-admin` and build your headless API.

Standalone code is configured to create a `CommonContentResponse` from a `main-menu` node. If you need to customize common content responses, we invite you to create a custom project.

### Create a new custom project

[](#create-a-new-custom-project)

For custom projects we recommend starting from a dedicated repository:

```
# Create a new Roadiz project on develop branch
composer create-project roadiz/headless-edition;
# Navigate into your project dir
cd headless-edition;
```

Composer will automatically create a new project based on Roadiz and download every dependency.

Composer script will copy a default configuration file and your entry-points in `web/` folder automatically and a `.env` file in your project root to set up your *Docker* development environment.

### Develop with *Docker*

[](#develop-with-docker)

*Docker* on Linux will provide awesome performances, and a production-like environment without bloating your development machine:

```
# Copy sample environment variables
# and adjust them against your needs.
nano .env;
# Build PHP image
docker-compose build;
# Create and start containers
docker-compose up -d;
# Initialize database and base content
docker-compose exec -u www-data app bin/roadiz migration:migrate --allow-no-migration -n
docker-compose exec -u www-data app bin/roadiz install -n --env=install
# Restart to empty caches
docker-compose up -d --force-recreate --no-deps app varnish
```

##### Issue with Solr container

[](#issue-with-solr-container)

*Solr* container declares its volume in `.data/solr` in your project folder. After first launch this folder may be created with `root` owner causing *Solr* not to be able to populate it. Just run:
`sudo chown -R $USER_UID:$USER_UID .data` (replacing `$USER_UID` with your local user *id*).

### Develop with *PHP* internal server

[](#develop-with-php-internal-server)

```
# Edit your Makefile "DEV_DOMAIN" variable to use a dedicated port
# to your project and your theme name.
nano Makefile;

# Launch PHP server
make dev-server;
```

#### On Linux

[](#on-linux)

Pay attention that *PHP* is running with *www-data* user. You must update your `.env` file to reflect your local user **UID** during image build.

```
# Type id command in your favorite terminal app
id
# It should output something like
# uid=1000(toto)
```

So use the same uid in your `.env` file **before** starting and building your docker image.

```
USER_UID=1000
```

Update Roadiz sources
---------------------

[](#update-roadiz-sources)

Simply call `composer update` to upgrade Roadiz packages. You’ll need to execute regular operations if you need to migrate your database.

Maximize performances for production
------------------------------------

[](#maximize-performances-for-production)

You can follow the already [well-documented article on *Performance* tuning for Symfony apps](http://symfony.com/doc/current/performance.html).

### Optimize class autoloader

[](#optimize-class-autoloader)

```
composer dump-autoload --optimize --no-dev --classmap-authoritative
```

### Increase PHP cache sizes

[](#increase-php-cache-sizes)

```
; php.ini
opcache.max_accelerated_files = 20000
realpath_cache_size=4096K
realpath_cache_ttl=600
```

Build a docker image with Gitlab Registry
-----------------------------------------

[](#build-a-docker-image-with-gitlab-registry)

You can create a standalone *Docker* image with your Roadiz project thanks to our `roadiz/php80-nginx-alpine` base image, a continuous integration tool such as *Gitlab CI* and a private *Docker* registry. All your theme assets will be compiled in a controlled environment, and your production website will have a minimal downtime at each update.

Make sure you don’t ignore `package.lock` or `yarn.lock` in your themes not to get dependency errors when your CI system will compile your theme assets. You may do the same for your project `composer.lock` to make sure you’ll use the same dependencies' version in dev as well as in your CI jobs.

*Headless Edition* provides a basic configuration set with a `Dockerfile`:

1. Customize `.gitlab-ci.yml` file to reflect your *Gitlab* instance configuration and your *theme* path and your project name.
2. Enable *Registry* and *Continuous integration* on your repository settings.
3. Push your code on your *Gitlab* instance. An image build should be triggered after a new **tag** has been pushed and your test and build jobs succeeded.

###  Health Score

27

—

LowBetter than 49% of packages

Maintenance17

Infrequent updates — may be unmaintained

Popularity14

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity57

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

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 ~107 days

Recently: every ~150 days

Total

7

Last Release

1254d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/380026?v=4)[Ambroise Maupate](/maintainers/ambroisemaupate)[@ambroisemaupate](https://github.com/ambroisemaupate)

---

Top Contributors

[![ambroisemaupate](https://avatars.githubusercontent.com/u/380026?v=4)](https://github.com/ambroisemaupate "ambroisemaupate (104 commits)")

###  Code Quality

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/roadiz-headless-edition/health.svg)

```
[![Health](https://phpackages.com/badges/roadiz-headless-edition/health.svg)](https://phpackages.com/packages/roadiz-headless-edition)
```

###  Alternatives

[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)[kimai/kimai

Kimai - Time Tracking

4.6k7.4k1](/packages/kimai-kimai)[contao/core-bundle

Contao Open Source CMS

1231.6M2.3k](/packages/contao-core-bundle)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

595.2M385](/packages/shopware-core)[ec-cube/ec-cube

EC-CUBE EC open platform.

78527.0k1](/packages/ec-cube-ec-cube)[typo3/cms-core

TYPO3 CMS Core

3512.3M3.8k](/packages/typo3-cms-core)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)