vanilo/adjustments
Vanilo Adjustments provides a flexible adjustment system for Laravel e-commerce apps, letting you apply promotions, discounts, taxes, and other price modifications to orders and line items through a consistent, extensible API.
Architecture fit. vanilo/adjustments is a domain module in the Vanilo e-commerce suite for Laravel, built on the Concord module loader (Konekt). It provides the abstraction for attaching monetary adjustments — discounts, promotions, taxes, shipping, fees — to any "adjustable" Eloquent model via a polymorphic Adjustment relation. The design is a clean, narrow seam: an Adjustable contract plus trait on the domain side, an Adjustment model and typed adjustment collection on the other. This is exactly the kind of package a TPM wants when the product needs a uniform, auditable representation of why an order total differs from the sum of line prices, without each team inventing its own discount_amount columns. Fit is strongest inside a Vanilo-based storefront or order pipeline; outside Vanilo it is usable but the Concord conventions and the wider suite (cart, order, taxes, payment) are where its value compounds.
Integration feasibility. Composer-installable, MIT-licensed, service-provider registered. Realistic effort is low for the install and moderate for correct modeling: add the package, publish/run the adjustments migration, implement Adjustable on the models that carry pricing (cart line, order line, order, shipment), and register interface bindings per Concord config. The hard part is not code — it is agreeing on the adjustment taxonomy (type, description, included-in-price flag, origin) and the rounding policy before data accumulates.
Technical risk. The signal here is thin: 5 stars, 0 dependents, a composite score of 0.155. That does not mean poor quality — it means low independent adoption. The practical read is that this package is almost always consumed transitively through vanilo/order or vanilo/cart rather than chosen on its own merits, so its health is coupled to the parent suite's release cadence and to a small maintainer group. Specific risks: version lockstep with Concord and Laravel major versions; a single-maintainer bus factor; sparse public issue history (fewer known-issue warnings, and fewer known fixes); and schema/API drift across minor releases of the suite. Mitigations are cheap — pin exact versions, wrap the package behind a thin internal service, and keep the migration reversible.
Key questions for the maintainer/vendor.
vanilo/taxes and shipping modules?Stack fit. Laravel 9–11, PHP 8.1+, MySQL/Postgres, standard Eloquent. Concord's module registration is the only non-obvious convention; teams already running any Vanilo module will find it familiar. If the storefront is not Vanilo-based, adopt this package only if you are also willing to adopt Concord's service-provider and binding patterns — otherwise a bespoke adjustments table is lower friction for equivalent value.
Migration path. (1) Inventory existing price-modifier columns and logic — coupon codes, manual discounts, tax lines, shipping fees scattered across order and cart tables. (2) Install and migrate the adjustments table. (3) Implement Adjustable on the target models. (4) Dual-write: continue populating legacy columns while also writing adjustments, with a reconciliation job asserting sum(adjustments) == legacy_total per order. (5) Cut reads over to adjustments behind a feature flag. (6) Backfill historical orders only if reporting requires it — otherwise start the ledger at cutover and freeze legacy data. (7) Drop legacy columns after a full billing cycle of clean reconciliation.
Compatibility. Pin the package, Concord, and the parent Vanilo modules to a tested matrix; these move together. Verify the Adjustable contract signature against your models before writing traits — a mismatch surfaces at container resolution, not at compile time. Check that any custom adjustment types survive the enum/class-map mechanism used in your pinned version.
Sequencing. Week 1: spike on a single cart line — apply one promotion and one tax adjustment, assert totals. Week 2: taxonomy and rounding policy sign-off with finance/product. Weeks 3–5: order-line and order-level integration behind a flag, dual-write reconciliation. Weeks 6–7: reporting/export reads, admin visibility of adjustment breakdown. Week 8: cutover and legacy column retirement. Defer multi-currency and returns/refund adjustment semantics to a second phase unless launch-blocking.
Maintenance. Expect to track the parent suite's release cadence rather than this package's alone. Budget a small but real recurring cost: quarterly dependency review, monthly security patch window, and a named owner. Because independent adoption is low, regression coverage must be internal — the community will not surface your edge cases. Keep a fork-or-vendor contingency; the code surface is small enough that a fork is a days-not-months operation.
Support. Community-only, GitHub issues, no SLA, no commercial backing visible at the package level. Escalation path in practice is the Vanilo maintainer and paid support around the broader framework. Treat this as "supported by the suite, not by the module."
Scaling. The adjustments table grows linearly with order volume times adjustments-per-line — typically 1–5 rows per line, so plan indexing on (adjustable_type, adjustable_id) and on order-date for reporting. Totals are computed in PHP over hydrated collections; at high line counts this becomes an N+1 and memory concern, so eager-load adjustments and consider a denormalized cached total on the order. Reporting queries should hit a read model or warehouse, not the transactional adjustments table.
Failure modes to instrument. Rounding drift between adjustment sum and stored order total (alert on any order where they diverge by more than one minor unit). Orphaned adjustments after line deletion. Double application of the same promotion on retry or duplicate webhook. Currency mismatch between adjustment and parent order. Silent no-op when the Adjustable trait is missing on a newly added model. Version skew after a partial composer update of the suite.
Ramp-up. A mid-level Laravel developer is productive on the happy path in a day; full fluency — Concord bindings, adjustment taxonomy, rounding semantics, and the interaction with taxes and shipping modules — is roughly one to two weeks. The main onboarding artifact is not this package's README but a written internal policy on adjustment types, immutability, and correction patterns, because that policy, not the code, determines whether the ledger stays trustworthy.
How can I help you explore Laravel packages today?