Money Bundle Laravel Package

Product Decisions This Supports

• Monetary correctness in billing, pricing, and payouts. The underlying moneyphp/money library models amounts as integer minor units plus a currency, which removes the class of rounding defects that appear when prices, taxes, discounts, and refunds are held as floats. If your roadmap includes subscriptions, multi-currency catalogs, invoicing, or marketplace payouts, this is a foundational correctness decision rather than a feature.
• Build vs. buy for "money handling." Buying the domain library is close to a no-brainer (it is the de facto PHP money value-object library, MIT, stable, widely depended upon). This bundle is a much smaller decision: it is glue that wires that library into Symfony's container, forms, and validation. Treat it as buy the library, optionally adopt the bundle.
• Framework-conditional roadmap item. This is a Symfony bundle, not a Laravel package. For a Laravel codebase, the relevant decision is "adopt moneyphp/money (or brick/money) directly and write a thin service provider," not "adopt this bundle." Scoping work here should reflect that split.
• Multi-currency scope. Adopting the money abstraction early is cheap; retrofitting it after prices are stored as DECIMAL/FLOAT columns and arithmetic is scattered across models is expensive. This supports a "do it before scale" sequencing decision.
• Architecture and team conventions. Standardizing on value objects for money creates a consistent domain vocabulary (Money, Currency, allocation) that reduces review friction and makes financial logic testable without a database.
• Explicitly out of scope for this package: FX rate sourcing, tax engines, price formatting/localization, and persistence. Those remain separate build/buy decisions — do not let adoption of this bundle be mistaken for solving them.

When to Consider This Package

Adopt when:

• You are on Symfony (the bundle's only supported context) and already use, or intend to use, moneyphp/money.
• You want to remove repetitive container wiring, form-type mapping, and validation boilerplate for monetary inputs — the bundle's real value is developer time, not functionality.
• Your monetary requirements are conventional: fixed-price catalogs, cart totals, invoices, refunds, allocations/splits of an amount.
• You can tolerate a small third-party surface: ~29 stars means a very thin community. That is acceptable here only because the bundle is small and the substantive logic lives in the upstream library. Mitigate with a version pin, a read of the source (it is small enough to audit in an afternoon), and a willingness to vendor or replace it.

Look elsewhere (or skip the bundle) when:

• You are on Laravel, plain PHP, or another framework — use moneyphp/money or brick/money directly.
• You need exchange rates, currency conversion services, or historical FX — neither this bundle nor the upstream library provides them.
• You need locale-aware formatting — use intl/NumberFormatter; the money library is deliberately format-agnostic.
• You need persistence out of the box — Doctrine types/column mapping are your responsibility; budget for it.
• You need advanced allocation with remainder policies or aggressive decimal math — evaluate brick/money against your requirements first; it is more actively maintained and has richer allocation semantics.
• Your financial domain is regulated or audit-critical and your procurement process requires a maintained vendor with a support path — 29 stars and a single maintainer is a supply-chain conversation, not a technical one.

Maintenance signal: a release dated 2025-12-15 indicates the project is not abandoned. Confirm the release is substantive rather than a dependency bump, and check open-issue responsiveness before committing.

How to Pitch It (Stakeholders)

To executives (one paragraph): We are standardizing how the product represents and calculates money so that pricing, tax, discounts, refunds, and payouts cannot silently drift by cents — a defect class that is cheap to prevent now and expensive to unwind once it reaches customer invoices and financial reporting. The capability comes from a mature, MIT-licensed PHP library; the specific Symfony integration layer is small, free, and easily replaced. Cost is effectively engineering hours only, with no licensing or vendor commitment, and the work is reversible.

To engineering: This is a thin Symfony integration over moneyphp/money — DI configuration, form types, validators. Expect to write your own persistence mapping (Doctrine types) and formatting layer, and to source FX rates separately; the bundle does not do either. The upstream library is the real dependency and is a safe bet. The bundle itself is low-adoption (~29 stars, single maintainer), so pin the version, read the source before adopting (it is small), and keep the integration behind a thin internal interface so we can drop it for direct library usage or brick/money without touching domain code. If we are a Laravel shop, skip the bundle and integrate the library directly.

To product/finance stakeholders: Expect no user-visible change from this work. The deliverable is that multi-currency prices, splits, and refunds are computed in integer minor units and are auditable and unit-testable — which is what lets us commit to multi-currency pricing on the roadmap without a rewrite of the pricing model later.