PHPackages                             pinoox/numera - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. pinoox/numera

ActiveLibrary[Utility & Helpers](/categories/utility)

pinoox/numera
=============

Translate Numera

2.1.2(1mo ago)1818.1k—7.7%31MITPHPPHP ^8.0CI passing

Since Apr 28Pushed 1mo agoCompare

[ Source](https://github.com/pinoox/numera)[ Packagist](https://packagist.org/packages/pinoox/numera)[ Docs](http://www.pinoox.com/)[ RSS](/packages/pinoox-numera/feed)WikiDiscussions master Synced yesterday

READMEChangelog (6)Dependencies (3)Versions (7)Used By (1)

**Numera: A PHP Library for Number to Words Conversion**
========================================================

[](#numera-a-php-library-for-number-to-words-conversion)

[![Coverage](https://camo.githubusercontent.com/c77e0d41846eb86126a5c2a39f1b1531c81152bf62109d9dcaaaf4137ec5001a/68747470733a2f2f636f6465636f762e696f2f67682f70696e6f6f782f6e756d6572612f6272616e63682f6d61737465722f67726170682f62616467652e737667)](https://codecov.io/gh/pinoox/numera)[![Latest Stable Version](https://camo.githubusercontent.com/d1392fbe7d4eb49581cb2e47fa0c4133371c6f416e7cbc0f00e8019fa7a03d08/68747470733a2f2f706f7365722e707567782e6f72672f70696e6f6f782f6e756d6572612f762f737461626c65)](https://packagist.org/packages/pinoox/numera)[![GitHub Stars](https://camo.githubusercontent.com/b8f038a6126ad78179bdcf3414f74e17c33c884eabc505b9caed48c09e5dad5b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f70696e6f6f782f6e756d6572612e737667)](https://github.com/pinoox/numera/stargazers)[![GitHub Forks](https://camo.githubusercontent.com/1ec7747f044771630c361143ff5093d935d6946a276628ed156c6d375a00e5dc/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f666f726b732f70696e6f6f782f6e756d6572612e737667)](https://github.com/pinoox/numera/network)[![GitHub Issues](https://camo.githubusercontent.com/5da659c58a8802327da251eb28eb9ffde686abbad543078ddc6d2d0a0c0c96a5/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732f70696e6f6f782f6e756d6572612e737667)](https://github.com/pinoox/numera/issues)[![License](https://camo.githubusercontent.com/d90f3bf397a9b24fd50d0680343ad7092d3d3a7115b19af7f5a6f2a7acdcf47e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f70696e6f6f782f6e756d6572612e737667)](https://github.com/pinoox/numera/blob/master/LICENSE)[![Total Downloads](https://camo.githubusercontent.com/24159a120beb6efc1cf3e06044570d889533322a2b91b170e54d12ac9b05fc33/68747470733a2f2f706f7365722e707567782e6f72672f70696e6f6f782f6e756d6572612f646f776e6c6f616473)](https://packagist.org/packages/pinoox/numera)

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:**

```
use Pino\Numera;

echo Numera::init('en')->n2w(1234);
echo Numera::init('fa')->n2w('۱۲۳۴');
echo Numera::init('en')->toYear(2024);
```

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

**Using Laravel?** Go to [For Laravel users](#for-laravel-users) — install `pinoox/numera-laravel` only.

- [For Laravel users](#for-laravel-users)
- [Features](#features)
- [API reference](#api-reference)
- [Project layout](#project-layout)
- [Installation and Setup](#installation-and-setup)
    - [Install via Composer](#install-via-composer)
    - [Initialize Numera](#initialize-numera)
- [Usage](#usage)
    - [Convert Numbers to Words](#convert-numbers-to-words)
    - [Negative Numbers](#negative-numbers)
    - [Decimal Numbers](#decimal-numbers)
    - [Ordinal Numbers](#ordinal-numbers)
    - [Currency Formatting](#currency-formatting)
    - [Units](#units)
    - [Convert Numbers to Summary Words](#convert-numbers-to-summary)
    - [Convert Words to Numbers](#convert-words-to-numbers)
    - [Use Camel Case](#use-camel-case)
    - [Input Formats](#input-formats)
    - [Fractions](#fractions)
    - [Years](#years)
    - [Phone Numbers](#phone-numbers)
    - [Roman Numerals](#roman-numerals)
    - [IP and Version Strings](#ip-and-version-strings)
- [Supported Languages](#supported-languages)
- [Set Locale](#set-locale)
- [Set Locale Fallback](#set-locale-fallback)
- [Get Translates](#get-translates)
- [Add Translate](#add-translate)
- [Create a New Language](#create-a-new-language)
- [Author](#author)
- [Contributing](#contributing)
- [Documentation](#documentation)
- [License](#license)

**Features**
------------

[](#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](#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**
-----------------

[](#api-reference)

MethodAliasDescription`n2w($num)`—Number → words (supports multiple input formats)`w2n($words)``s2n`Words → number`n2s($num)`—Number → summary (e.g. 4 Billion, 454 Million)`toOrdinal($n)``n2o`Ordinal words`toCurrency($amount, $code)`—Money with main/sub units`withUnit($n, $unit)`—Amount + unit (kg, hour, …)`toWeekday($day)``d2w`ISO key, index, or name → weekday word`getWeekdays()`—All weekdays (order from `meta.week_starts_on`)`translateTo($locale, $words)``t2t`Cross-locale word translation`detectFormat($input)`—Static: `default`, `european`, `swiss`, `persian`, `underscore``toFraction($float)``n2f`Common fractions (half, quarter, …)`toYear($year)``n2y`Year reading (English pairs; else cardinal)`toPhone($string)``n2p`Phone digit-by-digit`toRoman($int)``n2r`Integer → Roman (1–3999)`fromRoman($roman)`—Static: Roman → integer`toIp($ipv4)``n2ip`IPv4 octets as words`toVersion($semver)`—Version string (digits + labels)`setLocale($code)`—Switch locale (loads `src/lang/{code}.php`)`setLocaleFallback($code)`—Fallback when a key is missing`setCamelCase($bool)`—Title-case outputStatic helpers: `Numera::init($locale, $fallback)`, `getAvailableLocales()`, `hasLocale($code)`.

**Project layout**
------------------

[](#project-layout)

```
src/
  Numera.php              # Main API
  LocaleRegistry.php      # Locale load/merge (regional variants)
  Strategy/               # german, french, multiplier_tens, default
  Support/                # Input parsers, fractions, phone, IP, …
  Languages/              # English-specific year rules
  lang/                   # Per-locale translations (184+ files)
  data/                   # numbers.php, regional-locales, …
tests/                    # PHPUnit (1000+ tests)

```

**For Laravel users**
---------------------

[](#for-laravel-users)

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

### Install

[](#install)

```
composer require pinoox/numera-laravel
```

RequirementVersionPHP^8.0Laravel9, 10, or 11Packagist[pinoox/numera-laravel](https://packagist.org/packages/pinoox/numera-laravel)No manual service-provider registration: Laravel **auto-discovers** `NumeraServiceProvider` and registers the **`Numera` facade**.

### Configuration (required once)

[](#configuration-required-once)

```
php artisan vendor:publish --tag=numera-config
```

Edit `config/numera.php`:

```
'default_locale' => 'en',   // or fa, de, fa-IR, …
'fallback_locale' => 'en',
```

### Usage

[](#usage)

```
use Pinoox\Numera\Laravel\Facades\Numera;

echo Numera::n2w(1234);
echo Numera::toYear(2024);
echo Numera::setLocale('fa')->n2w(-500);
```

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

### More detail

[](#more-detail)

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

**Installation and Setup**
--------------------------

[](#installation-and-setup)

> **Note:** This section is for **plain PHP** (Symfony, WordPress, custom apps). Laravel projects should follow [For Laravel users](#for-laravel-users) above.

### Install via Composer

[](#install-via-composer)

You can install Numera using Composer:

```
composer require pinoox/numera

```

### Initialize Numera

[](#initialize-numera)

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

```
use Pino\Numera;

$numera = Numera::init('en'); // Initialize with English locale
```

### Convert Numbers to Words

[](#convert-numbers-to-words)

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

```
$result = $numera->convertToWords(4454545156);
echo $result; // Output: "four billion, four hundred fifty-four million, five hundred forty-five thousand, one hundred fifty-six"
```

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

```
$result = $numera->n2w('4,454,545,156');
echo $result; // Output: "four billion, four hundred fifty-four million, five hundred forty-five thousand, one hundred fifty-six"
```

### Negative Numbers

[](#negative-numbers)

```
echo Numera::init('en')->n2w(-500);  // negative five hundred
echo Numera::init('fa')->n2w(-500);  // منفی پانصد
```

### Decimal Numbers

[](#decimal-numbers)

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

```
echo Numera::init('en')->n2w(3.14);       // three point one four
echo Numera::init('en')->n2w('1,250.75'); // one thousand, two hundred fifty point seven five
echo Numera::init('fa')->n2w(3.14);       // سه ممیز یک چهار
```

### Ordinal Numbers

[](#ordinal-numbers)

```
$numera = Numera::init('en');
echo $numera->toOrdinal(21);  // twenty-first
echo $numera->n2o(100);       // one hundredth

$numera->setLocale('fa');
echo $numera->toOrdinal(3);   // سوم
echo $numera->toOrdinal(21);  // بیست و یکم
```

### Currency Formatting

[](#currency-formatting)

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

```
echo Numera::init('en')->toCurrency(1250.50, 'USD');
// one thousand, two hundred fifty dollars and fifty cents

echo Numera::init('fa')->toCurrency(150000, 'IRR');
// صد و پنجاه هزار ریال

echo Numera::init('en')->toCurrency(3.01, 'GBP');
// three pounds and one penny
```

### Units

[](#units)

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

```
echo Numera::init('en')->withUnit(1, 'kg');   // one kilogram
echo Numera::init('en')->withUnit(5, 'hour'); // five hours
echo Numera::init('fa')->withUnit(1, 'day');  // یک روز
```

### Weekdays

[](#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.

```
echo Numera::init('en')->toWeekday(1);        // monday
echo Numera::init('en')->toWeekday('friday'); // friday
echo Numera::init('fa')->toWeekday(5);        // جمعه (ISO: Friday)
echo Numera::init('fa')->toWeekday(6);        // شنبه (ISO: Saturday)
echo Numera::init('fa')->d2w('saturday');     // شنبه

// All days; Persian locale starts on Saturday (meta.week_starts_on)
print_r(Numera::init('fa')->getWeekdays());
```

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

### Cross-locale translation (words → words)

[](#cross-locale-translation-words--words)

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

```
// Persian → English
echo Numera::init('fa')->translateTo('en', 'دویست و یک');  // two hundred one
echo Numera::init('fa')->translateTo('en', 'شنبه');       // saturday

// English → Persian
echo Numera::init('en')->translateTo('fa', 'two hundred one'); // دویست و یک
echo Numera::init('en')->t2t('monday', 'fa');                 // دوشنبه

LocaleTranslator::between('fa', 'en')->translate('منفی پانصد'); // negative five hundred
```

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

Chain with locale and camel case:

```
echo Numera::init('en')->setCamelCase(true)->n2w(-10); // Negative Ten
```

### Convert Numbers to Summary

[](#convert-numbers-to-summary)

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

```
$result = $numera->convertToSummary(4454545156);
echo $result; // Output: "4 Billion, 454 Million, 545 Thousand, 156"
```

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

```
$result = $numera->n2s('4,454,545,156');
echo $result; // Output: "4 Billion, 454 Million, 545 Thousand, 156"
```

### Convert Words to Numbers

[](#convert-words-to-numbers)

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

```
$result = $numera->convertToNumber('four billion, four hundred fifty-four million, five hundred forty-five thousand, one hundred fifty-six');
echo $result; // Output: 4454545156
```

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

```
$result = $numera->w2n("4 Billion, 454 Million, 545 Thousand, 156");
echo $result; // Output: 4454545156
```

You can also specify separators for the `w2n` method:

```
$result = $numera->w2n('four billion, four hundred fifty-four million, five hundred forty-five thousand, one hundred fifty-six', [' ', ',']);
echo $result; // Output: 4454545156
```

### Use Camel Case

[](#use-camel-case)

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

```
$numera->setCamelCase(true);
$result = $numera->convertToWords('4,454,545,156');
echo $result; // Output: "Four Billion, Four Hundred Fifty-Four Million, Five Hundred Forty-Five Thousand, One Hundred Fifty-Six"
```

### Input Formats

[](#input-formats)

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

FormatExample`detectFormat()`Default`1234.56`, `1,250.75``default`European`1.234.567,89``european`Swiss`1'234'567.89``swiss`Persian/Arabic digits`۱۲۳۴``persian`Underscore`1_000_000``underscore````
Numera::detectFormat("1.234.567,89"); // european
echo Numera::init('en')->n2w('۱۲۳۴');
echo Numera::init('en')->n2w("1'234'567.89");
echo Numera::init('en')->n2w('1_000_000');
```

### Fractions

[](#fractions)

```
echo Numera::init('en')->toFraction(0.5);   // one half
echo Numera::init('en')->n2f(1.5);         // one and a half
echo Numera::init('fa')->toFraction(0.5);  // نیم
```

### Years

[](#years)

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

```
echo Numera::init('en')->toYear(2024);  // twenty twenty-four
echo Numera::init('en')->n2y(2000);     // two thousand
echo Numera::init('fa')->toYear(1402);  // cardinal Persian form
```

### Phone Numbers

[](#phone-numbers)

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

```
echo Numera::init('en')->toPhone('+1 415 555 0172');
echo Numera::init('en')->n2p('021-8834-1100');
```

### Roman Numerals

[](#roman-numerals)

```
echo Numera::init('en')->toRoman(1999);      // MCMXCIX
echo Numera::fromRoman('xiv');               // 14
```

### IP and Version Strings

[](#ip-and-version-strings)

```
echo Numera::init('en')->toIp('192.168.1.1');
echo Numera::init('en')->n2ip('10.0.0.1');
echo Numera::init('en')->toVersion('2.14.0');
echo Numera::init('en')->toVersion('1.0.0-beta');
```

### Supported Languages

[](#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`.

```
Numera::init('en-US')->n2w(42);       // same words as en, US meta
Numera::init('en-GB')->toCurrency(3.01, 'GBP');
Numera::init('fa-IR')->getWeekdays();  // inherits fa (week starts Saturday)
Numera::init('de-AT')->getStrategyName(); // german (inherited from de)
```

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

StrategyLocalesReason`german``de`, `de-*`Inverted tens (`einundzwanzig`), `tausend` concatenation`french``fr`, `fr-*`Vigesimal 70–99 (`soixante-dix`, `quatre-vingts`)`multiplier_tens``id`, `ms`, `vi`, `jv`, `tl`, `mi`, `sm`, `to`, `ty``dua puluh tiga` = 2×10+3, not 2+10+3`default`Most othersEnglish-style place valueWelsh (`cy`), Breton (`br`), and some locales with incomplete lang data may still need dedicated strategies or richer translations in `src/lang/`.

### Set Locale

[](#set-locale)

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

```
$numera->setLocale('fa'); // Set locale to Persian
```

### Set Locale Fallback

[](#set-locale-fallback)

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

```
$numera->setLocaleFallback('en'); // Set fallback locale to English
```

### Get Translates

[](#get-translates)

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

```
$translates = $numera->getTranslates();
print_r($translates); // Output: Array of translates for the current locale
```

### Add Translate

[](#add-translate)

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

```
$numera->addTranslate('fr', ['four' => 'quatre']); // Add French translates
```

### Add Translate File

[](#add-translate-file)

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

```
$numera->addTranslateFile('fr','/path/lang/fr.php'); // Add French translates
```

### Create a New Language

[](#create-a-new-language)

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

**Author**
----------

[](#author)

Numera was created by [Pinoox](https://www.pinoox.com/).

**Contributing**
----------------

[](#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**
-----------

[](#testing)

```
composer install
vendor/bin/phpunit
```

Laravel package CI runs in [pinoox/numera-laravel](https://github.com/pinoox/numera-laravel).

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

**Upgrade from 2.0**
--------------------

[](#upgrade-from-20)

```
composer require pinoox/numera:^2.1
```

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**
-----------------

[](#documentation)

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

**License**
-----------

[](#license)

Numera is licensed under the [MIT License](https://opensource.org/licenses/MIT). See the LICENSE file for more information.

###  Health Score

51

—

FairBetter than 95% of packages

Maintenance94

Actively maintained with recent releases

Popularity36

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~153 days

Recently: every ~191 days

Total

6

Last Release

30d ago

Major Versions

1.1.2 → 2.0.02026-05-25

### Community

Maintainers

![](https://www.gravatar.com/avatar/b0b2d1a1048bdc12294e89e6f94f2f2b0bf1805fd01dec2195aa9ab906a02b82?d=identicon)[pinoox](/maintainers/pinoox)

---

Top Contributors

[![yoosefap](https://avatars.githubusercontent.com/u/24357596?v=4)](https://github.com/yoosefap "yoosefap (35 commits)")

---

Tags

phpnumber translate

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/pinoox-numera/health.svg)

```
[![Health](https://phpackages.com/badges/pinoox-numera/health.svg)](https://phpackages.com/packages/pinoox-numera)
```

###  Alternatives

[imanghafoori/laravel-anypass

A minimal yet powerful package to help you in development.

21623.4k](/packages/imanghafoori-laravel-anypass)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)