Laravel Num Laravel Package

Getting Started

• Install with composer require ageekdev/laravel-num. As of v2.0.0 this requires PHP 8.2+ and Laravel 11, 12, or 13 — if you are still on Laravel 9/10 or PHP < 8.2, stay pinned to the 1.4.x line until you upgrade the host app.
• The service provider is auto-discovered, so there is no manual registration step. Publish the config on first install so locale/formatting defaults are explicit in your repo:

  php artisan vendor:publish --tag=laravel-num-config
  

• First use case: converting numbers to their written form (invoices, legal documents, cheque printing, receipt totals) or formatting ordinals/casual number output. The most common call is a static/facade-style helper such as Num::toWords($amount) inside a Blade view or a PDF generator.
• Start by reading the published config/num.php — it is where default locale and formatting behaviour live, and tweaking it is the fastest way to get sane output for a non-English app.

Implementation Patterns

• Formatting at the boundary. Keep raw numeric values in your models/DB (int, decimal) and only convert to words/ordinal text at the presentation layer (Blade, API transformers, PDF/email builders). This keeps the package out of your domain logic and makes it trivial to swap formats later.
• Blade + API resources. Wrap the helper in a small custom Blade component (e.g. <x-num-words :value="$invoice->total" />) so views do not depend on the package directly. In JSON responses, call the helper inside an Attribute on your resource rather than a global helper.
• Multi-currency invoices. Combine the number-to-words output with the currency code and locale from the config so the same helper produces correct wording for en, fr, etc. Pass the locale explicitly per call when a single request may produce multiple jurisdictions.
• Queued documents. When generating PDFs in jobs, be aware that locale may not be the request locale inside a queue worker — set app()->setLocale($invoice->locale) before invoking the helper, or pass the locale argument directly.
• Upgrade pattern for v2. Because v2.0.0 only bumps framework/PHP constraints, the upgrade is usually composer update plus bumping "laravel/framework" in composer.json. The main work is in your CI matrix: drop PHP 8.1 and Laravel 9/10 jobs, add 8.2+ and 11/12/13.
• Testing. In feature tests assert on the final string, not on internals; use Num::toWords(1234) style calls in unit tests with the config cached, and add a smoke test that hits your invoice endpoint to catch locale regressions after config changes.

Gotchas and Tips

• v2.0.0 is a breaking release — dropping Laravel 9, 10 (the changelog double-lists "10"; the practical effect is Laravel 9/10/11-era support is narrowed) and PHP < 8.2 means composer update will fail for apps that have not upgraded their host framework. Plan the Laravel major upgrade first, then bump this package.
• No deprecation shims. Since v2 only changes constraints, there are no runtime deprecations to catch — but there is also no backwards-compatible path. Treat the composer constraint as the source of truth and pin ^1.4 on legacy branches.
• Config caching. If you edit config/num.php and see no change, run php artisan config:clear; stale cached config is the most common cause of "wrong output in production but correct locally."
• Locale is global-ish. If you rely on the app locale you inherit any setLocale calls made elsewhere (middleware, jobs, tests). Prefer passing the locale explicitly to the helper for anything user-facing.
• Rounding before conversion. Round/format decimals before converting to words so you don't get "one point two three four five" output. Convert the rounded value, keep the raw value for calculations.
• Extension points. The config file is the intended customisation surface; avoid subclassing internals since the major version bump signals the package is willing to move constraints sharply between majors.
• CI matrix. Update GitHub Actions / Forge / Vapor runtime to PHP 8.2+ and add Laravel 13 to your composer.json allow-test matrix; otherwise CI will silently keep testing an unsupported combo.