Customization

Output Formatters

An output formatter decides how a field value is written into the search index. Formatters are a tagged service extension point, so you can add a formatter for a field type the bundle does not cover, or replace a shipped one.

info

Formatters run at indexing time, not at request time. DataObjectMappingAndDataExtractor applies them while extracting an element's data, before the document is written to the index; the REST endpoints then return the stored value unchanged. Adding or changing a formatter therefore has no effect on responses until the affected elements are reindexed. Queue them again and process the queue, see Indexing Details.

Implement OutputFormatterInterface and tag the service with pimcore.datahub_simplerest.output_formatter:

namespace App\DataHub;

use Pimcore\Bundle\DataHubSimpleRestBundle\MappingAndDataExtractor\OutputFormatter\OutputFormatterInterface;

final class MyImageFormatter implements OutputFormatterInterface
{
    public function getType(): string
    {
        // the field type this formatter handles, for example 'image'
        return 'image';
    }

    public function format(string $value, string $configName, array $config): mixed
    {
        // return whatever the endpoint should deliver for this field
    }
}

App\DataHub\MyImageFormatter:
    tags: [ 'pimcore.datahub_simplerest.output_formatter' ]

A compiler pass validates at container build time that every tagged service implements OutputFormatterInterface.

The bundle ships formatters for image, hotspotimage, imageGallery and video.

warning

Formatters are collected into a map keyed by getType(). The bundle makes no guarantee about which formatter wins when two of them return the same type: the last one in the tagged iterator overwrites the earlier ones, silently and without an error. Take care when overriding a shipped type.

Studio API Events

The configuration panel is a Pimcore Studio plugin. Before one of its endpoints returns, the bundle dispatches a pre-response event carrying the response schema. Listen for it to add your own attributes to the response.

Event	Dispatched	Payload
pre_response.data_hub_simple_rest.configuration_detail	Once, when a single configuration is read.	ConfigurationDetail: name, configuration data (including the generated Swagger, tree-items, search and get-element URLs), the update and delete permissions of the current user, and the modification date.
pre_response.data_hub_simple_rest.configuration_update	Once, after a configuration was saved.	UpdateConfigurationResponse: the new modification date.
pre_response.data_hub_simple_rest.label_list	Once per label.	Label: the label key as it appears in the search index.
pre_response.data_hub_simple_rest.thumbnail	Once per image thumbnail configuration.	Thumbnail: the thumbnail configuration name.
pre_response.data_hub_simple_rest.queue_item_count	Once, when the queue size is polled.	QueueItemCount: the number of items currently in the index queue.

See the Studio Backend Additional and Custom Attributes documentation for the listener pattern.

warning

The endpoints themselves are not a supported public API. The controllers are marked @internal and may change in any release without a deprecation path. Do not build integrations against them.

Upstream Events That Drive Reindexing

The bundle dispatches no events other than the five above. It does subscribe to events dispatched elsewhere, and those are what feed the index queue. To react to the same changes, register your own listener on the upstream event, independently of this bundle.

• Pimcore core, DataObjectEvents::POST_UPDATE, AssetEvents::POST_UPDATE and AssetEvents::POST_ADD: add the saved element to the index queue, then queue every document already indexed at or below the element's current full path. The lookup matches the path the document carried when it was last indexed, using a path-hierarchy analyzer, so it covers the element's descendants. Saves carrying the isAutoSave or saveVersionOnly argument return early, so auto-saves and version-only saves never touch the index.
• Pimcore core, DataObjectEvents::POST_DELETE and AssetEvents::POST_DELETE: queue every document indexed at or below the deleted element's full path. Nothing is removed from the index at this point; the entries disappear once the queue is processed and the elements can no longer be loaded.

note

The update subscriber passes the element's path after the save, not the path it had before. Renaming or moving an element therefore queues the element itself, but not the documents still indexed under its old path. Reindex the moved subtree explicitly if stale entries remain.

• Datahub, ConfigurationEvents::CONFIGURATION_POST_DELETE: drop the indices belonging to a deleted simpleRest (or ciHub) Datahub configuration.

Both subscribers, ChangedEventSubscriber and ConfigurationEventSubscriber, are marked @internal. The upstream events they listen to are stable Pimcore and Datahub extension points.

Queuing an element does not index it. Queued items reach the search index only when the queue is processed, either via datahub:simple-rest:process-queue or, if enabled, via Symfony Messenger. See Indexing Details. The Messenger messages involved (QueueMessage, QueueDuplicateCleanupMessage) are internal transport messages, not extension points.