Sylius Order Association Bundle Laravel Package

Getting Started

This is a Sylius plugin, not a Laravel package. The v0.4.0 release only bumps compatibility to Sylius 0.19, so treat it as a maintenance release with the same public surface as v0.3.x — there are no new APIs to learn before you start.

1. Confirm your stack first. You need Sylius ~0.19 (Symfony 2.x era) and its PHP constraint. If you are on a modern Sylius (1.x) or a Laravel app, this package will not install cleanly — check composer.json for the sylius/sylius constraint before anything else.
2. Install with composer require <vendor>/<package>:^0.4 and register the bundle in app/AppKernel.php alongside the core Sylius bundles.
3. Look at these files first, in order: the bundle class (*Bundle.php), the DI extension in DependencyInjection/, Resources/config/services.yml, and any Resources/config/app/config.yml the README tells you to import. Sylius plugins almost always work by overriding resources, so the resource configuration is the real entry point.
4. First use case: declare the package's resource override (model, controller, form, or repository) in app/config/config.yml under sylius_* resource keys, clear the cache (app/console cache:clear), and run app/console doctrine:schema:update --dump-sql before applying. You should then see the package's behaviour through the existing Sylius admin or frontend route rather than a new route of its own.

Implementation Patterns

• Resource override, not inheritance. The idiomatic integration is to point a Sylius resource at the package's model/controller/form classes via config, keeping your app's classes as thin subclasses. This survives package updates better than copying templates or services.
• Service decoration / compiler passes. Where the package exposes services, decorate rather than replace, and use a compiler pass if you need to swap a definition conditionally. Register your pass in the bundle class, not in services.yml.
• Event listeners for behaviour. E-commerce flows (order lifecycle, checkout, cart) are best hooked via the Sylius event dispatcher. Subscribe to the relevant event in your app's service config and keep listeners side-effect-scoped.
• Template overrides live under app/Resources/<BundleName>/views/.... Mirror the package's path exactly; a wrong directory silently falls back to the vendor template.
• Test against a Sylius fixture app. Use the package's own test application or a minimal Sylius 0.19 install; PHPUnit tests that boot the full kernel catch container-compile errors that unit tests miss.

Gotchas and Tips

• This is Symfony/Sylius, not Laravel. There are no service providers, no Eloquent, no Artisan, no config/*.php merge. Do not try to wrap it in a Laravel app; the dependency chain is incompatible.
• Sylius 0.19 is pre-1.0 and old. Expect PHP 5.x-era code, deprecated Symfony APIs, and sparse documentation. Pin exact versions in composer.lock; a minor Sylius bump can break resource config keys.
• Resource config must exist before container compilation. If your override "does nothing", it is almost always a cache issue or a YAML key that was silently ignored. Run app/console debug:container --parameter=... and app/console cache:clear --no-warmup when in doubt.
• Doctrine mapping errors are the most common failure mode after a version bump — the release note says 0.19, so verify mapping XML/annotations against 0.19's resource loader rather than a newer one.
• Extension points to prefer: bundle class + DI extension for wiring, resource config for model/controller swaps, event listeners for runtime behaviour. Avoid editing vendor files; there is no patch layer here.
• No migration path is documented in this release. Because v0.4.0 is a compatibility-only bump, diff the package's Resources/config against v0.3.x before upgrading — that is where any silent config-key changes will show up.