README

Multi-language and multi-currency number to words converter for Laravel.

Features

Convert numbers to words in multiple languages (Turkish, English)
Convert currency amounts to words with proper formatting
Smart pluralization support (e.g., "1 dollar" vs "2 dollars")
Flexible input parsing (handles various number formats)
Customizable output (uppercase, lowercase, custom separators)
Fail-safe (never throws exceptions)
Easy to extend with new languages and currencies

Installation

composer require codemarkt/laravel-number-to-words

Configuration

Publish the configuration file:

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

Publish the language files (optional):

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

Configuration options in config/number-to-words.php:

return [
    'locale' => 'tr',
    'fallback_locale' => 'en',
    'case' => 'lowercase',
    'separator' => ' ',
];

Usage

Recommended: Using Helper Functions (Shorter Syntax)

// Convert numbers to words
number_to_words(154); // Uses default locale from config
number_to_words(154, 'tr'); // "yüz elli dört"
number_to_words(154, 'en'); // "one hundred fifty four"

// Convert currency amounts
number_to_currency_words(8097.21, 'TRY', 'tr'); // "sekiz bin doksan yedi türk lirası yirmi bir kuruş"
number_to_currency_words(150.50, 'USD', 'en'); // "one hundred fifty us dollar fifty cent"

// With custom formatting
number_to_words(123, 'tr', 'uppercase', '-'); // "YÜZ-YİRMİ-ÜÇ"

Using Facade (Alternative)

use CodeMarkt\NumberToWords\Facades\NumberToWords;

// Or use the global alias (automatically registered)
use NumberToWords;

NumberToWords::toWords(154, 'tr'); // "yüz elli dört"
NumberToWords::toCurrency(8097.21, 'TRY', 'tr'); // "sekiz bin doksan yedi türk lirası yirmi bir kuruş"

Using Service Container

$service = app(\CodeMarkt\NumberToWords\NumberToWordsService::class);
$service->toWords(154, 'tr');

Input Formats

The package handles various number formats automatically:

NumberToWords::toWords('8.097,21'); // Turkish format → 8097.21
NumberToWords::toWords('1,200.56'); // English format → 1200.56
NumberToWords::toWords('18 500,90'); // With spaces → 18500.90
NumberToWords::toWords(1200.0); // Float
NumberToWords::toWords(1200); // Integer

Supported Languages

Turkish (tr)
English (en)

Supported Currencies

TRY (Turkish Lira)
USD (US Dollar)
EUR (Euro)
GBP (British Pound)

Adding Custom Languages and Currencies

Adding a New Currency

Simply add the currency to your language files. The package supports both simple strings and pluralization:

Simple format (backward compatible):

'currencies' => [
    'JPY' => [
        'major' => 'Japanese yen',
        'minor' => '', // Leave empty if no minor unit
    ],
],

With pluralization (recommended for proper grammar):

'currencies' => [
    'USD' => [
        'major' => [
            'singular' => 'US dollar',
            'plural' => 'US dollars',
        ],
        'minor' => [
            'singular' => 'cent',
            'plural' => 'cents',
        ],
    ],
],

The package automatically uses the correct form based on the amount:

1.50 USD → "one US dollar fifty cents"
2.00 USD → "two US dollars"

Creating a New Language File

Create a new language file in resources/lang/vendor/number-to-words/{locale}/number.php:

return [
    'digits' => [
        '0' => 'zero',
        '1' => 'one',
        // ...
    ],
    'tens' => [
        '10' => 'ten',
        '20' => 'twenty',
        // ...
    ],
    'hundred' => 'hundred',
    'exponents' => [
        0 => '',
        1 => 'thousand',
        2 => 'million',
        // ...
    ],
    'currencies' => [
        'USD' => [
            'major' => 'dollar',
            'minor' => 'cent',
        ],
        // ...
    ],
];

Testing

composer test

License

The MIT License (MIT). Please see License File for more information.

codemarkt / laravel-number-to-words

Maintainers

Details