Laravel Number Converter Laravel Package

Getting Started

The 1.7.0 release is a compatibility-only bump: it widens the framework constraint to allow Laravel 11 and 12. There are no API changes, so anything written against 1.6.0 should keep working — but this is the version you must require if you're on a modern Laravel install.

1. Install with composer require hnhdigital-os/laravel-number-converter:^1.7. On Laravel 11/12 anything below 1.7.0 will fail dependency resolution, so pin ^1.7 explicitly rather than letting Composer pick the highest 1.6.x from a cache.
2. No manual service provider registration is needed — package discovery handles it. Confirm with php artisan about or php artisan package:discover if the facade alias doesn't resolve.
3. Start with the README to confirm the current facade alias and method names; the public surface has been stable across 1.x, but the docs are the source of truth for the spelling of convert() / toWords() style calls.
4. First use case: rendering a monetary amount in words for an invoice, quote, or cheque-style document. Something along the lines of NumberToWords::convert(1234.56) returning an English string, which you then pair with your own currency label.

If you're upgrading from 1.6.0, run the test suite on Laravel 11/12 before merging: the dependency change is the only delta, so any breakage will be in your own code, not the package's.

Implementation Patterns

Inject, don't call statically, in domain code. The facade is convenient in controllers and Blade, but injecting the underlying converter service into a value object or a MoneyToWords helper keeps your formatting testable and lets you swap locales per-tenant later.

Wrap it in one application-level helper. Rather than scattering converter calls, expose a single method such as Money::inWords($amount, $currency, $locale) that handles rounding, currency labels, and locale defaults. When you eventually need to swap the underlying library, you change one class instead of forty call sites.

Use it at the presentation edge. Convert at render time — a Blade component, an API resource, a PDF template — not in the database layer. Storing the words alongside the numeric value guarantees they drift apart the first time someone edits the amount.

Model accessors and API resources are a natural fit: an InvoiceResource can add a total_in_words key computed from $this->total_cents / 100. Keep the raw integer in the payload too; clients that need to do arithmetic shouldn't have to parse English.

Locale handling. Where the package supports multiple locales, drive the locale from the request or the document's own language field rather than app()->getLocale(), so a French invoice rendered by an English-speaking admin still reads correctly. Set locale explicitly per call and reset it afterwards if you mutate global state.

Testing. Assert on the words string for a handful of representative amounts (zero, a round hundred, a decimal, a large number, a negative), and assert your wrapper's rounding behaviour separately. Don't snapshot thousands of conversions — a few boundary cases catch nearly all regressions.

Bulk generation. For PDF batches or exports, resolve the converter once and reuse it; the work is CPU-bound string building, so it queues cleanly if you're generating hundreds of documents.

Gotchas and Tips

• The 1.7.0 change is the whole story. If you're on Laravel 11 or 12, your previous constraint was almost certainly the blocker — this release exists to unblock you. If you're on Laravel 10, staying on 1.6.0 is fine and 1.7.0 adds nothing.
• Floats are a trap. Passing 1234.56 directly invites 1234.5599999 style surprises. Convert from integer minor units ($cents / 100) and round explicitly before handing the value over, or pass integer amounts where the API allows.
• Rounding vs. truncation. Decide whether 1234.567 becomes "one thousand two hundred thirty-four and fifty-seven cents" or fifty-six; the package's behaviour should be verified with a test rather than assumed, and your wrapper should be the one making the decision.
• Locale availability. Not every language is covered, and missing locales may fall back silently to English. If locale matters to your output, add a test that asserts a non-English string, not just that a string was returned.
• Config caching. If you publish a config file, remember php artisan config:cache in deployment — a locale or format setting changed in .env after caching won't take effect until you re-cache.
• Negative and zero values. Cheque and invoice rendering cares about "zero" and "minus" phrasing. Test them; they're the cases that reach production unannounced.
• Large numbers. Very large inputs may hit an internal limit or produce awkward compound phrasing. If amounts can exceed millions, test the ceiling and consider falling back to digits plus a note.
• Keep the version loose but modern. Require ^1.7 so patch fixes flow in, but don't pin the framework constraint yourself — the package's own constraint is what needs to line up with your laravel/framework requirement.
• Upgrade hygiene. Because this is a constraint-only release, a green test run after composer update is sufficient validation. There's no migration, no config publish, and no deprecation to chase.