Laravel Prices Laravel Package

Product Decisions This Supports

• Build vs. buy for money primitives. Prices, discounts, totals, and taxes are the kind of domain logic every commerce-adjacent product eventually writes. This package lets us buy that layer (integer minor-unit storage, currency-aware casting, formatting/parsing helpers) instead of funding a bespoke money value object — a decision that typically saves weeks of design review and an ongoing maintenance tail.
• Pricing and localization roadmap bets. Whether we can ship per-market pricing, multi-currency catalogs, or localized price display is partly a data-model decision. Adopting a currency-aware price type now keeps that door open cheaply; retrofitting currency semantics after launch is a migration project with customer-visible risk.
• Data-integrity posture. Storing monetary amounts as integers rather than floats is a correctness decision that is expensive to reverse once invoices, orders, or subscription records exist. This is a one-way-ish door worth making deliberately, early, and in writing.
• Scope boundaries for integrations. The package handles representation, formatting, and basic arithmetic — not FX conversion, tax calculation, or ledger-grade accounting. That clarifies where we must integrate third-party services (tax engine, payments provider, ERP) versus where we build.
• Reference use cases to evaluate against: product catalogs, carts and checkout, subscriptions and plan tiers, invoices and receipts, promotional pricing, regional price lists.
• Platform baseline (new in v2.0.0). The major version pins our minimum platform: Laravel 11+ and PHP 8.3+. That makes this a dependency decision and a platform-cadence decision — it should be sequenced with, not ahead of, the framework upgrade plan.

When to Consider This Package

Consider adopting when:

• We are on Laravel 11+ and PHP 8.3 or later (required by v2.0.0).
• The product stores or displays prices for customers: catalog, checkout, billing, invoicing.
• Multiple currencies are in scope today or credibly within 2–3 quarters.
• We want consistent rounding, formatting, and input parsing across web, API, and admin surfaces without each team reimplementing it.
• The team is small enough that a maintained, single-purpose dependency beats an internal money library.

Look elsewhere or defer when:

• We cannot leave Laravel 10 / PHP 8.2 yet. v2.0.0 drops both. Staying means pinning to the 1.6.x line with no upstream fixes — a real risk, not a neutral choice. Treat this as a forcing function to schedule the platform upgrade, and record the accepted risk if we don't.
• We need money semantics beyond representation: FX rate management, tax determination, multi-leg rounding strategies at scale, or double-entry ledger behavior. Those are separate products; this package is not one.
• The domain must be shared across non-Laravel services (e.g., a Go or Python pricing service). A PHP-coupled cast is then the wrong center of gravity; prefer a language-neutral money standard and an explicit serialization contract.
• We have already standardized on a money library with an existing conversion/driver layer. Introducing a second money representation is worse than the marginal ergonomics gained.
• We need precision or currency shapes the package doesn't model (high-precision or non-2-decimal currencies, crypto). Validate against our actual currency list before committing.

Upgrade note for v2.0.0: the release is a support-matrix change — adds Laravel 13 / PHP 8.5, drops Laravel 10 / PHP 8.2 — with no stated feature additions. Major-version bumps warrant a branch-level regression pass on price persistence, rounding, and display formatting even when the changelog implies no API movement.

How to Pitch It (Stakeholders)

To executives (one paragraph): We're standardizing how the product stores and displays money on a small, actively maintained open-source component. The business value is risk reduction, not features: it eliminates a class of rounding and currency bugs that show up as wrong charges, refund discrepancies, and support escalations, and it makes per-market pricing a configuration exercise rather than a rebuild. The cost is a single dependency and a version bump tied to framework work we already have planned. The main decision it forces is timing — the new 2.0 release requires Laravel 11+/PHP 8.3+, so we either align with our existing upgrade cadence or knowingly run an unsupported older line.

To engineering: Thin, single-purpose layer over Laravel's casting system; keeps monetary values as integers in the database and gives us typed, currency-aware values in application code. Adopting it removes an internal library from our maintenance burden and gives one consistent behavior for formatting and parsing. 2.0 is a platform-floor bump — verify our minimum Laravel/PHP targets, run the existing price-related tests against it in a branch, then roll it into the framework upgrade rather than as a standalone change.

The ask: approve adoption (or the 2.0 upgrade) and confirm the sequencing against the Laravel upgrade timeline; if we defer, explicitly accept the pinned-version risk on 1.6.x.