Installation

info

Datahub Simple REST 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. It also needs a search engine: OpenSearch 2.7 up to 2.x, or Elasticsearch 8.12.2 or later. The bundled clients do not support OpenSearch 3 or Elasticsearch 9.

Datahub, the OpenSearch client bundle and the Elasticsearch client bundle are Composer dependencies. Composer pulls them in automatically, and the bundle registers them as dependent bundles, so they are loaded without manual bundle ordering.

Loading Datahub this way does not install it. Datahub's own installer creates the plugin_datahub_config permission and the Datahub permission category that Simple REST depends on, so Datahub must be installed on its own, see step 3 below.

Installation Process

1. Install the package:

composer require pimcore/data-hub-simple-rest

2. Enable the bundle in config/bundles.php:

use Pimcore\Bundle\DataHubSimpleRestBundle\PimcoreDataHubSimpleRestBundle;
// ...

return [
    // ...
    PimcoreDataHubSimpleRestBundle::class => ['all' => true],
    // ...
];

3. Install Datahub, if it is not installed yet. Enabling it as a dependent bundle only loads it, it does not create the plugin_datahub_config permission and the Datahub permission category that Simple REST depends on:

bin/console pimcore:bundle:install PimcoreDataHubBundle

4. Install the bundle:

bin/console pimcore:bundle:install PimcoreDataHubSimpleRestBundle

5. Configure the search client. See OpenSearch Client Setup or Elasticsearch Client Setup. Configure exactly one of the two.

6. Create the index mapping and initialise the indices:

bin/console datahub:simple-rest:create-or-update-mapping
bin/console datahub:simple-rest:init-index

The search client must be configured before running step 6, otherwise the commands cannot reach the search engine.

Bundle Configuration

Search Client and Index Settings

Search client setup is covered in step 5 above, see OpenSearch Client Setup or Elasticsearch Client Setup. For analyzers, tokenizers, and other index-level settings, see Index Configuration.

Further Configuration Options

Configure index name prefix with symfony configuration:

pimcore_data_hub_simple_rest:

    # Prefix for index names
    index_name_prefix:    datahub_restindex_

    # Limit of page size and offset when paging only works via page cursor (and not page numbers anymore).
    max_results_window:   10000
        
    # Options to configure indexing behaviour
    indexing_options:
        assets:

            # Enable indexing for exif data
            enable_exif:          true

            # Enable indexing for xmp data
            enable_xmp:           true

            # Enable indexing for iptc data
            enable_iptc:          true
        global_options:

            # Enable numeric detection for dynamic objects (like embedded asset metadata, etc.)
            numeric_detection:    false

            # Enable date detection for dynamic objects (like embedded asset metadata, etc.)
            date_detection:       true
            
        # Configure number of shards for created indices
        number_of_shards_config:

            # default number is picked if no index specific settings is set
            default_number:       1

            # Define number of shards for certain indices. Define index name (without -odd/-even postfix) as key, and number of shards as value.
            index_specific:       []                
            
    # Configure index queue processing via symfony messenger
    messenger_queue_processing:

        # Activate queue processing via symfony messenger.
        activated:            false

        # Lifetime of tmp store entry for current worker count entry. After lifetime, the value will be cleared. Default to 1 hour.
        worker_count_lifetime: 3600

        # Count of items processed per worker message.
        worker_item_count:    400

        # Count of maximum parallel worker messages for queue processing.
        worker_count:         3                

info

Supported search engines: OpenSearch 2.7 up to 2.x, Elasticsearch 8.12.2 up to 8.x.

Swagger UI OAuth Client

The bundled Swagger UI page can offer an Authorize button that signs a user in through the Studio Backend bundle's embedded OAuth 2.1 authorization server, instead of the user pasting an API key in by hand. Showing it takes a setting here (swagger_oauth_client_id) plus a matching pre-registered client in the Studio Backend bundle's own configuration; left unset, which is the default, the button is simply not shown. See Swagger UI OAuth Authorization for the full setup.

Index Processing

To make sure indexing queue is processed and index is filled, there are two possible ways:

Command Based

For command-based queue processing, the following command has to be executed on a regular basis, e.g. every 5 minutes.

*/5 * * * * php /home/project/www/bin/console datahub:simple-rest:process-queue 

Symfony Messenger Based

For Symfony messenger-based queue processing, at least the following configuration is needed in the Symfony configuration:

pimcore_data_hub_simple_rest:
    messenger_queue_processing:
        activated: true

If activated, the processing is kicked off automatically with the datahub_simplerest_update_queue_dispatching maintenance task or when a Datahub configuration is saved.

In addition to that, the following settings are available. They all have meaningful default values though:

• worker_count: Count of maximum parallel worker messages for queue processing
• worker_item_count: Count of items processed per worker message.
• worker_count_lifetime: Lifetime of the tmp store entry holding the current worker count. After the lifetime expires, the value is cleared.

Messages are dispatched via the pimcore_index_queues transport. When activating messenger-based queue processing, make sure workers are processing this transport.

User Permissions

Two permissions apply, both listed under the Datahub category in user and role settings.

plugin_datahub_config comes from Datahub and is shared by every adapter. Every Studio endpoint of this bundle enforces it with #[IsGranted('plugin_datahub_config')], so without it the configuration panel returns 403 rather than merely hiding controls.

plugin_datahub_adapter_simpleRest ("Datahub Adapter - Simple REST") is created by this bundle's installer. It governs access to Simple REST configurations, and Datahub evaluates it like this:

1. Administrators and holders of plugin_datahub_admin are always allowed.
2. If the configuration defines no entries in its Permissions tab, plugin_datahub_adapter_simpleRest decides read, update and delete access.
3. As soon as the configuration defines at least one user or role entry, only those entries are evaluated and plugin_datahub_adapter_simpleRest is ignored. A user who is not covered by an entry, directly or through a role, is denied.