Sylius Happy Cms Plugin Laravel Package

Getting Started

What this package is: agence-adeliom/sylius-happy-cms-plugin layers a CMS (pages, blocks, CMF routes) on top of a Sylius/Symfony application and wires that content into the admin via easy-crud. Day to day, you'll spend most of your time defining blocks and routes, then letting the plugin's makers scaffold the admin CRUD around them.

Minimal setup

1. composer require agence-adeliom/sylius-happy-cms-plugin
2. Register the bundle in config/bundles.php and import the plugin's routing/config (check the package README — the agence-adeliom docs are French-first).
3. Run the migrations for the CMS tables.
4. Log into the Sylius admin and confirm the CMS section appears — that's your smoke test that easy-crud picked up the admin classes.

Where to look first

• The plugin's src/ for the block/route entities and their registries — this tells you what's extensible vs. what's baked in.
• Existing admin classes: as of v2.4.0 these are annotated with #[AsAdmin] rather than registered through CrudAdminFactory. Reading one of these is the fastest way to understand the wiring.
• The makers. They are the intended authoring path — don't hand-roll an admin class until you've seen what the maker produces.

First use case: create a simple content block (e.g. a promo banner), expose it as a CMF route, and render it in a Twig template on the storefront. That exercises the whole loop: entity → admin CRUD → route → template.

Version note: v2.4.0 targets easy-crud 2.4. If you're on easy-crud 2.3, pin the plugin to 2.3.x.

Implementation Patterns

Attribute-driven admin (the v2.4 way) Admin CRUD classes are now declared with #[AsAdmin] instead of being constructed by the removed CrudAdminFactory. The practical consequence is that admin configuration lives on the class — fields, filters, actions — which makes it greppable and diff-friendly. Pattern: one admin class per CMS resource, keep it thin, push display logic into Twig.

Maker-first workflow

1. Run the plugin's maker to scaffold the new CMS resource and its admin class.
2. The maker emits the #[AsAdmin] attribute for you — verify it, then adjust fields/filters by hand.
3. Add the corresponding Twig template/partial.
4. Register the block type so editors can drop it into a page.

Treat the maker output as the baseline contract; re-running makers after a plugin upgrade is the cheapest way to see what the new conventions look like.

Rendering blocks Keep block templates small and self-contained, resolving their data from the block entity rather than from globals. When a block needs variants, prefer separate block types over conditionals inside one template — the admin UI stays comprehensible and editors don't get a wall of options.

CMF routes over hardcoded controller routes Model content URLs as CMF routes so editors can change slugs without a deploy. Reserve ordinary Symfony routes for application behaviour (cart, checkout, account).

AI-assisted development via Symfony AI Mate (new in v2.4.0) The plugin now exposes AI Mate tools for CMF routes and blocks. With the AI Mate MCP server configured in your editor/agent, you can ask things like "which routes point at this template?" or "what blocks are registered?" without grepping. Useful pattern: let the agent enumerate existing routes/blocks before generating new ones, so it doesn't duplicate a block type that already exists. Treat the tools as read/inspection helpers — review anything the agent writes back.

Multi-store / multi-locale If the Sylius app is multi-channel or multi-locale, decide early whether CMS content is global or per-channel. Retrofitting channel awareness onto blocks after editors have populated content is painful.

Gotchas and Tips

The easy-crud 2.4 break is real but narrow. CrudAdminFactory is gone. If you only ever used the plugin's makers, you're fine. If you wrote custom services that injected or extended CrudAdminFactory, or subclasses overriding its methods, you must migrate to #[AsAdmin]. Grep your src/ and config/ for CrudAdminFactory before upgrading — that's the whole migration check.

Pin versions deliberately. Plugin v2.4.0 + easy-crud 2.4 go together. A partial upgrade (plugin bumped, easy-crud left at 2.3, or vice versa) produces confusing "class not found" or "admin section missing" symptoms rather than a clean error.

Maker output drifts between versions. If you've customised a generated admin class heavily, don't blindly overwrite it when re-running makers after an upgrade. Diff first; the #[AsAdmin] attribute generation is the headline change in v2.4.0.

Admin section not appearing? In order: (1) is the class actually annotated with #[AsAdmin] and in a scanned namespace? (2) bin/console cache:clear; (3) bin/console debug:container --tag=<easy-crud admin tag> to confirm registration. Most "it vanished" reports are stale cache or a namespace outside the scan path.

Debugging routes and blocks bin/console debug:router for CMF routes; the block registry is best inspected via debug:container or — now — by asking the AI Mate tools directly. For "why is my block not rendering", check the block type registration before you check the template.

Translation and locale traps. CMS content typically needs a fallback per locale. If a page renders empty on a secondary locale, it's usually a missing translation row, not a template bug.

Documentation is French-first. The agence-adeliom ecosystem assumes French-reading developers. Budget extra time for the README and changelog, and lean on the source and the makers as the authoritative spec.

AI Mate tooling is an extension point, not magic. It's genuinely handy for discovery in a large CMF, but it reflects the current container state — after adding blocks or routes, clear cache before expecting the agent to see them.

Upgrade checklist for v2.4.0

1. Grep for CrudAdminFactory; migrate any hits to #[AsAdmin].
2. Bump easy-crud to ^2.4.
3. Clear cache; verify each admin section still loads.
4. Re-run a maker on a scratch branch to confirm the new attribute convention.
5. Optionally wire up AI Mate and spot-check route/block listing.