Layouts Ezplatform Relation List Query Laravel Package

Getting Started

Confirm the stack before anything else. This is not a Laravel package. There is no Illuminate\Support\ServiceProvider, no extra.laravel.providers in composer.json, and no contract with the Laravel container or Eloquent. It is a Symfony bundle for eZ Platform / Ibexa 2.x–3.x that adds a query type to Netgen Layouts. If your application is Laravel, stop here and consume relation data over Ibexa's REST or GraphQL API instead — see the integration note below.

Assuming an eZ Platform + Netgen Layouts application:

1. Install and register.

   composer require se7enxweb/layouts-ezplatform-relation-list-query
   

   Register the bundle next to NetgenLayoutsEzPlatformBundle — in config/bundles.php on Symfony 4/5, or app/AppKernel.php on older eZ installs.
2. Clear and verify.

   bin/console cache:clear
   bin/console debug:container --tag=netgen_layouts.query_type
   

   You should see a new query type registered by the bundle. If it is absent, the bundle is not loading (check config/bundles.php ordering) or the Netgen Layouts version constraint conflicts.
3. Where to look first. Read the bundle's query type class (the service tagged as a Layouts query type) and its Resources/config/*.yml. That file is the authoritative list of supported configuration keys — field identifier, limit, offset, filtering — which is more reliable than the README for a small fork.
4. First use case: a "Related articles" block. Add a block to your article layout, set item type to the relation-list query type, point it at the current content's relation-list field (e.g. related_articles), set a limit of 3, and render it with the standard Layouts content item view template. That single block replaces the most common hardcoded-content ticket.

If you are on Laravel, the correct first use case is the API adapter: fetch the parent content via Ibexa REST/GraphQL, resolve the relation-list field to content IDs, batch-load those, and expose them to your Blade partial. That keeps the eZ kernel out of your dependency graph entirely.

Implementation Patterns

Configure queries in the Layouts admin where possible, in YAML where you need reuse. For a repeated module (topic hubs, "more from this section"), define the block once in a Layouts YAML config with the field identifier parameterized, then let editors instantiate it. Hardcoding field identifiers per block defeats the point of the package.

Pass context explicitly. The query needs to know which content's relation list to read. Wire the current location/content into the query via the layout's value resolvers so the same block definition works on every article page:

# Layouts block definition (representative shape)
query:
    type: ezplatform_relation_list
    parameters:
        content: '@=content'          # current content from layout context
        field: related_articles
        limit: 6

Treat the relation list as IDs, not as content. The relation-list field returns an ordered set of content IDs. Load them in one call — $contentService->loadContentList($ids) — and render from that result set. Never call loadContent() inside a {% for %} loop; that is the N+1 that will hurt you on hub pages with three relation modules.

Ordering: decide which side wins. Relation-list fields in eZ store an explicit order (the order an editor dragged them into). If the query type also accepts a sort parameter, document which one is authoritative for your project. Mixing them produces the classic "why did the block reorder itself after an editor saved" bug.

Build a fallback branch. Editors leave relation lists empty. Pair the query with a secondary query (most-recent-in-section, same-content-type) so the block degrades to something useful rather than rendering an empty <div>. Model this at the block level, not in the template.

Cache at the Layouts layer, not in the handler. Set a view/block cache TTL on the block. Relation lists change rarely, but the block is rendered per page; without block-level caching you re-execute the same relation query on every request to every hub page.

Integrate with the content view pipeline. Items resolved by the query should flow through the normal ez_render_content / content-view template resolution so your existing content-type templates apply without special-casing.

Pin the version and stage the diff. Given the release history, require "se7enxweb/layouts-ezplatform-relation-list-query": "1.4.2" rather than ^1.4 in a production application, and diff rendered HTML between versions on a staging copy of a real layout before promoting.

Gotchas and Tips

• Do not attempt to install this in a Laravel app. No auto-discovery, no Laravel config publishing, no Eloquent relationship. The practical alternative — Ibexa REST/GraphQL into a Laravel service — is a day of adapter work versus standing up a Symfony/eZ kernel. Record the decision so it does not get relitigated.
• Field identifier vs. content type name. The most common misconfiguration is passing the content-type identifier where the field identifier is expected (or vice versa). If the block renders empty with no error, that is the first thing to check. Log the resolved field value during development.
• Visibility and permission filtering is not guaranteed. A relation list can point at hidden, archived, or now-unpublished content, and at content the current user cannot read. Verify whether the handler filters these; if not, filter in the loader step or your template will render ghost links and 404s.
• Drafts and newly published content. Relation lists are stored on the published version. If an editor adds a relation and the block does not update, check publish state and cache before suspecting the query.
• Cache invalidation is the sharpest edge. Updating a relation-list field on content A may not invalidate the layout block cached for page B. Configure cache tags/TTL at the block level, and know your purge path (bin/console ezplatform:cache:clear variants or the platform's HTTP cache) before you go live.
• Pagination is manual. Relation lists are arrays, not query objects; offset/limit on a small array is fine, but true paginated listings over hundreds of related items belong in a content query, not here. Cap the list and link to a filtered listing instead.
• Debugging. Use debug:container --tag=netgen_layouts.query_type to confirm registration, Xdebug into the query type's getQuery/buildQuery path to see the resolved parameters, and check var/log/ for Layouts query exceptions that get swallowed into an empty block. An empty block is almost never a template problem.
• Extension point. The cleanest customization is your own query type service that decorates or extends this one — add project-specific filtering (section, visibility) there rather than forking the bundle. Keep the fork pristine so upstream reconciliation stays cheap.
• Sourcing risk is real. v1.4.2 shipped with a changelog containing only a compare link. Treat every release as potentially behavioral: read the diff, and run composer audit and composer outdated --direct before merging. Keep an owner on the quarterly dependency review, and keep the ability to disable an affected layout block at runtime.
• Scaling. Cost scales with content volume × layout pages, not request rate alone. Watch for multiple relation-list blocks on one page and for large relation sets without limits — those are the two configurations that bite under load.