Layouts Ezplatform Relation List Query Laravel Package

Getting Started

1. Install and check the constraint graph first. composer require netgen/layouts-ezplatform-relation-list-query. Read the require block before you commit: it pulls in netgen/layouts-* and the eZ Platform integration (netgen/layouts-ezplatform at the time of writing), both of which are pre-1.0 and churn between minor versions. Pin exact versions of Layouts, the eZ integration, and this package together.
2. Register the bundle. It ships a single *Bundle.php class under src/. Open it, take the FQCN, and add it to config/bundles.php (Symfony 4/5) or app/AppKernel.php (older). There is no config tree to publish.
3. Confirm the query type is registered. Query types are collected via the netgen_layouts.query_type container tag. Run bin/console debug:container --tag=netgen_layouts.query_type and look for the service that maps to the new type. If it is not there, the bundle is not loaded or autoconfiguration is off.
4. Where to look first. The package surface is three files: the QueryTypeInterface implementation (identifier, display name, config form), the form type it returns, and the query builder that talks to ContentService/LocationService. Everything else is stock Netgen Layouts plumbing. Read those three before touching templates.
5. First use case: a "Related articles" block. In the Layouts admin, add a block with a collection, switch the collection to Query mode, pick the relation-list query type, choose the source content and its ezobjectrelationlist field. The block then renders whatever that field points at, instead of hand-picked items.

Implementation Patterns

• Treat the package as a data source, not a renderer. Items flow Query config -> QueryBuilder -> ItemList -> Item value converter and are rendered by the standard Layouts/Ibexa block templates. If output looks wrong, the fix is almost always a template override or item view, not this bundle.
• Editorial "related content" blocks. The intended pattern: editors maintain a relation list on the article/news content (often with an object-relation-list field), and the Layouts block reads it. This keeps editorial control in the CMS and layout control in Layouts.
• One block type per placement. Collections are either manual or query-backed; you cannot mix the two in one collection. If a page needs "editor-picked plus auto-related", use two blocks rather than hacking the query.
• Dynamic source content. The common request is "show the related items of the content being viewed". Check whether the config form exposes a variable/placeholder for the content reference; if it only takes a fixed content ID, wire it up with a layout resolver that maps the current content, or decorate the query type to accept a runtime value. Do not hardcode per-article blocks.
• Compose with Layouts features. Since the result is a normal ItemList, you get pagination, offset, and the Layouts item view system for free — configure limits on the collection, not in the query type.
• Extend by decoration, not forking. To exclude the current content, enforce visible/published, filter by content type, or add a sort, decorate the query builder service in your app's services.yaml (decorates: the bundle's service ID) and post-process the resolved IDs. This survives package upgrades better than editing vendor code.

Gotchas and Tips

• Silent non-registration is the #1 failure. Query type missing from the admin dropdown = bundle not in bundles.php, or the QueryTypeInterface service not tagged. Verify with debug:container before debugging anything else.
• Relation list stores content IDs, not locations. Rendering usually needs a location for URL and name; the eZ integration resolves the main location. Content with multiple locations will render against mainLocationId — check that the main location is the one editors expect.
• Broken or invisible targets. A relation list can point at trashed, unpublished, or permission-restricted content. Depending on how the query builder loads things, you get a NotFoundException, a short result, or a hole in the output. Decide explicitly (skip silently vs. surface an error) and test as the anonymous front-end user, not as admin.
• Permissions change results. Repository calls respect the current user. Editor preview and anonymous front-end can legitimately show different item counts; this is not a bug — but it does mean cache warm-up runs under the wrong user can poison a block.
• Translations. Relation lists are language-agnostic IDs; content is then loaded in the current language with fallback. Missing translations mean names/URLs silently fall back — verify with a multi-language content item.
• Caching. Layouts caches rendered blocks. Adding/removing a relation on the source content must invalidate the block. Check whether the query builder contributes cache tags for the related content; if not, wire cache clearing into the editorial workflow (nglayouts:cache:clear or the admin Clear cache action) or accept stale related lists.
• GPL-2.0. This is copyleft. Fine for GPL-compatible projects; get legal sign-off before embedding it in a proprietary application, since it is linked into your app.
• Adoption risk is real. Six stars, zero dependents, and a pre-1.0 dependency chain: read the source (it is small), pin the version, and do not expect upstream fixes. If you need it on Ibexa 4+, verify the eZ\Publish\* vs Ibexa\* namespace compatibility before committing — the package name dates it to the eZ Platform era.