Layouts Sylius Bitbag Laravel Package

Getting Started

This is a thin integration layer between Netgen Layouts (layout engine), Sylius (e-commerce), and BitBag Sylius CMS (CMS pages/blocks). It ships block handlers and value types so BitBag CMS content can be dropped into Netgen layouts and used as layout-resolution criteria. Do not expect documentation — read the bundle source and the parent netgen/layouts-sylius bundle first; this one mostly extends it.

Minimal steps:

1. Install alongside its prerequisites (versions must line up — check the composer.json constraints of all three):

   composer require netgen/layouts-sylius netgen/layouts-sylius-bitbag bitbag/sylius-cms-plugin
   

2. Register the bundle after the BitBag CMS and Netgen Layouts Sylius bundles in config/bundles.php:

   Netgen\Bundle\LayoutsSyliusBitBagBundle\NetgenLayoutsSyliusBitBagBundle::class => ['all' => true],
   

3. Import routing/config: BitBag CMS admin routes must already exist; then the bundle auto-registers Netgen Layouts block definitions and value types via its extension.
4. First use case: in the Netgen Layouts admin (/admin/netgen-layouts), edit a layout, open the block library, and add a BitBag CMS Page or BitBag CMS Block block. Point it at an existing CMS page/block created through BitBag's admin.

Where to look first:

• DependencyInjection/ — what block definitions and value types get registered and under what names.
• Block/ (or Block/Handler/) — how CMS content is loaded and passed to the view.
• Resources/views/ — the Twig templates you will inevitably override.
• ValueType/ / QueryType/ — how CMS pages are resolved for rule matching and listing.

Implementation Patterns

Compose layouts around CMS content. The typical pattern is: BitBag CMS Page provides the canonical content object; Netgen Layouts resolves a layout for that page via a rule matching a bitbag_cms_page value type; the layout contains zones, and one of those zones contains a bitbag_cms_block block pulling the CMS block. Keep the "which CMS page am I on" resolution in a rule, not in Twig.

Rule-based targeting. Use the registered value types in netgen_layouts.yaml under value_definitions/rule_targets to target rules at specific CMS pages, CMS sections, or "any CMS page". This is the whole point of the integration — you get CMS-aware layout resolution without writing a custom resolver.

Reuse CMS blocks across layouts. Define a block of type bitbag_cms_block once, reference the same BitBag CMS block from several layouts, and edit content in BitBag's own admin. Editors edit content in the CMS plugin, marketers reorganize in Netgen Layouts. Preserve that split.

Twig rendering. Render with the bundle’s templates and only override where necessary:

{{ netgen_layouts_render('layout', { layout_resolver: 'my_resolver' }) }}

For CMS blocks inside a layout, the block view template is chosen from the block definition’s views. Add your own view entries in netgen_layouts.yaml and let the CMS editor pick via the block’s view selector.

Query types for listings. If the bundle exposes query types for listing BitBag pages (e.g. in a "content list" block), configure them in the layout block’s parameters so the CMS side owns the data while the layout owns presentation.

Integration tip — content-first routing. Let BitBag’s dynamic router own the URL, and hook Netgen Layouts rendering into the BitBag page controller via a controller override or a kernel-view/response listener. Never let Netgen Layouts own routing for CMS pages; that produces duplicate-slug conflicts.

Testing hooks. Because of the version coupling (Sylius + BitBag CMS + Netgen Layouts), add a smoke test that boots the kernel, fetches / and a CMS page URL, and asserts HTTP 200. That single test catches most upgrade breakage in this stack.

Gotchas and Tips

• Bundle registration order is load-bearing. BitBag CMS → Netgen Layouts → Netgen Layouts Sylius → this bundle. Wrong order leads to "service not found" for the CMS repositories during container compilation.
• Zero community footprint. 0 stars, 0 dependents means no StackOverflow answers. Pin exact versions in composer.json and treat a minor bump of any of the three parents as a migration. Read the diff of netgen/layouts-sylius on every upgrade — this bundle inherits its breakage.
• CMS content may be null. The block handler resolves a BitBag page/block by ID or slug; deleted or unpublished CMS entities yield null and can throw in the view. Guard in your Twig override:

  {% if content is not empty %}{{ ... }}{% endif %}
  

• Caching invalidation. Netgen Layouts and Sylius both cache aggressively. Editing a BitBag CMS block in Sylius admin may not invalidate the Netgen Layouts cache entry that embeds it. Wire BitBag’s entity listeners (or add a Doctrine postUpdate/postPersist subscriber) to call Netgen Layouts’ cache clear for layouts referencing that block, or accept "clear cache after editing content" as an operational note for editors.
• Value type IDs are Doctrine IDs, not slugs. Rule targeting usually matches on the CMS page/block identifier. If content is re-imported and IDs shift, rules silently stop matching. Prefer targeting by slug/section through a custom value type if your content lifecycle involves migrations.
• Two admin UIs. Editors have to learn BitBag CMS admin (content) and Netgen Layouts admin (layout). Decide up front which one is the "entry point" and link between them; don’t leave this ambiguous.
• Template overrides. Override templates by copying from Resources/views/ into templates/bundles/NetgenLayoutsSyliusBitBagBundle/ (Symfony bundle override convention) rather than editing vendor files — you will need to, since the default views are minimal.
• Config quirks. The Symfony extension normally registers block definitions implicitly. If a block type doesn’t appear in the library, check that netgen_layouts.php (or .yml) doesn’t have a block_definitions key that replaces rather than merges — use YAML merge (!php/const / _defaults) or import the bundle’s config explicitly.
• Testing without fixtures. There are no fixtures in the repo. Create BitBag CMS pages/blocks in a Doctrine fixture that runs after Sylius fixtures, or every test run against a fresh DB will produce empty layouts.
• Debugging layout resolution. Use bin/console debug:container netgen_layouts.layout_resolver and debug:container --tag=netgen_layouts.block_definition to confirm what this bundle actually registered. When a block or rule target seems missing, this is faster than reading the source.
• Extension points to know: netgen_layouts.block_definitions, netgen_layouts.value_types, and the block handler service tag netgen_layouts.block.handler. Registering your own handler here is often cleaner than forking this bundle — especially if you need to add fields (e.g. "show excerpt only") to the CMS block type.