Ecommerce Bundle Laravel Package

Getting Started

Know what you are actually installing. libre-informatique/ecommerce-bundle is a Symfony 2 bridge bundle — glue between Libre Informatique's own bundles and Sylius components. It is not a standalone storefront engine and it is not a Laravel package. "Leveraging" it day-to-day only happens under two scenarios: (a) you are maintaining/inheriting a Symfony 2 app that already wires together librinfo + Sylius, or (b) you are mining it as a domain-model reference while building a catalog natively. Anything else is a porting project.

Minimal steps, in dependency order:

1. Read composer.json first, not the README. Look at three blocks: the symfony/* constraints (expect ~2.3–2.8), the sylius/* entry (component-level or the full sylius/sylius — this determines how much of Sylius you inherit), and the libre-informatique/* entries. That graph is the real API surface. If the constraints conflict with any modern package you already require, stop here.
2. Locate the *Bundle class and its Resources/config/. This is where service wiring, DI aliases, and routing/validation YAML live. Map each registered service to the Sylius or librinfo service it decorates or implements — the bundle's whole job is adaptation, so its value is the mapping layer, not bespoke logic.
3. List the Entity/ and Form/Type/ directories. These are your actual model and UI contracts: products, variants, orders, checkout form types. Read the entity associations before reading any service — the schema tells you what the system can and cannot represent.
4. Find the event subscribers. In Symfony 2 commerce, order state transitions and checkout steps are driven through the EventDispatcher. Identify which *Events:: constants are listened to; that is the workflow you will be maintaining or reimplementing.

First use case. Point the app at the catalog path (product CRUD with variant/attribute selection and a category assignment) and render it through the bundle's Twig templates. This exercises Doctrine mappings, form types, and the Twig layer simultaneously and is the fastest way to confirm the bundle boots and the DI config resolves. Do this in a throwaway environment first — it is the cheapest possible smoke test before any commitment.

If your target is Laravel, do not attempt install. Open Entity/Product.php, Entity/Variant.php, and the form types, write down the fields, relations, and validation rules, and treat that document as the spec for native Eloquent models. Budget it as a two-day research spike; delete the clone afterward.

Implementation Patterns

Pattern 1 — Legacy Symfony 2 maintenance (the only real integration). Register the bundle in AppKernel::registerBundles() in the correct order relative to the Sylius and librinfo bundles it bridges — ordering here is load-bearing because DI parameters are overridden by later bundles. Keep configuration in app/config/config.yml under the bundle's declared root key, and prefer overriding services via services.yml compiler passes over editing vendor code, so upgrades (such as they are) remain possible. Treat any local patch to the bundle's own Resources/config as a fork: track it in a patches/ directory with rationale in the commit message, because no upstream will ever merge it back.

Pattern 2 — Service decoration for custom business logic. The bundle's extensibility story is Symfony's decoration mechanism. To add pricing rules, tax logic, or inventory checks, implement your own service and decorate the bundle's existing service ID rather than subclassing entities. This keeps the Doctrine mapping untouched (schema churn on a legacy system is the highest-risk change you can make) and confines your custom code to a directory you can lift into a replacement system later.

Pattern 3 — Extract, don't import (Laravel target). Model the catalog as: Product → hasMany Variant; Variant → belongsToMany AttributeValue; Product → belongsToMany Category; Price and Inventory as separate tables keyed to Variant. Mirror the bundle's associations, then re-decide the behaviours: Eloquent has no identity map, so the Doctrine-style "load aggregate, mutate, flush" workflow does not translate. Use explicit service classes with database transactions and DTOs at the boundaries instead of letting models carry the workflow.

Pattern 4 — Repository adapter for a staged migration. If you must run both systems concurrently, define a narrow Laravel-side interface (CatalogRepository with findBySku, listForCategory, variantAvailability) and implement it twice: once against the Doctrine repository via a thin bridge, once against Eloquent. Consumers depend only on the interface, so the cut-over is a container binding change, not a code sweep. Keep the Doctrine-side implementation read-only — dual-write across two ORMs is where these migrations fail.

Pattern 5 — Checkout/order as an explicit state machine. The bundle's order workflow is event-driven. Whatever you build, encode order states as an explicit enum with guarded transitions rather than scattering if ($order->getState() === …) checks. This is the single highest-value lesson to carry forward, because a legacy event-driven workflow with no visible state table is the hardest thing to reason about when bugs surface.

Integration tips that apply to every pattern:

• Write a characterization test suite against the catalog and order paths before changing anything on a legacy system. You need a definition of "still works" that does not depend on reading the bundle's internals.
• Pin every transitive dependency with composer.lock committed and never run a blanket composer update on this codebase.
• Keep a docs/domain.md capturing the entity model and state transitions; this is the artifact that survives when the bundle does not.

Gotchas and Tips

• The license blocks you before the code does. NOASSERTION means redistribution is unclear. Do not copy entity or service code into an internal Laravel repo until legal has signed off in writing — writing an original implementation from a read of the schema is a different (and safer) act than copying files. Keep the two activities separate and documented.
• Do not attempt autoload coexistence. A Symfony 2 bundle alongside a modern Laravel app produces confusing boot/container/autoload failures, not a clean install error. If both must exist, run them as separate applications behind a network boundary.
• Doctrine ≠ Eloquent, and the gap bites in four places: no identity map (the same row loaded twice is two objects in Eloquent — deduplicate deliberately); N+1 emerges from lazy relation access in both but is easier to spot and eager-load in Eloquent via with(); flush semantics are transactional batches, not per-save; and UnitOfWork change tracking has no equivalent. Any timing or correctness assumption inherited from the Doctrine side is unvalidated.
• Event dispatcher semantics differ. Symfony 2 listeners with priorities and stopPropagation do not map onto Laravel's events. If you are porting workflow logic, re-read each listener as an explicit step in a pipeline rather than trying to preserve the event graph.
• NOASSERTION also means no security process. Assume every transitive dependency carries known CVEs with no patch path. Run a scanner on day one and record the baseline; if the list is long, that is your argument for replacement.
• Zero dependents is a correctness signal, not just a popularity one. Nobody has exercised the pricing, variant, and inventory edge cases in production and reported the bugs. Treat those code paths as unvalidated and write your own tests around them before trusting the output.
• Config quirks live in extension ordering. When a service unexpectedly resolves to the wrong implementation, the cause is almost always bundle registration order or a DI parameter overridden by a later bundle. Dump the container (debug:container --show-private in that era) and compare against the vendor services.yml rather than guessing.
• Extension points, ranked by safety: service decoration > event subscriber > overriding a form type > overriding a Twig template > editing an entity mapping. Stay as high on that list as the requirement allows; entity mapping changes force schema migrations that you will own forever.
• Budget ramp-up honestly. Multi-week for a competent engineer to be productive, and the knowledge does not transfer to your Laravel codebase. If the requirement is "a product catalog," a native build is measured in days and produces code your team already knows how to maintain.
• If you take one thing from the repo, take the schema. The entity associations are the genuinely reusable asset. Everything else — services, forms, templates, workflow wiring — is locked to a framework generation that reached end of life in 2019 and is cheaper to rewrite than to port.