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.