Skip to main content
Version: Next

Installation

info

Headless Documents is an enterprise bundle. It requires a Pimcore enterprise subscription.

Prerequisites​

The bundle requires Pimcore 2026.1 or later and PHP 8.4 or 8.5.

Datahub 2026.1.3 or later is a Composer dependency. Composer pulls it in automatically, but Headless Documents does not register it as a dependent bundle, so it must be enabled in config/bundles.php and installed on its own, see steps 2 and 3 below.

Installation Process​

  1. Install the package:
composer require pimcore/headless-documents
  1. Enable the bundle in config/bundles.php. Make sure PimcoreDataHubBundle is listed before PimcoreHeadlessDocumentsBundle:
use Pimcore\Bundle\DataHubBundle\PimcoreDataHubBundle;
use Pimcore\Bundle\HeadlessDocumentsBundle\PimcoreHeadlessDocumentsBundle;
// ...

return [
    // ...
    PimcoreDataHubBundle::class => ['all' => true],
    PimcoreHeadlessDocumentsBundle::class => ['all' => true],
    // ...
];
  1. Install Datahub, if it is not installed yet. Enabling it in config/bundles.php only loads it, it does not create the plugin_datahub_config permission and the Datahub permission category that Headless Documents depends on:
bin/console pimcore:bundle:install PimcoreDataHubBundle
  1. Install the bundle:
bin/console pimcore:bundle:install PimcoreHeadlessDocumentsBundle

Datahub is required, not optional. The bundle registers itself as a Datahub adapter type only when the pimcore_data_hub extension is present, but its service definitions always register a GraphQL document type that depends on Datahub services. Running without the Datahub bundle leaves those container dependencies unresolved.

User Permissions​

Access is checked on several levels, depending on what a user configures:

  • Creating or editing headless document templates and bricks in Pimcore Studio requires the pimcore_headless_documents_config permission ("Headless Documents Configuration"), or an admin user. It gates the Studio endpoints for both templates and bricks (tree, detail, create, update, delete, inline help) as well as the brick list. The template list endpoint is intentionally left ungated: the document configuration sidebar uses it to populate its template selector, so any Studio user can read the list of template names.
  • Opening the Datahub configuration panel at all requires the plugin_datahub_config permission, or an admin user. This permission comes from Datahub and is shared with every adapter, including Headless Documents.
  • The installer adds plugin_datahub_adapter_headlessDocuments ("Datahub Adapter - Headless Documents") to the Datahub permission category. For a given Datahub configuration, this permission is only consulted as a fallback: if the configuration's own Permissions tab has no user or role entries, access falls back to whether the user holds this permission. As soon as the Permissions tab has at least one entry, only those entries are checked and the adapter-level permission is ignored for that configuration. Users with admin rights or the plugin_datahub_admin permission always have access.

Access to an individual Datahub configuration (read, update, delete) is granted per user and role in its Permissions tab, see Configuration.

Upgrading​

See Upgrade Notes for version-specific changes when updating an existing installation.