Layouts Ibexa Tags Query Laravel Package

Getting Started

Prerequisites. You need a working Ibexa Platform install (4.x/5.x) with netgen/layouts-ibexa already configured, and content types that actually use the Ibexa Tags field type. Without content carrying tags, the query has nothing to match against.

Install and register.

composer require netgen/layouts-ibexa-tags-query

Then enable the bundle in config/bundles.php:

Netgen\Layouts\Ibexa\TagsQuery\NetgenLayoutsIbexaTagsQueryBundle::class => ['all' => true],

Clear the cache (bin/console cache:clear) and confirm the bundle shows up in bin/console debug:container output. Because the package has essentially no dependents and zero stars, treat the README and the src/ directory as your primary documentation — read the query type registration and the query handler before trusting any assumptions.

Where to look first.

1. src/Query/ (or similarly named folder) — the query value object and its handler; this is where the actual Ibexa search happens.
2. The query type class — this defines what parameters are exposed in the Layouts admin UI (tags, content types, limit, offset, etc.).
3. Resources/config/services.yaml (or config/) — the service wiring and tags that register the query with Netgen Layouts.
4. Any form type / view under Resources/ — this is what renders the tag picker in the block editing screen.

First use case. Create a content item with a Tags field populated with a couple of values. In Netgen Layouts, create a block, set its item query to the Tags query provided by this bundle, and pick one of those tags in the query parameters. Publish the layout, place the block in a zone, and verify the matching content appears. Once that round-trip works, you understand the whole package.

Implementation Patterns

Admin-driven configuration. The dominant workflow is: authors pick tags in the block's query form. This means the query parameters must be expressive enough for editorial use — check that the form exposes content type restriction, sorting, and a limit, not just a raw tag list.

YAML layout definition. Netgen Layouts lets you define layouts in YAML and import them. Wire the Tags query in there when blocks are provisioned per environment:

# illustrative - verify parameter names against the query type
blocks:
    featured:
        type: list
        query:
            type: tags
            tags: [promo, homepage]
            limit: 6

Parameter names and the exact query type identifier are defined by the query type class; confirm them there rather than guessing.

Composing with content-type filtering. The useful pattern is combining tags with a content type constraint: "show the 5 most recent articles tagged featured". If the bundled query type doesn't expose content types, decorate the handler or subclass the query type to add it.

Programmatic access. For controller-level or Twig-level reuse, resolve the query handler from the container and execute the query object directly. This is useful for previewing what a block will render, or for writing integration tests that assert the search returns the right content IDs.

Testing. In functional tests, create content with tags via the Ibexa content service, run ibexa:reindex (or ensure the test search engine indexes immediately), then assert the query handler returns the expected items. This is the fastest way to catch the indexing pitfalls below.

Extension points. The clean seams are: a new query type (if you need a distinct parameter schema), a decorated query handler (to add filters, permissions, or custom search criteria), and a custom item view for the block so you control rendering of the matched content.

Gotchas and Tips

Indexing. This is the number one trap. The query hits Ibexa's search index, not the database. Content created or edited before tags were added — or before the bundle was installed and indexed — won't appear. Run bin/console ibexa:reindex after content changes in staging and after adding tags in dev.

Search engine differences. Legacy Search Engine and Solr behave differently for tag fields. Solr requires the field to be indexed with a suitable schema; if your Solr config doesn't index the tag field you may get zero results while the legacy engine works. Verify with bin/console ibexa:search:... tooling or by querying the index directly.

Multiple tag fields. A content type can have more than one Tags field. If the query only inspects a single hardcoded field identifier, tags stored in a different field will silently never match. Check the handler for a hardcoded identifier and, if present, extend it to accept the field as a parameter.

Match semantics. Confirm whether multiple selected tags mean AND or OR. Editorial expectations are usually OR ("any of these tags") but implementations frequently default to AND, producing empty blocks that look like a bug.

Permissions and languages. The query runs with the current user's permissions (or a configured one) — anonymous front-end visitors may see fewer results than an admin preview. On multilingual sites, tags may be translatable; ensure the handler filters by the correct language or you'll get duplicates and misses.

Cache invalidation. Netgen Layouts caches block query results. A new tagged item won't appear until the block cache expires or is invalidated. Configure reasonable TTLs and make sure your content publish workflow triggers Layouts cache invalidation, or authors will report "the block is broken".

Version constraints. With zero dependents, the package is unlikely to be actively tracked against netgen/layouts-ibexa and Ibexa core releases. Pin versions in composer.json and re-run your integration test after every Layouts/Ibexa upgrade. Treat it as lightly maintained code you own.

Debugging. When a block is empty: (1) confirm content is indexed, (2) confirm the tag value strings match exactly (case, whitespace), (3) disable the block cache temporarily, (4) inspect the generated search criteria in the handler. If the query type doesn't appear in the admin dropdown, the DI tag registration is missing or the bundle isn't enabled — check debug:container for the query type service.

Licensing. GPL-2.0. That's fine for GPL-compatible projects but a real consideration if you ship proprietary code that links against it.