Download the PHP package pinoox/numera without Composer

Numera: A PHP Library for Number to Words Conversion

Numera is a PHP library that converts numbers to words (and back), with support for 184 ISO 639-1 languages, regional variants, ordinals, currency, units, weekdays, cross-locale translation, and specialized reading modes (fractions, years, phone numbers, Roman numerals, IP/version strings).

Requirements: PHP ^8.0, Composer. No runtime dependencies.

Quick start:

Install (plain PHP): composer require pinoox/numera — see CHANGELOG.md for release notes.

Using Laravel? Go to For Laravel users — install pinoox/numera-laravel only.

• For Laravel users
• Features
• API reference
• Project layout
• Installation and Setup
  • Install via Composer
  • Initialize Numera
• Usage
  • Convert Numbers to Words
  • Negative Numbers
  • Decimal Numbers
  • Ordinal Numbers
  • Currency Formatting
  • Units
  • Convert Numbers to Summary Words
  • Convert Words to Numbers
  • Use Camel Case
  • Input Formats
  • Fractions
  • Years
  • Phone Numbers
  • Roman Numerals
  • IP and Version Strings
• Supported Languages
• Set Locale
• Set Locale Fallback
• Get Translates
• Add Translate
• Create a New Language
• Author
• Contributing
• Documentation
• License

Features

• Convert numbers to words (e.g. 1234 to "one thousand two hundred thirty-four")
• Convert words to numbers (e.g. "one thousand two hundred thirty-four" to 1234)
• Negative numbers (n2w(-500) → "negative five hundred")
• Decimal numbers (n2w(3.14) → "three point one four")
• Ordinal numbers (toOrdinal(21) / n2o(21) → "twenty-first")
• Currency formatting (toCurrency(1250.50, 'USD'))
• Units with singular/plural (withUnit(3, 'kg') → "three kilograms")
• Weekday names (toWeekday(1) / getWeekdays() — Monday=1 ISO, or saturday, …)
• Cross-locale word translation (translateTo('en', 'دویست و یک') / t2t())
• European, Swiss, Persian-digit, and underscore numeric input formats
• Fractions (toFraction() / n2f()), year reading (toYear() / n2y()), phone numbers (toPhone() / n2p())
• Roman numerals (toRoman() / n2r(), Numera::fromRoman())
• IPv4 and semver reading (toIp() / n2ip(), toVersion())
• Laravel bridge — see For Laravel users (pinoox/numera-laravel)
• 180+ ISO 639-1 language packs (English and Persian fully extended)
• Camel case support for output words
• Easy to use and extend
• GitHub Actions CI (PHP 8.0–8.3) and optional Codecov badge

API reference

Static helpers: Numera::init($locale, $fallback), getAvailableLocales(), hasLocale($code).

Project layout

For Laravel users

Use the dedicated Laravel package — it pulls in pinoox/numera automatically.

Install

No manual service-provider registration: Laravel auto-discovers NumeraServiceProvider and registers the Numera facade.

Configuration (required once)

Edit config/numera.php:

Usage

All methods from the core library (n2w, w2n, toCurrency, toFraction, …) work on the facade.

More detail

• Full Laravel guide: github.com/pinoox/numera-laravel
• Core API (all locales and options): sections below in this README

Installation and Setup

Note: This section is for plain PHP (Symfony, WordPress, custom apps). Laravel projects should follow For Laravel users above.

Install via Composer

You can install Numera using Composer:

Initialize Numera

To use Numera, you need to initialize it with a locale. You can do this using the init method:

Convert Numbers to Words

To convert a number to words, use the convertToWords method:

Alternatively, you can use the n2w method for a simpler syntax:

Negative Numbers

Decimal Numbers

Each digit after the decimal separator is read individually. Accepts floats or strings (3.14, 1,250.75).

Ordinal Numbers

Currency Formatting

Supported codes: USD, EUR, GBP, IRR, IRT (extend via language file currencies maps).

Units

Supported units: kg, g, km, m, cm, hour, minute, second, day, week, month, year.

Weekdays

Day names live in each language file under weekdays (monday … sunday). Use ISO weekday numbers (1 = Monday … 7 = Sunday), PHP date('w') (0 = Sunday … 6 = Saturday), or the English key name.

Optional meta.week_starts_on in src/lang/{locale}.php controls the order returned by getWeekdays() (default: monday).

Cross-locale translation (words → words)

Convert spoken/written text in one language to another via a neutral intermediate (integer or weekday key):

Supports cardinal numbers (including negative and decimal phrases), and weekday names. Currency/unit phrases are not converted yet.

Chain with locale and camel case:

Convert Numbers to Summary

To convert a number to summary words, use the convertToSummary method:

Alternatively, you can use the n2w method for a simpler syntax:

Convert Words to Numbers

To convert words to a number, use the convertToNumber method:

Alternatively, you can use the w2n method for a simpler syntax:

You can also specify separators for the w2n method:

Use Camel Case

To use camel case for output words, use the setCamelCase method:

Input Formats

n2w() and w2n() normalize these string formats before parsing:

Fractions

Years

English uses paired year reading (1999 → nineteen ninety-nine). Other locales use cardinal form.

Phone Numbers

Reads digit-by-digit with locale-aware digit words.

Roman Numerals

IP and Version Strings

Supported Languages

Numera ships with 184 ISO 639-1 language packs under src/lang/, plus regional variants such as en-US, en-GB, fa-IR, de-DE (see src/data/regional-locales.php). Each base file contains cardinals, separators, and v1.2 keys (negative, point, ordinals, currencies, units, weekdays, …). Edit the locale file directly — see src/lang/en.php and TranslationGuide.md.

Regional variants (BCP 47): Files like src/lang/en-US.php only declare overrides (usually meta.region); translations are merged from the parent (en.php → en-US.php). Configured regions are listed in src/data/regional-locales.php.

Number strategies: Languages with special compounding use meta.strategy in the lang file (see src/data/locale-strategies.php):

Welsh (cy), Breton (br), and some locales with incomplete lang data may still need dedicated strategies or richer translations in src/lang/.

Set Locale

To set the locale for the Numera object, use the setLocale method:

Set Locale Fallback

To set the fallback locale for the Numera object, use the setLocaleFallback method:

Get Translates

To get the translates for the current locale, use the getTranslates method:

Add Translate

To add translates for a specific locale, use the addTranslate method:

Add Translate File

To add translates by array file for a specific locale, use the addTranslateFile method:

Create a New Language

If you want to add support for a new language, please read our Translation Guide for a step-by-step guide on how to create a new language pack.

Author

Numera was created by Pinoox.

Contributing

If you'd like to contribute to Numera, please fork the repository and submit a pull request. We'd love to have your help.

Testing

Laravel package CI runs in pinoox/numera-laravel.

CI for this library runs on push/PR to master (see .github/workflows/ci.yml).

Upgrade from 2.0

New methods are additive; existing n2w, w2n, toCurrency, etc. are unchanged. Add fractions, plus, dot, dash to custom lang files if you use toFraction, toPhone, toIp, or toVersion.

Documentation

• README.md — This file
• CHANGELOG.md — Release history
• TranslationGuide.md — Creating or extending language packs
• pinoox/numera-laravel — Laravel users: composer require pinoox/numera-laravel
• src/lang/_schema.php — Expected locale file structure
• src/lang/en.php — Reference locale (full v2.1 keys)

License

Numera is licensed under the MIT License. See the LICENSE file for more information.