Terbilang Laravel Package

Product Decisions This Supports

• Customer-facing document generation: the package's core job — spelling out numbers and dates in words ("terbilang") — is a hard requirement for invoices, receipts, kuitansi, payroll slips, contracts, purchase orders and payment confirmations in the Indonesian market, where an amount-in-words line is often expected on financial documents. This release directly protects that output quality.
• Localization roadmap: with en/id/pt coverage now explicitly tested, this supports decisions to ship multi-locale document templates without building per-locale number-spelling logic in-house.
• Build vs. buy: a viable "buy" (adopt) answer for a recurring, deceptively fiddly problem. Spelling rules, meridiem labels, month names, abbreviation forms and Roman numerals are all edge-case-heavy; this release's bug list (English "fourty", Indonesian "Nopember", Portuguese abbreviation key, negative-number double spaces) is exactly the class of defect an in-house helper accumulates silently.
• Relative-time UX: DistanceDate fixes reduce to "N hours ago"-style strings that were previously dropping or misplacing hour/minute components — relevant to activity feeds, notification lists and support-ticket timelines.
• Upgrade decision (2.1.1): a bug-fix release with two behavior changes to plan for, not a drop-in no-op. It is worth scheduling, but it is a patch release, so it does not by itself justify roadmap re-prioritization. The 34 → 271 test increase (with previously zero-coverage DistanceDate) is the strongest signal here: it converts this from "plausible but unverified" to "safe to depend on for revenue-adjacent documents."

When to Consider This Package

Adopt when:

• You are on Laravel and need number-to-words and/or spelled-out dates for Indonesian, English or Portuguese — especially amount-in-words on invoices, receipts, payslips or contracts.
• You need the auxiliary features: large-number abbreviation, Roman numerals, negative/decimal handling, or human-readable distance dates.
• You want a small, single-purpose dependency rather than a full i18n/formatting stack, and can pin a version.
• You generate documents in tests or snapshots where deterministic, locale-correct strings matter.

Look elsewhere (or wrap/extend) when:

• You need locales beyond en/id/pt — this is a three-locale package, not a general i18n solution; ICU/CLDR-backed intl (NumberFormatter::SPELLOUT) covers far more languages.
• You need currency-aware formatting, grouping, symbol placement and rounding as first-class behavior — this library spells numbers; it does not model money.
• You require legally certified numeral-to-words output for a regulated jurisdiction, where grammar and phrasing must be formally validated per locale.
• You need locale-specific grammar beyond straightforward spelling (gendered/declined forms, complex pluralization) — the fixed translation key set will not flex.
• You cannot tolerate a small dependency with a single maintainer and no long-term support commitment; treat it as vet-and-pin rather than set-and-forget.

Upgrade notes for 2.1.1 (PM-relevant):

• The config key rename terbilang.period.show.* → terbilang.distance.show.* means previously published config files silently stop controlling distance output. Republish/merge config as part of the upgrade, and plan a verification pass on any screen using distance dates.
• Roman now throws InvalidNumber outside 1–3999 instead of returning "". Callers relying on empty-string behavior need try/catch or pre-validation — this is a latent crash risk on user-supplied input, but also the correct behavior (fail loudly rather than render a blank field on a document).
• Translation typo fixes ("fourty" → "forty", "Nopember" → "November", Portuguese short → large-number) will change output strings — expect snapshot/golden-file tests to fail until updated, and check any stored/cached rendered documents.
• LargeNumber no longer crashes on zero/negative input, and negative numbers no longer render with a double space — low-risk improvements.

How to Pitch It (Stakeholders)

To executives: This is a small, low-cost library that produces the spelled-out numbers and dates on our customer documents. The new release is a quality release, not a feature release: it fixes several correctness bugs that could have put wrong words on customer-facing output — a misspelled "forty" in English, "Nopember" instead of "November" in Indonesian, a broken Portuguese abbreviation key, and negative/zero amounts that could crash or render badly. Critically, the automated test suite went from 34 to 271 tests, including a component (DistanceDate) that previously had none. That is the difference between "we hope the numbers are right" and "we can prove they are." Recommendation: adopt and schedule the upgrade in a normal maintenance window; no product deadline pressure, but do not skip the two migration steps.

To engineering: Patch-level upgrade with two behavior changes to handle explicitly. (1) The distance-date config namespace moved from terbilang.period.show.* to terbilang.distance.show.* — republish/merge the config and verify any distance-date rendering, otherwise settings are silently ignored. (2) Roman now throws InvalidNumber for values outside 1–3999 rather than returning an empty string — wrap or pre-validate anywhere user input reaches it. Also expect snapshot tests to shift due to translation typo fixes, and add regression coverage around amount-in-words output on invoices/receipts since that is the highest-blast-radius surface. No new dependencies, no deprecations announced.