Order Cart Bundle Laravel Package

Getting Started

tourze/order-cart-bundle is a domain package: it gives you cart/order entities plus the services that move a cart through checkout. It is not a turnkey storefront — expect to wire your own controllers, views, and payment handling around it.

1. composer require tourze/order-cart-bundle (pin to 1.0.1; see Gotchas about the changelog).
2. Read src/ in this order: the entity/model directory (Cart, CartItem, Order, OrderItem), then the service/repository classes, then the bundle/DIC extension. Those three layers tell you the whole contract in about twenty minutes.
3. Check whether a bundle config file is shipped (config/ or a DependencyInjection/Configuration.php). Copy any defaults into your own config rather than editing vendor files.
4. Check the persistence layer. If it ships Doctrine XML/YAML mappings you will either inherit them via a mapped superclass or need to register your own entity mappings — decide this before you write a migration.
5. First use case: create a cart, add two items, compute a total, then convert to an order in a database transaction. Do that as a throwaway artisan/tinker script before touching HTTP. If those four steps work, integration is straightforward.

If you are on Laravel, verify the service provider is auto-discovered (extra.laravel in the package's composer.json). If it is a Symfony-style bundle without a Laravel bridge, you will add the provider manually to bootstrap/providers.php.

Implementation Patterns

Cart creation and lifecycle. Treat the cart as a short-lived aggregate keyed to a session or user. A common pattern is a single CartService::getOrCreateFor($user) called from middleware, so controllers never construct carts directly. Keep the "active cart" lookup in one place — duplicating it is how you end up with two carts per user.

Line items. Add items through the service, not by appending to the collection on the entity. The service is where quantity merging (same SKU added twice) and re-validation of availability usually live. Never trust a quantity posted from the client without re-checking it server-side.

Money. Compute totals through the package's total/calculator service rather than summing in your controller. If you add discounts or tax, do it as a wrapper around the package's calculator or as an event listener, so the raw subtotal stays available for display and audit.

Checkout as a transactional unit. The cart-to-order conversion should be one DB::transaction(): re-read the cart under a lock, snapshot prices and product names into order items, decrement stock or reserve inventory, then mark the cart consumed. Order items must capture the price at time of purchase; never join back to the product's current price to render an old order.

Idempotent conversion. Guard against double submission: check whether the cart is already converted (status column or an order_id back-reference) before creating anything. This matters more than any other pattern here because payment retries are normal.

Extension points. Before subclassing, look for events and interfaces — the bundle typically emits something around cart mutation and checkout. Listeners are much cheaper to maintain across upgrades than an overridden entity.

Testing. Write a test that builds a cart in memory, applies a discount, and asserts the final total. It is the fastest regression net you can build for a domain package like this, and it survives vendor updates.

Gotchas and Tips

• The 1.0.1 release notes are a bare compare link. There is no changelog describing what changed between 1.0.0 and 1.0.1. Diff the two tags locally (composer diff or Git compare) or read the commit log before upgrading a production app. Pin exact versions in composer.json — "tourze/order-cart-bundle": "1.0.1" — rather than allowing ^1.0 to drift silently.
• Naming suggests a bundle, not a Laravel package. Confirm the integration path early. If there is no laravel service provider entry, you will be doing manual container bindings and may need Doctrine rather than Eloquent. That is a decision that affects everything downstream, so settle it first.
• Mapping inheritance is the classic failure point. If your Cart extends the package's entity and you forget to register the mapping or the id generator, you get an empty table and a confusing "no such column" error at runtime, not at boot.
• Currency assumptions. Check whether amounts are stored as integers (minor units) or decimal strings before you display anything. Mixing the two produces a 100× pricing bug that shows up only at checkout.
• Floating point totals. Never let a float touch a persisted total. If the package hands you float, cast to a string/integer representation at the boundary and keep it that way.
• Stale carts. Add a cleanup command early. Abandoned carts accumulate quickly, and if they hold stock reservations, they will block real sales.
• Concurrency. Two tabs adding to the same cart will interleave writes. If the cart is a normalized set of rows with a version column, honor it; if not, serialize mutations with a pessimistic lock in your service wrapper rather than patching the vendor entity.
• Debugging total mismatches. Log the intermediate values — subtotal, discount, shipping, tax — as a single structured line per calculation. When a customer says "that's wrong," the diff of those four numbers tells you instantly whether the bug is yours or the package's.
• Watch for a missing CHANGELOG.md. With no per-release notes, treat every patch as potentially behavior-affecting and run your pricing test suite after each bump.