Pimcore Universal Search

Full-text frontend search for Pimcore. The bundle indexes documents, assets and data objects into OpenSearch and exposes a JSON search API, Twig functions and a document editable.

Elements are indexed automatically when editors save, publish or delete them in Pimcore. Every element type is normalized into a single record format, so one query searches pages, PDFs and products together and returns ranked, highlighted hits.

#Requirements

#Installation

The package is served from the 2bdev-studio Composer repository. Access is anonymous, so no token or auth.json is needed.

1. Add the repository and require the package

composer config repositories.2bdev-studio composer https://2bdev-studio.repo.repman.io
composer require 2bdev-studio/pimcore-universal-search

2. Register the bundle

If Symfony Flex did not add it for you, register the bundle in config/bundles.php:

return [
    // ...
    PimcoreLabs\Bundle\UniversalSearchBundle\UniversalSearchBundle::class => ['all' => true],
];

3. Point it at OpenSearch

OPENSEARCH_URL=http://opensearch:9200

4. Install tables and assets

bin/console pimcore:bundle:install UniversalSearchBundle
bin/console assets:install
bin/console cache:clear

The installer creates the search_index_queue (retry queue) and search_index_lock (reindex mutex) tables and the search_index admin permission.

5. Declare searchable data objects

Documents and PDF/text assets are indexed out of the box. Data object classes are opt-in:

pimcore_universal_search:
    objects:
        Product:
            fields: [name, description, sku]
            url_pattern: '/product/{key}'

6. Build the index and query it

bin/console pimcore:search:index --sync
curl 'http://localhost/search?q=hello'

From now on, saving or deleting an element in Pimcore keeps the index up to date.

#Configuration

Everything lives under the pimcore_universal_search root key, usually in config/packages/pimcore_universal_search.yaml. YAML is the only configuration source in the free edition. A minimal setup:

pimcore_universal_search:
    enabled: true
    opensearch:
        host: '%env(OPENSEARCH_URL)%'
        index_prefix: pimcore_search
    indexing:
        async: true
    objects:
        Product:
            fields: [name, description, sku]
            url_pattern: '/product/{key}'

Global

opensearch

pimcore_universal_search:
    engine: meilisearch
    meilisearch:
        host: '%env(MEILISEARCH_URL)%'
        api_key: '%env(MEILISEARCH_API_KEY)%'

#search

Highlighted excerpts are cut from the indexed body around the match, so they differ from the static excerpt (truncated to 300 characters at index time). When highlighting is off or no fragment comes back, highlightedTitle and highlightedExcerpt are null and you should fall back to title and excerpt.

#indexing

Asset text comes from the plain-text extractor and, for PDFs, from pdftotext when the binary is installed. Other MIME types are indexed by filename and path only.

pimcore_universal_search:
    indexing:
        tika:
            enabled: true
            url: '%env(TIKA_URL)%'
            timeout: 60

#sites (main site)

The free edition indexes the main site only. Documents inside a Pimcore Site tree are skipped; assets and objects go into the main site index. Only the 0 key is read:

pimcore_universal_search:
    sites:
        0:
            index_name: my_search    # optional custom physical index name
            excluded_paths:
                - /internal
            document_types:
                - page

pimcore_universal_search:
    sites:
        0:
            excluded_paths: [/internal]
        2:
            enabled: true
            index_name: my_shop_search
            document_types: [page]

#objects (map keyed by class name)

Declares which Data Object classes are indexed and how their URLs are built.

pimcore_universal_search:
    objects:
        Product:
            enabled: true
            fields:
                - name
                - description
                - sku
            url_pattern: '/product/{id}'
            route_name: product_detail   # alternative to url_pattern

Objects without a resolvable URL are indexed as headless hits (headless: true): searchable, but with no link.

#How indexing works

1. A Pimcore save, publish or delete event reaches the bundle's document, asset or object listener.
2. The indexing service checks that the bundle is enabled and the element is eligible (published, public, not in an excluded path, allowed type or MIME type).
3. An indexer turns the element into an IndexRecord.
4. The dispatcher sends it through Messenger (async: true) or executes it immediately.
5. The executor writes to OpenSearch. If OpenSearch is down, the operation goes to the retry queue.

What gets indexed per type

Every record carries id, siteId, locale, type, elementId, title, excerpt, body, url, headless, lastModified and customFields. Search uses a multi_match query with boosts title^3, excerpt^2, body and fuzziness: AUTO, so small typos still match.

#Async indexing and retry queue

Index messages are routed to the pimcore_universal_search Messenger transport, which defaults to doctrine://default?queue_name=pimcore_universal_search. Run a worker for it:

bin/console messenger:consume pimcore_universal_search

Use another broker by overriding the transport:

framework:
    messenger:
        transports:
            pimcore_universal_search: 'amqp://rabbitmq:5672/%2f/pimcore_universal_search'

For synchronous indexing (tests, small sites) set indexing.async: false, or pass --sync to pimcore:search:index.

Retry queue

When OpenSearch rejects or cannot receive an operation, it is stored in search_index_queue with an attempt counter, the next retry time (queue_retry_delay_seconds, 300 by default) and the last error. After max_queue_attempts (10) the item is dropped. Queued items are retried by:

• the pimcore:search:process-queue command;
• the Pimcore maintenance task search_index_queue, so a running pimcore:maintenance cron is enough.

Concurrent full reindexes are prevented by a lock row in search_index_lock.

#Index identity

Each record has a stable ID, so re-saving an element overwrites its entry instead of duplicating it:

{type}_{elementId}_{siteId}_{locale}

document_42_0_en
object_118_0_de
asset_7_0_en

The free edition always uses site ID 0, so the physical index is pimcore_search_0 by default.

#Public search API

GET /search (path set by search.public_route) returns JSON.

curl 'https://example.com/search?q=wireless+headphones&locale=en&types=object,document&per_page=5'

{
  "hits": [
    {
      "id": "document_42_0_en",
      "type": "document",
      "title": "About us",
      "excerpt": "We design products that last...",
      "url": "/about",
      "headless": false,
      "score": 1.4,
      "customFields": {},
      "highlightedTitle": null,
      "highlightedExcerpt": "...our <mark>products</mark> are built to last..."
    }
  ],
  "totalCount": 1,
  "processingTimeMs": 3.2,
  "facets": [],
  "page": 1,
  "perPage": 10
}

Sending Accept: text/html returns the same result set rendered with the results template instead of JSON. The bundled results script uses this to update the page without a reload.

"facets": {
  "type": {"document": 14, "object": 12, "asset": 3},
  "class_name": {"Product": 12}
}

#Twig functions

{% set result = pimcore_search(app.request.query.get('q')) %}

<p>{{ result.totalCount }} results</p>
{% for hit in result.hits %}
    <a href="{{ hit.url }}">
        {% if hit.highlightedTitle %}{{ hit.highlightedTitle|raw }}{% else %}{{ hit.title }}{% endif %}
    </a>
{% endfor %}

<a href="{{ pimcore_search_url({page: 2}) }}">Next</a>

highlightedTitle and highlightedExcerpt are already escaped by the bundle, with only the highlight tags left as HTML, so they are safe to print with |raw.

#Results page

The quickest way to a full results page with pagination, sorting and highlighting:

{{ pimcore_search_render(app.request.query.get('q')) }}
<script src="{{ asset('bundles/universalsearch/js/search-results.js') }}" defer></script>

Without JavaScript everything works: pagination links are plain links and the sort control submits a form. With search-results.js loaded, those interactions are fetched and swapped in place, then pushed to the browser history.

Overriding templates

results.html.twig is composed of _hit.html.twig and _pagination.html.twig. Override a single result card by providing your own _hit.html.twig through Twig template path priority, or replace the whole page:

{{ pimcore_search_render(terms, {'template': '@App/search/my-results.html.twig'}) }}

#Document editable

Editors can drop a search results area into any document. Add the search_results editable to a document template; it reads the q query parameter and renders hits server side. It accepts the same template option as pimcore_search_render().

{{ pimcore_editable('results', 'search_results') }}

{{ pimcore_search_widget_assets() }}

<search-widget results-page-url="/search-results" theme="auto"></search-widget>

search-widget {
  --sw-bg: #ffffff;
  --sw-text: #131B24;
  --sw-muted: #4D5765;
  --sw-border: #E1E4E8;
  --sw-hover: #F1F3F6;
  --sw-accent: #0677F7;
  --sw-error: #993c1d;
}

document.querySelector('search-widget').addEventListener('search:select', (event) => {
  analytics.track('search_select', { id: event.detail.hit.id });
});

window.PimcoreSearch.open();
window.PimcoreSearch.search('wireless headphones');
window.PimcoreSearch.close();

#CLI commands

# reindex only data objects, without Messenger
bin/console pimcore:search:index --type=object --sync

# start from scratch
bin/console pimcore:search:clear --force
bin/console pimcore:search:index --sync

#Testing setup

Use a dedicated index prefix and synchronous indexing in the test environment, so tests never touch the real index and see results immediately:

pimcore_universal_search:
    opensearch:
        index_prefix: pimcore_search_test
    indexing:
        async: false

#Extension points

Every part of the pipeline can be replaced or extended with plain Symfony services. All classes live under PimcoreLabs\Bundle\UniversalSearchBundle.

#Custom object indexer

Several object indexers can coexist. The first one whose supports() returns true, by priority, builds the record. No service definition is needed if the class is in an autowired namespace.

namespace App\Search;

use PimcoreLabs\Bundle\UniversalSearchBundle\Contract\ObjectIndexerInterface;
use PimcoreLabs\Bundle\UniversalSearchBundle\Indexer\IndexRecord;
use Pimcore\Model\DataObject\AbstractObject;
use Pimcore\Model\DataObject\Product;
use Pimcore\Model\Site;
use Symfony\Component\DependencyInjection\Attribute\AutoconfigureTag;

#[AutoconfigureTag('pimcore.search_index.object_indexer', ['priority' => 64])]
final class ProductIndexer implements ObjectIndexerInterface
{
    public function supports(AbstractObject $object): bool
    {
        return $object instanceof Product;
    }

    public function buildIndexRecord(
        AbstractObject $object,
        int $siteId,
        ?Site $site = null,
        string $locale = 'en',
    ): IndexRecord {
        /** @var Product $object */
        $object->setLocale($locale);

        return IndexRecord::create(
            IndexRecord::TYPE_OBJECT,
            $object->getId(),
            $siteId,
            $locale,
            (string) $object->getName(),
            implode("\n", array_filter([
                (string) $object->getDescription(),
                (string) $object->getSku(),
            ])),
            url: '/shop/' . $object->getKey(),
            customFields: ['class_name' => 'Product'],
        );
    }
}

#Document and asset indexers

Documents and assets use a single indexer service each. Implement the interface and alias it, or decorate the bundled DocumentIndexer to reuse editable extraction and change only what you need.

namespace App\Search;

use PimcoreLabs\Bundle\UniversalSearchBundle\Contract\DocumentIndexerInterface;
use PimcoreLabs\Bundle\UniversalSearchBundle\Indexer\IndexRecord;
use Pimcore\Model\Document;
use Pimcore\Model\Site;

final class EventDocumentIndexer implements DocumentIndexerInterface
{
    public function supports(Document $document): bool
    {
        return $document->getType() === 'page'
            && $document->getProperty('event_date') !== null;
    }

    public function buildIndexRecord(Document $document, int $siteId, ?Site $site = null): IndexRecord
    {
        return IndexRecord::create(
            IndexRecord::TYPE_DOCUMENT,
            $document->getId(),
            $siteId,
            'en',
            $document->getTitle(),
            $document->getDescription() . "\n" . $document->getProperty('event_date'),
            $document->getFullPath(),
            customFields: ['document_type' => 'event'],
        );
    }
}

services:
    App\Search\EventDocumentIndexer: ~

    PimcoreLabs\Bundle\UniversalSearchBundle\Contract\DocumentIndexerInterface:
        alias: App\Search\EventDocumentIndexer

Assets follow the same pattern with AssetIndexerInterface (supports(Asset $asset) and buildIndexRecord(Asset $asset, int $siteId, ?Site $site = null)).

#Custom text extractor

Add text extraction for formats the built-in chain (plain text, then pdftotext) does not cover. Extractors are tried by priority; the first that supports the asset and returns non-empty text wins. Throw TextExtractionException to log a warning and fall through to the next one. Remember to add the MIME type to indexing.asset_mime_types.

namespace App\Search;

use PimcoreLabs\Bundle\UniversalSearchBundle\Contract\DocumentTextExtractorInterface;
use Pimcore\Model\Asset;
use Symfony\Component\DependencyInjection\Attribute\AutoconfigureTag;

#[AutoconfigureTag('pimcore.search_index.text_extractor', ['priority' => 512])]
final class MarkdownTextExtractor implements DocumentTextExtractorInterface
{
    public function supports(Asset $asset): bool
    {
        return $asset->getMimeType() === 'text/markdown';
    }

    public function extractText(Asset $asset): string
    {
        return strip_tags((string) $asset->getData());
    }
}

#Result decorators

Decorators change hits after OpenSearch returns them and before JSON or Twig output: add a badge, a thumbnail, a breadcrumb. All tagged decorators run in sequence.

namespace App\Search;

use PimcoreLabs\Bundle\UniversalSearchBundle\Contract\SearchResultDecoratorInterface;
use PimcoreLabs\Bundle\UniversalSearchBundle\Search\SearchHit;
use Symfony\Component\DependencyInjection\Attribute\AutoconfigureTag;

#[AutoconfigureTag('pimcore.search_index.result_decorator')]
final class BadgeDecorator implements SearchResultDecoratorInterface
{
    public function decorate(SearchHit $hit): SearchHit
    {
        $fields = $hit->customFields;
        $fields['badge'] = $hit->type === 'object' ? 'Product' : ucfirst($hit->type);

        return new SearchHit(
            $hit->id,
            $hit->type,
            $hit->title,
            $hit->excerpt,
            $hit->url,
            $hit->headless,
            $hit->score,
            $fields,
            $hit->highlightedTitle,
            $hit->highlightedExcerpt,
        );
    }
}

#Custom search engine

Implement SearchEngineInterface to use a backend other than OpenSearch:

• index(IndexRecord $record): void
• delete(string $id): void
• search(SearchQuery $query): SearchResult
• clear(string $siteId): void
• getIndexStats(int $siteId): array

services:
    App\Search\AlgoliaEngine: ~

    PimcoreLabs\Bundle\UniversalSearchBundle\Contract\SearchEngineInterface:
        alias: App\Search\AlgoliaEngine

    pimcore.search_index.engine:
        alias: App\Search\AlgoliaEngine

Reuse IndexMapping for field names and IndexNameResolver for index naming. If your engine supports highlighting, ask the backend to delimit matches with HighlightSanitizer::ENGINE_PRE_TAG and ::ENGINE_POST_TAG (never with the configured output tags) and pass every raw fragment through HighlightSanitizer::sanitize($fragment, $preTag, $postTag) before putting it on a SearchHit. That is what keeps highlighted fields safe to render.

#Programmatic search and indexing

Inject SearchService in your own controllers or services:

use PimcoreLabs\Bundle\UniversalSearchBundle\Search\SearchQuery;
use PimcoreLabs\Bundle\UniversalSearchBundle\Service\SearchService;

public function __construct(private readonly SearchService $searchService) {}

$result = $this->searchService->search(new SearchQuery(
    terms: 'widget',
    siteId: 0,
    locale: 'en',
    types: ['document', 'object'],
    page: 1,
    perPage: 20,
));

Index elements outside the event listeners, optionally limited to some locales and forced to run synchronously with IndexingRunContext:

use PimcoreLabs\Bundle\UniversalSearchBundle\Indexer\IndexingRunContext;

$context = new IndexingRunContext(
    locales: ['en', 'de'],
    forceSync: true,
);

$this->documentIndexingService->indexDocument($document, $context);

#Frontend events

After each fetch and swap, search-results.js dispatches a bubbling search-results:update event with detail: { url }. Listen on document: the results container is replaced on every navigation, so a listener bound to it would be lost.

document.addEventListener('search-results:update', (event) => {
  console.log('Swapped in', event.detail.url);
});

#Troubleshooting

Saved elements do not show up in results

• With async: true a Messenger worker must consume pimcore_universal_search. Check with bin/console messenger:stats.
• Unpublished elements are skipped while published_only is on.
• Documents inside a Pimcore Site tree are not indexed in the free edition.
• Data object classes must be listed under objects, with at least one field.

OpenSearch was down for a while

Operations that failed are in the retry queue. Run bin/console pimcore:search:process-queue or wait for the maintenance task. pimcore:search:status shows how many items are waiting.

PDFs are indexed without content

Install poppler-utils so pdftotext is on the PATH of the PHP process, then reindex with pimcore:search:index --type=asset --sync. Files bigger than max_asset_size_mb are indexed by name only.

Search returns 503

enabled is false for the current environment.