Layouts Sylius Laravel Package

Getting Started

Prerequisites. The integration assumes a working Sylius application on Symfony (Sylius ^1.11 / ^2.x depending on the released tag) and pulls in netgen/layouts (core) plus netgen/layouts-standard, netgen/layouts-ui, and the Doctrine storage layer as Composer dependencies. Because the package has only ~23 stars and no downstream dependents, treat the version matrix as the first thing you verify before writing any code — check the package's composer.json constraint against your Sylius and Symfony versions, not just the README.

Minimal install sequence:

composer require netgen/layouts-sylius

1. Register the bundles in config/bundles.php — the core Layouts bundles (NetgenLayoutsBundle, NetgenLayoutsStandardBundle, NetgenLayoutsUiBundle, NetgenLayoutsDoctrineBundle) plus NetgenLayoutsSyliusBundle. Ordering matters: the Sylius bundle must come after the core Layouts bundles so its compiler passes can decorate the standard ones.
2. Import routing in config/routes.yaml for the Layouts UI (admin) and the Sylius-flavored admin routes.
3. Publish/execute Doctrine migrations. The package ships its own schema for layouts, zones, blocks, rules/rule targets, and item views. Run bin/console doctrine:migrations:migrate and confirm the nglayouts_* tables exist alongside sylius_*.
4. Configure netgen_layouts_sylius in config/packages/ — at minimum the Doctrine entity manager and the list of enabled Sylius resources you want exposed to the layer/context system.
5. Build assets if the UI assets are shipped unbundled (yarn install && yarn build, or bin/console assets:install --symlink if they are prebuilt). Clear cache.

Where to look first. Read the package's Resources/config/ directory before the README. This is where the bundle wires its context providers, block definitions, and item view types into the Netgen Layouts extension system — it tells you exactly which Sylius entities (Product, Taxon, Channel) are exposed and under which service IDs. Then look at Netgen/Layouts/Sylius/Context/ and Netgen/Layouts/Sylius/Block/ to see what targeting rules and block types you get out of the box. The Netgen Layouts core docs (docs.netgen.io) are far more complete than this package's own docs; the Sylius layer is a thin adapter over those core concepts.

First use case — a targeted homepage. In the Sylius admin, navigate to the Layouts section (typically under the "Content" or a dedicated "Layouts" menu). Create a layout named "Homepage", add a rule that targets the sylius_shop_homepage route, add a two-column zone structure, drop in a "Title" and "Text" block. Preview. Then override templates/bundles/SyliusShopBundle/Homepage/index.html.twig to replace the default content with the Layouts render call (usually {{ nglayouts_render_layout() }} or the Twig function re-exported by the integration). Clear cache and verify. That single loop — layout in admin → rule → render in template — is the entire mental model; everything else is a variation.

Implementation Patterns

Targeting via Sylius context. The integration's main value is exposing Sylius data to Layouts' rule system. Out of the box you'll typically get rule types for "route matches", "product is", "taxon is", and channel-aware targeting. The standard pattern is:

• One layout per page archetype (product detail, category listing, homepage, cart, checkout success) targeted by route.
• Further narrowing via product/taxon rules for landing pages — e.g. a "Spring collection" layout that takes precedence over the generic taxon layout because its rules are more specific. Netgen Layouts resolves the most specific matching rule set; this is the entire point of not just hardcoding templates.

Day-to-day, whenever merchandising asks for "a special page for X", the answer is a new layout + rule, not a new Twig template and deploy.

Template override as the render seam. The integration does not magically replace Sylius templates. You explicitly override the relevant Sylius templates and call the Layouts render function. The common touchpoints are:

• SyliusShopBundle/Homepage/index.html.twig
• SyliusShopBundle/Product/show.html.twig
• SyliusShopBundle/Taxon/show.html.twig
• SyliusShopBundle/Cart/index.html.twig

Keep the override thin — render the layout inside a {% block %} that Sylius' own template defines, so future Sylius upgrades that change the surrounding markup still work. Resist the urge to override wholesale.

Reusable blocks as a content library. Blocks are global, not scoped to a layout. The pattern that pays off: build a small library of shared blocks (promo banner, footer newsletter, "featured products" via a Sylius-specific block type), then place the same block in multiple layouts. Edits propagate. Use block collection blocks for repeated lists of child blocks (e.g. a slider where each slide is a child block) rather than duplicating blocks.

Sylius-aware block types. Look for block types that render Sylius entities — product and product-list blocks that take a product code or taxon and render using Sylius' own Twig helpers. This is where the integration earns its keep versus plain Layouts: those blocks respect Sylius' pricing, channel pricing, translation, and inventory state. If a required block type is missing, that's your cue to write one (see extension points below).

Programmatic layout creation. For layouts that must exist on every deploy (a base product layout, a checkout layout), don't create them by hand in staging. Use Layouts' PHP API in a Doctrine fixture or a console command: LayoutService::createLayout(), ZoneService::createZone(), BlockService::createBlock(), attach rules via RuleService::addRule(). This keeps environments reproducible and makes CI able to assert that the baseline layout set exists. It's more code than admin clicking, but it's the only way to keep staging/prod in sync without a content migration tool.

Theme and asset integration. Sylius' theming (SyliusShopBundle inheritance, ThemeBundle) sits underneath the Layouts render call — the layout render happens inside a Sylius template, so Sylius theming still applies. Keep custom block templates in the theme's bundles/ or your own bundle's Resources/views/; don't put them inside vendor.

Multi-channel. If you're running multiple Sylius channels, use a channel rule on every layout. Forgetting this is the single most common way a layout "leaks" onto the wrong channel — because without a channel rule, a layout targeted only by route will match on every channel sharing that route.

Gotchas and Tips

Version compatibility is the biggest risk. With 23 stars and no dependents, you are on the bleeding edge. The package's Sylius constraint is the hard ceiling on your composer.json. Pin the package version explicitly (netgen/layouts-sylius:^X.Y) and pin netgen/layouts* to the matching minor line — Layouts has had breaking changes across majors that this integration follows. Test a Sylius minor upgrade in a branch before merging; the template overrides in your app are where breakage surfaces first.

Doctrine mapping collisions. Layouts' Doctrine storage ships its own entity mapping. If you have any custom entity that extends or relates to Layouts entities, be careful with resolve_target_entities and don't accidentally have two mappings to the same table. If migrations fail with "table already exists," you likely installed Layouts core separately in an older version — do a clean migrate in a fresh DB to confirm the schema is the package's, not a leftover.

Cache is aggressive and layered. Three caches bite you:

• Symfony cache (cache:clear after config changes).
• Layouts' layout resolver cache (which layout applies to a URL) — the UI usually has a "clear cache" action, and there's a console command (netgen:layouts:... — check bin/console list netgen); wire it into your deploy script.
• The block/render cache for cached blocks.

When an admin edit "doesn't show up," it's almost always one of these, not a bug.

Debugging which layout applied. Enable the Symfony profiler and use the Layouts panel (if shipped) or look for the nglayouts collector; it lists the resolved layout, matched rules, and zones rendered. Without the profiler, add a dump() inside your overridden template around the render call to confirm the layout ID and that the template override is actually the one being loaded (check bin/console debug:twig for the template path — theme overrides can shadow your app override and vice versa).

Rule specificity is not intuitive. When two layouts both match, Layouts picks based on rule ordering/specificity, which is not always "the more specific rule wins" in the way you expect. Test with two overlapping layouts deliberately and read the resolved-layout debug output. If it's ambiguous, add an explicit shared rule (e