Layouts Ezplatform Site Api Laravel Package

Getting Started

1. Check the compatibility matrix first. This package is glue between three moving parts: netgen/layouts (Symfony-based layout builder), ezsystems/ezplatform-site-api (now ibexa/site-api), and a supported PHP/eZ Platform version. Verify the composer.json require block against your app's locked versions before install — the package version you can use is dictated by the Layouts major you're on, not the reverse.
2. Install and register the bundle.

   composer require netgen/layouts-ezplatform-site-api
   

   Add the bundle to config/bundles.php:

   Netgen\Layouts\Ez\SiteApi\NetgenLayoutsEzSiteApiBundle::class => ['all' => true],
   

   Ensure the Site API bundle (EzSystems\EzPlatformSiteApi\Bundle\EzPlatformSiteApiBundle) is registered before it — the integration consumes Site API services at container build time.
3. Look here first in vendor/: the bundle class, its DependencyInjection/ extension (Configuration.php + NetgenLayoutsEzSiteApiExtension.php), and any Resources/config/ service and YAML definition files. Layouts integrations are almost entirely configured by tagged services and netgen_layouts config, so the DI files tell you what value types, query types, and block definitions are actually available.
4. Read the two upstream docs alongside it: Netgen Layouts (value types, query types, block definitions, view types) and eZ Platform Site API (find, filter, ContentService). This package is small; the real surface area is those two.
5. First use case to try: drop a content list block into a layout in the Netgen Layouts admin UI, wire its query to a Site API search (content type, subtree of your root location), and render it with the provided view type. If content resolves and renders, the integration wiring is correct.

Implementation Patterns

Treat the package as three capabilities. In practice you'll interact with:

• Value types — embedding a site-API Content (or location) directly as a block value.
• Query types — driving block data from Site API find() / filtered queries instead of raw eZ search.
• View types / renderers — mapping a Site API content item or content list item to your Twig templates and eZ view configuration.

Configure queries at the block-definition level, not in PHP. Layouts intends block queries to be configured in config/packages/netgen_layouts.yaml (and per-siteaccess where relevant). Keep query shape, content types, and limits in YAML so editors can adjust them in the admin UI without a deploy. Reserve code for custom query handlers only when Site API's filter DSL genuinely can't express the query.

Prefer Site API for reads inside layouts. Do not reach for ezpublish / ContentService inside a layout block if the Site API equivalent exists. The whole point of this integration is consistent resolution (content IDs + remote IDs, correct language/translation fallback, correct siteaccess root). Mixing the two leads to content resolving in some block configurations and not others.

Template integration. Wire your Site API content to rendering through eZ view configuration (ezplatform.yaml content-view / view-type rules) rather than hardcoding Twig paths in the block view_type. This keeps the layout's rendering consistent with the rest of the site and lets you reuse existing content views. Use the package's view type as the bridge; keep rendering logic in eZ views.

Multi-siteaccess discipline. Use netgen_layouts.system / siteaccess-aware configuration for things like root location IDs, content type restrictions, and view selection. This is where a "works locally, broken in prod" bug most often appears.

Cache/HTTP layer integration. Layouts emits its own cache tags; Site API content items participate in eZ's cache. If you add custom query handlers or value converters, propagate the relevant cache tags/invalidation keys — otherwise editors see stale blocks after publishing.

Extend via DI tags, not by monkey-patching. If you need a new block definition or query type, register it as a tagged service in your app and mirror what the bundle does in its Resources/config/. Layouts is designed to be extended this way; subclassing package classes is fragile across minor upgrades.

Gotchas and Tips

• GPL-2.0 license. Netgen Layouts itself is GPL and this integration inherits that. If this is a commercial/hosted product, confirm with legal before shipping. This is a real blocker for many teams and a common source of last-minute scope changes.
• Version pinning is the biggest risk. With 11 stars and 0 dependents, you're on a long tail of the ecosystem — expect to upgrade netgen/layouts, Site API, and this package as one unit. Lock all three with tight constraints and test on upgrade. Never let Composer float the Integration package alone.
• Ibexa rename fallout. Older releases of this package target ezsystems/* package names; newer Ibexa installs use ibexa/*. Match namespaces and bundle class paths to your eZ Platform/Ibexa major or the bundle class won't autoload.
• Cache clearing is not optional. After editing netgen_layouts.yaml, block definitions, or view config, run bin/console cache:clear and clear the Layouts cache (admin "clear cache" action or netgen:layouts:clear-cache-style command if present in your Layouts version). Symfony cache alone often isn't sufficient because Layouts caches serialized layout structures.
• Admin vs front-end discrepancies. Blocks that render fine in the Layouts admin preview may fail on the site (or vice versa) because they run under different siteaccess context and different view resolver sets. Always verify both.
• "Content not found" usually means root location mismatch. If Site API queries return empty inside a layout but fine in a controller, the block's query is likely using a root location ID that only resolves under the wrong siteaccess. Log the resolved LocationQuery and root, and compare to the controller case.
• Watch the maintainer/activity signal. With this dependency score, treat the package as a thin shim you may need to own. Keep a local fork path in mind, and document (internally) which classes you depend on. Review recent commits/tags before a major framework upgrade — being a release behind on the Layouts major is the most common reason this integration stops working.
• Debug entry points: Layouts logs under var/log/ with netgen_layouts logger channel; Site API query failures surface through its own logger. Turn both to debug when a block renders empty — the split between "query returned nothing" and "rendering failed for found content" is where most debugging time is spent.