Web Bundle Laravel Package

Getting Started

Read the deprecation before anything else. This repository is archived and the package description is literally "DEPRECATED — see Sylius/Sylius." For new work, the correct first step is to close this tab and depend on sylius/sylius (or the split bundles that replaced this one: sylius/resource-bundle, sylius/grid-bundle, sylius/ui-bundle, sylius/admin-bundle, sylius/shop-bundle). Everything below assumes you have inherited a legacy Sylius application that still has sylius/web-bundle in its lock file and you need to work in it this week.

Step 1 — establish what you actually have.

composer show sylius/web-bundle
# Look at: version, requires (php, symfony/*), and the "replaces"/"provides" block
composer why sylius/web-bundle        # is it direct, or pulled transitively?

Record the version and the Symfony constraint. This bundle predates Symfony 4's bundle-less structure, so you are almost certainly on Symfony 2.8/3.x and possibly PHP 5.6–7.x. That constrains every other decision you make.

Step 2 — confirm kernel registration. In a legacy app/AppKernel.php, bundles are registered explicitly and order matters — the web bundle expects the resource bundle and Twig to already be present:

// app/AppKernel.php
$bundles = [
    new Symfony\Bundle\FrameworkBundle\FrameworkBundle(),
    new Symfony\Bundle\TwigBundle\TwigBundle(),
    new Sylius\Bundle\ResourceBundle\SyliusResourceBundle(),
    new Sylius\Bundle\WebBundle\SyliusWebBundle(),
];

Step 3 — verify the wiring before touching a template. Most "the bundle is broken" reports are really cache or asset-install problems:

bin/console debug:router | grep sylius          # are the storefront/admin routes mounted?
bin/console debug:container | grep -i sylius    # are services compiled in?
bin/console debug:twig | grep sylius            # are Twig extensions/paths registered?
bin/console assets:install --symlink
bin/console cache:clear

Where to look first, by intent:

First real use case: override a single storefront template. Do not fork the bundle and do not edit vendor/. Create the mirror path in your application and let Twig's loader chain pick it up — that is the entire extension model this bundle was designed around, and it is the cheapest, safest change you can make on day one.

Implementation Patterns

1. Template overriding via the loader chain (the primary pattern). Twig resolves templates by bundle name, and an app-level path shadows the bundle's path. In legacy Symfony the app override directory is:

app/Resources/SyliusWebBundle/views/<same/relative/path>.html.twig

So to replace Resources/views/Frontend/Product/show.html.twig you create app/Resources/SyliusWebBundle/views/Frontend/Product/show.html.twig. From inside the override you can still render the original:

{# app/Resources/SyliusWebBundle/views/Frontend/Product/show.html.twig #}
{% extends 'SyliusWebBundle:Frontend/Product:show.html.twig' %}
{# note: extending the same path recurses — extend a *different* parent,
   or use {% block %} overrides against the layout instead #}

The pragmatic rule: extend a layout or partial one level up, and override only the specific {% block %} you care about. Keep the override list small — every overridden template is a file you now own and must re-check on every Sylius upgrade.

2. Controller overriding. Subclass the bundle controller, keep the class name identical enough to be recognisable, and rewrite the route to point at yours:

namespace AppBundle\Controller;

use Sylius\Bundle\WebBundle\Controller\Frontend\ProductController as BaseController;

class ProductController extends BaseController
{
    // override only what you need; everything else is inherited
}

Then re-point the route without changing the route name (see Gotchas):

# app/config/routing.yml
sylius_frontend_product_show:
    path: /product/{slug}
    defaults: { _controller: AppBundle:Frontend/Product:show }

3. Routing: import first, override second. The bundle ships its route definitions as YAML under Resources/config/routing/. Import the whole set so route names exist, then override individual names afterwards:

# app/config/routing.yml
sylius_web:
    resource: "@SyliusWebBundle/Resources/config/routing/main.yml"

# later in the same file — overrides win because they are defined last
sylius_frontend_product_show:
    path: /p/{slug}
    defaults: { _controller: AppBundle:Frontend/Product:show }

4. Twig extensions and view helpers. The bundle contributes view helpers used by the stock templates (price formatting, inventory labels, cart widgets). When you write custom templates, reuse those helpers rather than re-deriving values from entities — it keeps your overrides compatible when the underlying domain changes. Register your own alongside them:

# app/config/services.yml
services:
    app.twig.store_extension:
        class: AppBundle\Twig\StoreExtension
        tags: [{ name: twig.extension }]

5. Service decoration for behavioural changes. If you need to alter a service the bundle wires (a repository query, a view model builder), decorate it rather than replacing the definition wholesale — replacement loses every constructor argument the bundle set up:

services:
    app.product_repository.decorator:
        class: AppBundle\Repository\ProductRepositoryDecorator
        decorates: sylius.repository.product
        arguments: ['@app.product_repository.decorator.inner']

6. Day-to-day workflow discipline. Because there is no upstream, treat every change as a first-party change:

• Branch per override; keep a changelog of which bundle files you shadowed and why.
• Add a smoke test that boots the kernel and asserts the storefront home and product-show routes return 200. This catches broken container compilation after any composer update.
• Never run composer update casually. Use composer update --lock/pinning; this dependency tree has no one upstream fixing constraint conflicts.
• Diff your overrides against the vendor files whenever the Sylius version changes.

7. Planning the exit while you work. Each time you touch a bundle file, note the corresponding sylius/sylius (or split-bundle) class so the eventual migration is a mapping table, not an archaeology project. The web layer in modern Sylius is spread across sylius/ui-bundle, sylius/admin-bundle, and sylius/shop-bundle; routing moved to attributes/PHP in newer versions, and Twig template paths changed. Build that map as a by-product of your normal work.

Gotchas and Tips

The headline gotcha: there is no upstream. Archived means no bug fixes, no CVE response, and no Symfony/PHP compatibility work. Every upgrade is yours. If this package is in your composer.json, it is a migration backlog item, not a dependency to maintain in place.

Cache is the #1 false alarm. Template overrides, routing YAML, and service definitions are all compiled. If a change "does nothing," run bin/console cache:clear (and in dev, check app/cache/dev was actually cleared — permissions on var//app/cache bite here too).

Asset changes need assets:install. Twig template edits are live in dev, but anything under Resources/public/ requires bin/console assets:install --symlink again. Symlinks are the usual culprit when CSS/JS goes stale.

Route names are load-bearing. Overriding a route by path but changing its name silently breaks every path('sylius_...') call in templates and controllers — you get 500s that look like missing routes. Always keep the name, change the path and _controller only. Verify with bin/console debug:router | grep <name>.

Override path recursion. Extending the exact template you are overriding creates infinite recursion or a blank page. Extend the layout or a parent partial instead.

Bundle registration order matters. SyliusWebBundle must load after SyliusResourceBundle and TwigBundle. Misordered bundles produce "service not found" errors at container compile time that read as if a service is missing entirely.

Container compile failures are opaque. When cache:clear fails after a change, run debug:container or lint:yaml app/config rather than reading the stack trace top-down — the real cause is usually one bad service argument three levels deep.

Twig debugging toolkit. debug:twig shows registered paths and extensions; use the dump() function in dev to inspect what a controller actually passed to a view. Most "template shows nothing" bugs are a missing variable name, not a template problem.

Doctrine mapping ownership is a boundary. The bundle's controllers assume Sylius core entities and their mappings. If you add your own entities touching the same tables, you now have two mapping sources and a migration-order problem. Keep your overrides read-mostly or go through the bundle's repositories — don't add parallel persistence.

PHP/Symfony constraint drift. This bundle's composer.json pins old Symfony components. Any attempt to bump Symfony or PHP in the host app will conflict. That conflict is your migration ticket — don't try to patch around it with --ignore-platform-reqs in production.

Session/CSRF semantics are old-style. If you are fronting this app with a newer service (or a separate API), authenticated state won't propagate cleanly. Test the auth flow end-to-end after any infrastructure change, not just the happy-path page render.

Extension points, ranked by safety:

1. Template override (lowest risk — presentational only)
2. Twig extension / view helper addition (low risk)
3. Route override keeping the name (medium — verify every path() caller)
4. Controller subclass (medium — you inherit the base's assumptions)
5. Service decoration (higher — depends on internal constructor signatures)
6. Editing or vendoring the bundle (last resort; pin the commit and treat it as first-party code)

When you migrate off: the mapping is not mechanical. Routing moves to PHP attributes or newer YAML conventions, template paths change namespace, and service IDs get reorganised across shop-bundle/admin-bundle/ui-bundle. Budget a real upgrade, run it behind feature flags on the routes you touch most, and delete sylius/web-bundle from the lock file in the same change — leaving it in as a "just in case" is how it survives another two years.