Admin Bundle Laravel Package

Getting Started

First, the honest framing: as a Laravel developer you cannot composer require sylius/admin-bundle and get an admin panel. This is a Symfony bundle and the back-office UI of the Sylius e-commerce platform — it boots off the Symfony kernel, Symfony DI, Twig, Sylius ResourceBundle/GridBundle/UiBundle, and Symfony Security. Laravel's container, Blade, Eloquent, auth guards, and Vite pipeline do not map onto any of that. Composer may resolve the package, but nothing will render.

If you are evaluating it, look at sylius/sylius (the distribution), not this repo. This is a read-only subtree split; all development and PRs live in the monorepo, and release versions track Sylius releases. The 7 stars / 0 dependents are split-repo artifacts — not a health signal.

Where to look first (in a real Sylius app, not a Laravel one):

1. Resources/config/routing.yml and Resources/config/app/*.yml — how grids, forms, menus, and resources are pulled in.
2. Resources/views/ — every screen is an overridable Twig template; 80% of customisation happens here.
3. DependencyInjection/Configuration.php — the actual sylius_admin config surface.
4. Resources/config/services*.xml — service IDs you decorate or replace.

First realistic use case from a Laravel codebase is not editing this bundle; it is standing up Sylius as a separate Symfony service and consuming it from Laravel. Concretely: a Sylius instance at shop.example.com with its admin at /admin, a matching admin account created via bin/console sylius:admin-user:create, and Laravel calling the Sylius API for catalog/orders. Do that end-to-end (create a product in Sylius admin, read it back in Laravel) before touching any templates.

Implementation Patterns

Pattern 1 — Sylius sidecar, Laravel as system of record. The realistic Laravel pattern. Sylius runs as its own Symfony app with this admin attached; Laravel owns auth/SSO, business workflows, and the customer-facing app, and integrates via API, webhooks, and a message queue. Keep database ownership clean (one service owns commerce tables), and never reach across from Eloquent into Sylius's schema.

Pattern 2 — Sylius admin as the operator UI, Laravel admin for everything else. Ops staff manage catalog/orders/promotions in the Sylius admin; domain-specific back-office tools (fulfilment quirks, B2B pricing, internal ops) live in Laravel/Nova/Filament and call Sylius APIs. Prevents you from rebuilding commerce CRUD in Laravel.

Pattern 3 — Headless: ignore this bundle. Expose Sylius via API Platform, build the admin in Laravel (Filament/Nova) against those APIs. Choose this when UI is a core differentiator or when you cannot staff a Symfony team — you lose template-override leverage but keep one framework in the org.

Inside the Sylius app, customisation is override-first (not fork):

• Twig overrides — mirror the original path under templates/bundles/SyliusAdminBundle/.... Prefer {% extends '@!SyliusAdmin/...' %} with block overrides over copy-paste so upstream fixes reach you. Block names differ across Sylius 1.x → 2.x, which materially restructured the admin.
• Grid overrides — every index/list page is a sylius_grid definition. Re-declare the grid with the same name in config/packages/sylius_grid.yaml to add a column (e.g. type: twig with a template) or filter, rather than touching controllers.
• Form type extension — decorate/replace form types in config rather than subclassing controllers.
• Menu extension — register a menu listener / builder to add entries; the admin menu is a KnpMenu-style tree, not a static template.
• Actions — add custom controller actions mapped into resource routing and referenced from grid item actions.

Integration tips.

• Put SSO at the Laravel IdP edge and have Sylius delegate/accept tokens; don't duplicate password stores between Laravel and Sylius admin users.
• Version-pin Sylius (and thereby this bundle) explicitly; treat an upgrade as a planned workstream, not a composer update.
• Isolate all customisations under templates/bundles/, config/packages/, and your own bundle namespace so upgrades don't fight you.
• Prefer async (queue/outbox) over synchronous Laravel↔Sylius calls for order/payment events.

Gotchas and Tips

• Framework mismatch is a hard wall, not a hill. Don't attempt to embed this bundle in a Laravel monolith, load Symfony DI, or wire its routing into Laravel's router. The only honest paths are: install Sylius separately, or build against the Sylius API and skip this package.
• Auth and session collisions. Laravel's guards and Symfony firewalls are separate worlds. Two independent session domains, matching ROLE_ADMINISTRATION_ACCESS, and an admin firewall with its own provider is the norm; SSO is where you reconcile them. Watch switch_user and admin regex scoping carefully — a mis-scoped %sylius.security.admin_regex% is a common cause of unexplained 401/403 on /admin.
• It's a read-only split. Local patches get lost on the next Sylius release. Fork the monorepo, or contribute upstream — never fork the split expecting it to stay mergeable.
• Upgrade churn. The admin UI changed materially in Sylius 2.0 — Twig blocks, asset pipeline (Webpack Encore), menus, and grid structure moved. Budget for template re-auditing at each Sylius major, not just Composer bumps.
• Asset pipeline. Sylius admin uses Webpack Encore; Laravel uses Vite/Mix. If you're trying to proxy assets or share a build, stop — keep Sylius's asset build entirely inside the Sylius app.
• Debugging. Missing template changes usually mean a wrong shadow path or a block name that changed between versions — verify against the vendored original for the exact pinned version, not GitHub master.
• Low star/dependent count is noise on this repo. Judging health, support, or ecosystem from 7 stars / 0 dependents is misleading; measure against Sylius/Sylius release cadence and community instead.
• When to pick something else: if you're not on Sylius, use Filament/Nova/EasyAdmin in Laravel, or an SPA admin against Sylius's API. If workflows are deeply domain-specific (B2B pricing, WMS, manufacturing), build sidecar services and integrate rather than forcing this bundle to be something it isn't.