siteapps / number-to-words

dev-main 2026-08-21 06:51 UTC

Requires

• php: ^8.0

Unknown License

Published on Packagist.org on 2026-08-21 06:52 UTC

README

A lightweight PHP 8+ library for converting numbers to words in multiple languages.

Currently supported:

• 🇳🇱 Dutch (nl)
• 🇬🇧 English (en)
• 🇩🇪 German (de)
• 🇫🇷 French (fr)
• 🇮🇹 Italian (it)
• 🇪🇸 Spanish (es)

The library uses a simple API and separate language implementations, making it easy to add additional languages later.

Requirements

• PHP 8.0 or newer
• Composer

Installation

Install the package with Composer:

composer require siteapps/number-to-words

Usage

<?php

require 'vendor/autoload.php';

use Siteapps\NumberToWords\NumberToWords;

echo NumberToWords::convert(1234, 'nl');

Output:

duizend tweehonderdvierendertig

Languages

The second argument determines the language:

NumberToWords::convert(1234, 'nl'); // Dutch
NumberToWords::convert(1234, 'en'); // English
NumberToWords::convert(1234, 'de'); // German
NumberToWords::convert(1234, 'fr'); // French
NumberToWords::convert(1234, 'it'); // Italian
NumberToWords::convert(1234, 'es'); // Spanish

Examples

Dutch

NumberToWords::convert(21, 'nl');
// eenentwintig

NumberToWords::convert(1234, 'nl');
// duizend tweehonderdvierendertig

English

NumberToWords::convert(21, 'en');
// twenty-one

NumberToWords::convert(1234, 'en');
// one thousand two hundred thirty-four

German

NumberToWords::convert(21, 'de');
// einundzwanzig

NumberToWords::convert(1234, 'de');
// eintausendzweihundertvierunddreißig

French

NumberToWords::convert(21, 'fr');
// vingt et un

NumberToWords::convert(1234, 'fr');
// mille deux cent trente-quatre

Italian

NumberToWords::convert(21, 'it');
// ventuno

NumberToWords::convert(1234, 'it');
// milleduecentotrentaquattro

Spanish

NumberToWords::convert(21, 'es');
// veintiuno

NumberToWords::convert(1234, 'es');
// mil doscientos treinta y cuatro

Negative numbers

Negative numbers are supported:

NumberToWords::convert(-42, 'nl');
// min tweeënveertig

NumberToWords::convert(-42, 'en');
// minus forty-two

NumberToWords::convert(-42, 'de');
// minus zweiundvierzig

Zero

Zero is supported in every language:

NumberToWords::convert(0, 'nl');
// nul

NumberToWords::convert(0, 'en');
// zero

NumberToWords::convert(0, 'de');
// null

Supported range

The current implementation supports numbers up to:

999,999,999,999

Numbers outside the supported range result in an InvalidArgumentException.

Error handling

An unsupported language throws an InvalidArgumentException:

try {
    echo NumberToWords::convert(123, 'xx');
} catch (InvalidArgumentException $e) {
    echo $e->getMessage();
}

Supported language codes are:

nl
de
en
fr
it
es

Architecture

The public API is intentionally small:

NumberToWords::convert(int $number, string $language = 'nl'): string

Each language has its own implementation:

src/
├── NumberToWords.php
├── NumberToWordsInterface.php
└── Language/
    ├── Dutch.php
    ├── English.php
    ├── German.php
    ├── French.php
    ├── Italian.php
    └── Spanish.php

This means new languages can be added without changing the existing language implementations.

A new language should implement:

interface NumberToWordsInterface
{
    public function convert(int $number): string;
}

and then be registered in NumberToWords.php.

Testing

The project includes PHPUnit tests.

Install development dependencies:

composer install

Then run:

vendor/bin/phpunit

Contributing

Contributions are welcome.

If you add or modify a language, please also add tests covering:

• zero
• single digits
• numbers from 10–19
• tens
• hundreds
• thousands
• millions
• billions
• negative numbers
• language-specific grammatical exceptions

License

MIT License

Copyright (c) 2026

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.