README

Convert numbers and currency values to words in Portuguese (Brazil) for Laravel applications.

Features

• ✅ Convert numbers to words
• ✅ Convert currency values to words (BRL)
• ✅ Bug-free (no trailing "e" issue)
• ✅ Easy to use with Facade and helpers
• ✅ Laravel 9, 10, 11, 12, and 13 support
• ✅ PHP 8.0+ support

Installation

composer require joelhmetz/laravel-number-to-words

Publish Configuration (Optional)

php artisan vendor:publish --tag=number-to-words-config

Usage

Using Facade

use Joelhmetz\LaravelNumberToWords\Facades\NumberToWords;

// Convert number to words
NumberToWords::spell(123);
// "cento e vinte e três"

NumberToWords::spell(1000);
// "mil"

// Convert currency to words
NumberToWords::currency(1234.56);
// "mil duzentos e trinta e quatro reais e cinquenta e seis centavos"

NumberToWords::currency(100);
// "cem reais"

Using Helpers

// Convert number to words
number_to_words(456);
// "quatrocentos e cinquenta e seis"

// Convert currency to words
currency_to_words(789.99);
// "setecentos e oitenta e nove reais e noventa e nove centavos"

Direct Instantiation

$converter = new \Joelhmetz\LaravelNumberToWords\NumberToWords();

$converter->spell(500);
// "quinhentos"

$converter->currency(1500.50);
// "mil e quinhentos reais e cinquenta centavos"

Examples

NumberToWords::spell(0);        // "zero"
NumberToWords::spell(1);        // "um"
NumberToWords::spell(15);       // "quinze"
NumberToWords::spell(100);      // "cem"
NumberToWords::spell(1000);     // "mil"
NumberToWords::spell(1000000);  // "um milhão"

NumberToWords::currency(0);     // "zero real"
NumberToWords::currency(1);     // "um real"
NumberToWords::currency(1.01);  // "um real e um centavo"
NumberToWords::currency(10.50); // "dez reais e cinquenta centavos"

Configuration

You can customize the locale in the config file config/number-to-words.php:

return [
    'locale' => env('NUMBER_TO_WORDS_LOCALE', 'pt_BR'),
];

Or set in your .env file:

NUMBER_TO_WORDS_LOCALE=pt_BR

Bug Fix

This package includes a fix for the common "trailing e" bug found in other similar packages. Numbers are always returned without trailing "e" words.

Requirements

• PHP 8.1 or higher
• Laravel 9.0, 10.0, 11.0, 12.0, or 13.0

License

MIT License. See LICENSE for details.

Author

Joel Metz - joelhmetz@gmail.com

Contributing

Pull requests are welcome! Please feel free to submit issues and enhancement requests.