Promotion Laravel Package

Technical Evaluation

Architecture fit. vanilo/promotion is not a standalone promotion library — it is a sub-package of the Vanilo e-commerce suite for Laravel. It is written contract-first against vanilo/contracts and assumes the Vanilo object model (Cart, CartItem, Order, Product, checkout flow). It will not drop into an arbitrary Laravel application; adopting it means committing to Vanilo as the commerce backbone.

Integration feasibility. Composer-installable with Laravel service-provider auto-discovery and package migrations loaded by the service provider. The real integration surface is the contracts layer: you bind or implement PromotionType, eligibility/condition logic, and coupon semantics through the container. Feasible and idiomatic — but only on a Vanilo stack, and only when the vanilo/* versions are pinned as a matched set.

Technical risk. The raw signals are weak: 1 star, 0 dependents, composite score 0.105. That is expected for a framework sub-package — adoption credit accrues to the monorepo, not the module — so the number is a misleading quality proxy. The real risks are (a) ecosystem dependency: package health tracks Vanilo's release cadence and major-version churn; (b) contract sprawl: understanding behavior requires reading across contracts, cart, and order repos; (c) business logic drift: the interesting rules (stacking, priority, eligibility) are exactly what you implement yourself, so the package gives you scaffolding, not a finished discount engine.

Key questions. Which Vanilo and Laravel versions are we locked to, and what is the support window? Does out-of-the-box promotion coverage match our needs (stacking/priority, tiered discounts, BOGO, bundle pricing) or will we build custom PromotionType implementations? What are the coupon semantics — usage caps, per-customer limits, validity windows, concurrency safety? Is there a documented upgrade path between Vanilo majors? What is the demonstrated release cadence and maintainer activity for the overall suite?

Integration Approach

Stack fit. Strong fit if we are already on Laravel + Vanilo; poor fit otherwise, because adopting this module pulls in cart, checkout, order, and product models. Treat it as a framework commitment, not a library addition.

Migration path. Build a feature-parity matrix against the current discount engine before touching code: supported promotion types, coupon rules, priority/stacking order, and the exact point of evaluation (cart mutation vs. checkout vs. order placement). Plan a dual-run window with shadow evaluation against historical orders to catch silent mismatches.

Compatibility. Verify Laravel/PHP version support and the vanilo/contracts version pin. Confirm package migrations do not collide with existing cart/order tables, and that migration ordering is stable across modules.

Sequencing.

1. Pin the entire vanilo/* set to a mutually compatible release and freeze it for the project.
2. Stand up promotion tables in a staging database; validate migrations and rollback behavior.
3. Introduce an internal promotion service that wraps the contracts — all business rules live behind that seam, not in controllers or views.
4. Implement custom PromotionType and condition classes for anything the module does not cover natively.
5. Run parity tests against current behavior, including edge cases (expired coupons, exhausted limits, empty carts).
6. Canary a single low-risk campaign, then roll out.

Operational Impact

Maintenance. Maintenance cost is really Vanilo maintenance cost. Upgrades are coordinated events across the module set; upgrading promotion in isolation is risky. Contract-first design means new interface methods land as required implementations in our code, so every major upgrade has an integration tax.

Support. MIT-licensed OSS with no vendor SLA. Upstream fixes may be slow; assume we may need to fork or patch. Internal ownership of the contract bindings and custom promotion types must be explicit and staffed — that code is where the business value lives and it is our code, not the community's.

Scaling. Promotion evaluation runs during cart operations and potentially at checkout. Watch for N+1 eligibility checks across CartItems, and index coupon lookups (code with a uniqueness constraint). Cache promotion definitions for read-heavy evaluation and invalidate on admin updates. Load-test rule evaluation specifically during simulated flash-sale traffic.

Failure modes. Promotions silently not applying due to eligibility gaps; coupon double-redemption under concurrency (needs DB-level uniqueness and row locking, not application-level checks); stale cached promotion definitions after admin edits; migration drift when modules are at mismatched versions; and business logic leaking out of the contract seam, which makes future upgrades brittle.

Ramp-up. Moderate for a Laravel-fluent team. The unfamiliar part is the contract-first pattern — reading interfaces in vanilo/contracts before implementing, rather than gluing package facades. Budget onboarding time for the Vanilo cart/order model, not for the promotion module itself. Given the low external adoption signal, do not plan to hire existing expertise; plan to train internally and document the contract bindings as a first-class internal artifact.

On the score. The 0.105 composite against a 37.27 opportunity score reads as "low observed adoption, moderate category upside." That is consistent with a sub-package inheriting the framework's relevance rather than demonstrating its own — worth a spike to validate the parent project's activity before committing.