Master Product Laravel Package

Technical Evaluation

Architecture fit. vanilo/master-product is not a standalone library; it is a module inside the Vanilo e-commerce suite for Laravel, built on the Concorde module system (contracts + service providers + registerable morph maps). It implements the "configurable/master product" pattern: a parent record owns shared merchandising data (name, description, media, properties) while child products represent the purchasable SKUs that inherit and selectively override those values. If our storefront requires size/color/configurable variants, this is exactly the domain model we would otherwise design from scratch. The catch is that it only makes sense on top of vanilo/product, vanilo/channel, vanilo/pricing, and the media/property modules — it is an additive layer, not an independent capability. Architecture fit is therefore high only if we are willing to adopt Vanilo's product data model wholesale; it is near-zero as a bolt-on to a bespoke catalog schema.

Integration feasibility. Composer-installable, MIT-licensed, no proprietary gating. The mechanics are straightforward: require the package, register the Concorde module, run migrations (expect a master-product table plus a foreign key from the variants/products table), and swap the bound product contract for Vanilo's. The real effort is not installation — it is retrofitting our existing catalog into Vanilo's product/channel/pricing abstractions, and then expressing variant inheritance on top. For a greenfield Laravel build this is a few days of work; for an existing production catalog it is a data-migration and model-reconciliation project.

Technical risk.

• Popularity signal is misleading in both directions. 2 stars and 0 dependents are artifacts of a read-only monorepo subtree split — usage is attributed to vanilo/framework, not this repo. But the same fact means this repo generates little independent issue traffic, so defect discovery will surface in the parent project.
• Vendor concentration. Vanilo is effectively a small-team (Concorde/Attila Fulop) ecosystem. Bus factor and long-term roadmap continuity are the dominant strategic risks, not code quality.
• Version pinning. Sub-packages track Vanilo majors and Laravel minors tightly. A Laravel upgrade can be gated on a Vanilo release, and this module is one of the less-trafficked ones.
• Inheritance semantics are the crux. How nulls, prices, and media resolve from master to variant is where behavior surprises appear. This must be validated against our merchandising rules before commitment.

Key questions.

1. Which Vanilo major are we targeting, and what Laravel/PHP versions does it pin? Is there an upgrade path from our current Laravel version?
2. Does the inheritance model treat a null variant attribute as "inherit" or "explicitly empty"? Does that match our pricing and media rules?
3. Are variants first-class purchasable products (own SKU, stock, price) in cart/checkout, or does the master participate in ordering?
4. What is the contract surface we must implement or override (product contract, master-product contract, variant resolver)?
5. What is the deletion/archival behavior when a master is removed while variants exist?
6. Who maintains this module upstream, and what is the release cadence relative to vanilo/framework?

Integration Approach

Stack fit. Native fit for a Laravel monolith or modular monolith already comfortable with service providers and contract binding. The package assumes Eloquent, Laravel migrations, and the Concorde module registry; there is no framework-agnostic path. Adjacent concerns — cart, checkout, orders, admin — are separate Vanilo modules, so a full commerce build implies adopting the suite rather than this package alone.

Migration path. Treat this as a catalog re-platform, not a package install:

1. Stand up vanilo/framework + vanilo/product + vanilo/channel and confirm the base product lifecycle works against a staging catalog.
2. Add master-product, run migrations, and model a representative product family (e.g., a 2-axis variant matrix) end to end.
3. Build an ETL from the existing catalog schema into Vanilo products, mapping the old "parent/child" concept onto master + variants. Freeze the legacy write path during cutover.
4. Only then expose variant resolution to storefront and search.

If the catalog is small or the variant requirement is shallow (single-axis, price-identical), the honest recommendation is to model variants directly on the existing product table and skip Vanilo entirely — the module's value scales with variant complexity.

Compatibility. Verify the Composer constraint matrix up front (vanilo/master-product ↔ vanilo/product ↔ vanilo/framework ↔ laravel/framework ↔ PHP). Because these are lockstep-versioned, pin the whole Vanilo set to a single release train and upgrade them together; partial upgrades will not resolve. Also confirm compatibility with any existing packages that decorate the Product model — morph maps and contract overrides are the usual collision point.

Sequencing. Foundation modules → master-product → admin/UI tooling → storefront variant resolution → cart/checkout integration. Do not parallelize catalog migration with checkout work; the variant identity contract (which SKU enters the cart) must be settled before checkout is touched.

Operational Impact

Maintenance. Low day-to-day surface if we stay on the paved path — the module is thin and the codebase is small enough to audit fully. The recurring cost is upgrade coordination: we inherit Vanilo's release cadence and cannot upgrade Laravel independently of it. Budget for a paired-upgrade ritual each Laravel minor. Vendor-maintenance risk is real but mitigated by MIT licensing and the small, readable codebase — a fork-and-own exit is credible.

Support. No commercial SLA implied by the package. Support flows through the Vanilo GitHub org and documentation site, with response times typical of a small open-source project. For a revenue-bearing storefront, that means we own tier-1 and tier-2 support internally and should designate one engineer as the Vanilo owner with read access to the upstream source. Contractual support, if required, must be sourced separately from the vendor.

Scaling. Two hotspots to watch:

• Inheritance resolution. Rendering a category listing of masters requires resolving overridden attributes per variant. If the resolver lazy-loads variants or media, N+1 queries will appear at catalog scale. Enforce eager-loading conventions and cache resolved variant payloads.
• Variant cardinality. Large matrices (3+ axes) inflate row counts and admin payloads. Validate against the largest realistic family before committing.

Read paths dominate; write paths are admin-only and will not be the constraint.

Failure modes.

• Orphaned or empty masters — a master with zero variants is purchasable-looking but unbuyable; needs a validation guard and an admin-level health check.
• Delete/archive cascade — removing a master while variants reference it; verify FK behavior and whether it is restrict or cascade, and align with merchandising intent.
• Inheritance ambiguity — a variant with a null price silently inheriting a master price can ship wrong prices to the storefront. This is the highest-severity failure mode and warrants explicit tests plus a data-quality report.
• Stale caches — resolved master/variant payloads cached at the edge will not invalidate on master edits unless wired to model events.
• Upgrade deadlock — a security patch in Laravel blocked by a lagging Vanilo release; requires a documented fork/mitigation play.

Ramp-up. Expect roughly one to two weeks for a mid-level Laravel engineer to become productive: the Eloquent and service-provider patterns are familiar, but Concorde's module registry, contract-first model binding, and morph maps are project-specific knowledge. Add focused onboarding on the inheritance resolver — it is the piece most likely to be misunderstood and the piece with the worst failure characteristics. Document the variant identity rule (what constitutes a purchasable SKU) as an architectural decision record; it is the single concept every downstream team will otherwise re-litigate.