Layouts Ibexa Site Api Laravel Package

Getting Started

1. Install the bridge

   composer require netgen/layouts-ibexa-site-api
   

   Make sure the transitive requirements are already in place: netgen/layouts-core (or netgen/layouts-ibexa), netgen/ibexa-site-api, and a matching Ibexa kernel version. Check composer.json in the package for the exact constraint matrix before you upgrade anything else.

2. Register the bundle in config/bundles.php:

   Netgen\Layouts\IbexaSiteApi\NgLayoutsIbexaSiteApiBundle::class => ['all' => true],
   

   It must be loaded after NetgenLayoutsBundle, NetgenLayoutsIbexaBundle (if installed) and NetgenIbexaSiteApiBundle.

3. Where to look first

   • vendor/netgen/layouts-ibexa-site-api/lib/ — the value converters and layout resolver target handlers live here.
   • The package's config/ directory for default service definitions and the target/rule type registrations it adds to netgen_layouts.
   • Your project's config/packages/netgen_layouts.yaml — this is where you wire layouts to Site API targets.

4. First use case — map a layout to a Site API content type:

   # config/packages/netgen_layouts.yaml
   netgen_layouts:
       layout_resolver:
           rules:
               - layout: article_layout
                 target:
                   type: ibexa_site_api_content
                   value: article
   

   Then open an Article content view in the front end and confirm the layout (not the default view template) renders.

Implementation Patterns

Rule-driven layout mapping. The bridge exposes layout resolver targets keyed on Site API concepts (content type, location, subtree). The canonical workflow is: create layouts in the admin UI (/nglayouts/admin), then add rules that bind them to Site API identifiers. Keep rules ordered from most specific (single location ID) to least specific (content type) — Netgen Layouts uses the first match.

Reusing Site API queries inside layout blocks. Instead of writing controllers, expose your content listing as a Netgen Layouts query type backed by Site API's ContentService::findContent() / findLocations(), then drop the corresponding block into a layout. This keeps editorial control in the layout UI while letting developers keep the data access in Site API.

Programmatic rendering outside the CMS pipeline. When you need a layout in a custom controller or a JSON endpoint:

$layout = $this->layoutResolver->resolve($request);
if ($layout !== null) {
    $html = $this->layoutRenderer->render($layout, $request);
}

Inject Netgen\Layouts\API\Service\LayoutService / LayoutResolver and pass the current Request — the Site API-aware resolver will pick up content and location from it.

Value converters for Site API objects. If you store Site API content IDs in layout parameters, register a value converter (tagged netgen_layouts.value_converter) that accepts int and hydrates a Netgen\IbexaSiteApi\API\Values\Content. Do the same for locations. This is the cleaner alternative to calling the service inside block templates.

Overriding the block/item templates. The bridge ships default templates under @nglayouts_ibexa_site_api/. Override only the ones you need by pointing netgen_layouts.design (per design/theme) at your own templates — don't fork the package.

Multi-site setups. Ibexa Site API is multi-site aware; pass the Site into your resolver/renderer when rendering across sites so that the correct content view and layout rules apply.

Gotchas and Tips

• Version alignment is the #1 failure mode. Netgen Layouts, Ibexa Site API, and this bridge are released on different cadences. Pin all three in composer.json together, and treat any minor bump as a code-review exercise. With 0 GitHub stars and 0 dependents there is essentially no community safety net — read the changelog.
• Cache, cache, cache. After touching netgen_layouts.yaml or registering a new target/rule type, run bin/console cache:clear and clear the Layouts cache (bin/console nglayouts:cache:clear). Stale layout resolution is almost always a cache issue, not a config issue.
• Rule order matters and failures are silent. If no rule matches, Netgen Layouts falls back to the default Ibexa view template — nothing errors. Debug by temporarily adding a catch-all rule, then narrow down which target fires. Inspect logs at debug level; the resolver logs target mismatches there.
• Resolve after Site API has context. The Site API-aware resolver relies on the current Content/Location being populated on the request. In custom controllers where you call LayoutResolver before ContentService sets them up, rules will silently not match. Load content first, then resolve.
• Route naming. Site API controllers use their own route names (ngcontent_view, nglocation_view, etc.). If you write custom rules keyed on routes, use the Site API names — not the legacy eZ/Ibexa ones.
• GPL-2.0 license. Fine for GPL projects, risky for proprietary. Confirm with your legal team before pulling into a commercial codebase; the licence is viral in a way that many corporate policies disallow.
• Extension points to prefer. Custom rule target types, value converters, and query types are the intended extension surfaces — all are service-tagged and easy to override in services.yaml. Avoid monkey-patching the bridge's services.
• Bus-factor warning. Treat this as glue code you may need to maintain yourself. Keep a copy of the exact version in your lockfile, and consider adding a small integration test that asserts a known layout resolves for a known Site API content type — so an upstream regression is caught on CI rather than in production.