PHPackages                             marcoconsiglio/modular-arithmetic - 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. marcoconsiglio/modular-arithmetic

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

marcoconsiglio/modular-arithmetic
=================================

A PHP libarary to support modular arithmetic, aka clock arithmetic.

v4.1.0(2mo ago)01951MITPHPPHP ^8.4

Since Jan 4Pushed 2mo agoCompare

[ Source](https://github.com/MarcoConsiglio/php-modular-arithmetic)[ Packagist](https://packagist.org/packages/marcoconsiglio/modular-arithmetic)[ RSS](/packages/marcoconsiglio-modular-arithmetic/feed)WikiDiscussions main Synced today

READMEChangelog (10)Dependencies (15)Versions (13)Used By (1)

[![GitHub License](https://camo.githubusercontent.com/dec084f3277b5417dc078b2e69dd31e00274d5949eaa276908b9e7cf58291f43/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f4d6172636f436f6e7369676c696f2f7068702d6d6f64756c61722d61726974686d65746963)](https://camo.githubusercontent.com/dec084f3277b5417dc078b2e69dd31e00274d5949eaa276908b9e7cf58291f43/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f4d6172636f436f6e7369676c696f2f7068702d6d6f64756c61722d61726974686d65746963)[![GitHub Release](https://camo.githubusercontent.com/3e6b00d79326ce8df39c09b79d6d8ae16e75a104db36f543f2768d33b87a7e69/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f4d6172636f436f6e7369676c696f2f7068702d6d6f64756c61722d61726974686d65746963)](https://camo.githubusercontent.com/3e6b00d79326ce8df39c09b79d6d8ae16e75a104db36f543f2768d33b87a7e69/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f4d6172636f436f6e7369676c696f2f7068702d6d6f64756c61722d61726974686d65746963)[![Static Badge](https://camo.githubusercontent.com/36c38aef5b7456f6191552698329f9269cef1a4cbf541bfdcef32d28519bc0c3/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d76342e312e302d7768697465)](https://camo.githubusercontent.com/36c38aef5b7456f6191552698329f9269cef1a4cbf541bfdcef32d28519bc0c3/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d76342e312e302d7768697465)
[![Static Badge](https://camo.githubusercontent.com/c8bb3ac16242973a4e2ecff80b432a82e780de20d01cdb30a85d933c8240dea0/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f3130302532352d7267622834302532432532303136372532432532303639293f6c6162656c3d4c696e65253230636f766572616765266c6162656c436f6c6f723d7267622832353525324332353525324332353529)](https://camo.githubusercontent.com/c8bb3ac16242973a4e2ecff80b432a82e780de20d01cdb30a85d933c8240dea0/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f3130302532352d7267622834302532432532303136372532432532303639293f6c6162656c3d4c696e65253230636f766572616765266c6162656c436f6c6f723d7267622832353525324332353525324332353529)[![Static Badge](https://camo.githubusercontent.com/17d4060f432cfe200fb084ac29608093018de28488b3f953bb0cca6c6ec68f2d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f3130302532352d7267622834302532432532303136372532432532303639293f6c6162656c3d4272616e6368253230636f766572616765266c6162656c436f6c6f723d7267622832353525324332353525324332353529)](https://camo.githubusercontent.com/17d4060f432cfe200fb084ac29608093018de28488b3f953bb0cca6c6ec68f2d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f3130302532352d7267622834302532432532303136372532432532303639293f6c6162656c3d4272616e6368253230636f766572616765266c6162656c436f6c6f723d7267622832353525324332353525324332353529)[![Static Badge](https://camo.githubusercontent.com/2006d4981b791087a970c2c0de3f40adcaf00b87cd9522d73ff1c9508cc8cd0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f3130302532352d7267622834302532432532303136372532432532303639293f6c6162656c3d50617468253230636f766572616765266c6162656c436f6c6f723d7267622832353525324332353525324332353529)](https://camo.githubusercontent.com/2006d4981b791087a970c2c0de3f40adcaf00b87cd9522d73ff1c9508cc8cd0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f3130302532352d7267622834302532432532303136372532432532303639293f6c6162656c3d50617468253230636f766572616765266c6162656c436f6c6f723d7267622832353525324332353525324332353529)

Modular Arithmetic
==================

[](#modular-arithmetic)

A PHP libarary to support modular arithmetic, aka *clock arithmetic*.

This software is made to overcome the [limit of modulo operation in PHP](https://bugs.php.net/bug.php?id=76287) where a negative modulus (divisor) would be treated as a positive one.

It also provide convenient modular arithmetic operations.

It is based on arbitrary precision calculations made with [BC Math Extended](https://github.com/MarcoConsiglio/bcmath-extended), check its API documentation to more info about the `Number` class.

Index
=====

[](#index)

- [Requirement](#requirement)
- [Usage](#usage)
- [Operations on a `ModularNumber`](#operations-on-a-modularnumber)
    - [Addition](#addition)
    - [Multiplication](#multiplication)
    - [Exponentiation](#exponentiation)
- [Operations on a `ModularRelativeNumber`](#operations-on-a-modularrelativenumber)
    - [Addition](#addition-1)
- [API documentation](#api-documentation)

Requirement
-----------

[](#requirement)

- PHP ^8.4
- [BCMath extension](https://www.php.net/manual/en/book.bc.php)

Installation
------------

[](#installation)

```
composer install marcoconsiglio/modular-arithmetic
```

Usage
-----

[](#usage)

A `ModularNumber` is a number placed in a ring with positive numbers starting from zero. The length of this ring is the **modulus**.

A `ModularRelativeNumber` is a number placed in a `Ring` whose **start** and **end** can be relative (like -180/180). In this case the start coincides with the end.

Construct a `ModularNumber` with its modulus if the ring has only positive numbers.

```
use Marcoconsiglio\ModularArithmetic\ModularNumber;

$hour_on_a_clock = 12;
$current_hour = new ModularNumber(15, $hour_on_a_clock);
echo "The current hour is $current_hour->value o'clock.";
```

```
The current hour is 3 o'clock.

```

Construct a `ModularNumber` with its `Ring` (or start and end of the `Ring`)

```
use Marcoconsiglio\ModularArithmetic\ModularRelativeNumber;
use Marcoconsiglio\ModularArithmetic\Ring;

$start = -180;
$end = 180;
$steering_wheel = ModularRelativeNumber::createFromExtremes(
    30, -180, 180
);

echo "Turn left {$steering_wheel->value}°" . PHP_EOL;

$steering_wheel = ModularRelativeNumber::createFromRing(
    -45, new Ring($start, $end)
);

echo "Now turn right {$steering_wheel->value}°" . PHP_EOL;
```

```
Turn left 30°
Now turn right -45°

```

Operations on a `ModularNumber`
-------------------------------

[](#operations-on-a-modularnumber)

### Addition

[](#addition)

You can add two `ModularNumber`: the sum will be a `ModularNumber` instance.

```
use Marcoconsiglio\ModularArithmetic\ModularNumber;

$hour_on_a_clock = 12;
$work_start = new ModularNumber(9, $hour_on_a_clock);
$working_time = new ModularNumber(9, $hour_on_a_clock);
$work_end = $work_start->add($working_time->value);
echo "I'm going to start to work at {$work_start->value} o'clock a.m.\n";
echo "I'll work for {$working_time->value} hours.\n";
echo "I'll finish to work at {$work_end->value} o'clock p.m.";
```

```
I'm going to start to work at 9 o'clock a.m.
I'll work for 9 hours.
I'll finish to work at 6 o'clock p.m.

```

### Multiplication

[](#multiplication)

You can multiply two `ModularNumber`: the product will be a `ModularNumber` instance.

```
use Marcoconsiglio\ModularArithmetic\ModularNumber;

$hours_in_a_day = 24;
$start_shift = new ModularNumber(0, $hours_in_a_day); /* midnight */
$shift_duration = new ModularNumber(3, $hours_in_a_day);
$my_shift = new ModularNumber(5, $hours_in_a_day); /* 5th turn */
$time_to_wait = $shift_duration->multiply($my_shift);
$my_shift_start = $start_shift->add($time_to_wait);
echo "There is a new guard shift every {$shift_duration->value} hours.\n";
echo "My shift, starts at {$my_shift_start->value} o'clock.";
```

```
There is a new guard shift every 3 hours.
My shift, the 5th, starts at 15 o'clock.

```

### Exponentiation

[](#exponentiation)

You can raise to power $k$ a `ModularNumber`: the result will be a `ModularNumber` instance.

```
use Marcoconsiglio\ModularArithmetic\ModularNumber;

$alphabet_lenght = 26;
$alphabet_set = range('A', 'Z');
$message = ['H', 'E', 'L', 'L', 'O'];
$encrypted_message = [];
$cypher_key = 3;
echo "Encrypting the message:\n";
echo implode("", $message)."\n";
foreach ($message as $char) {
    $unencrypted_index = new ModularNumber(
        array_search($char, $alphabet_set),
        $alphabet_lenght
    );
    $encrypted_index = $unencrypted_index->power($cypher_key);
    $encrypted_message[] = $alphabet_set[$encrypted_index->value];
}
echo "Encrypted message:\n";
echo implode("", array: $encrypted_message);
```

```
Encrypting the message:
HELLO
Encrypted message:
FMFFO

```

Operations on a `ModularRelativeNumber`
---------------------------------------

[](#operations-on-a-modularrelativenumber)

### Addition

[](#addition-1)

Only addition is available for `ModularRelativeNumber`s. To perform subtraction, add a negative `Number`.

```
use MarcoConsiglio\ModularArithmetic\ModularNumber;
use MarcoConsiglio\ModularArithmetic\ModularRelativeNumber;
use MarcoConsiglio\ModularArithmetic\Ring;

$ring = new Ring(-180, 180);
$moon_longitude = new ModularNumber(60, $ring->length);
$sun_longitude = new ModularNumber(330, $ring->length);
$angular_distance = ModularRelativeNumber::createFromRing(0, $ring);
$angular_distance = $angular_distance->add($sun_longitude->value);
$angular_distance = $angular_distance->add($moon_longitude->value->opposite());

$test = "The sun is at {$sun_longitude->value}°." . PHP_EOL;
$test .= "The moon is at {$moon_longitude->value}°." . PHP_EOL;
$test .= "The angular distance between the two is {$angular_distance->value}°." . PHP_EOL;
```

```
The sun is at 330°.
The moon is at 60°.
The angular distance between the two is -90°.

```

```
$ring = new Ring(-180, 180);
echo "The ring of numbers is a range from {$ring->start} to {$ring->end}." . PHP_EOL;

$a = ModularRelativeNumber::createFromRing(90, $ring);
$b = new Number(180);
$c = new Number(270);

echo "{$a->value} + {$b->value} = {$a->plus($b)->value}" . PHP_EOL;
echo "{$a->value} + {$c->value} = {$a->plus($c)->value}" . PHP_EOL;
```

```
The ring of numbers is a range from -180 to 180.
90 + 180 = -90
90 + 270 = 0

```

API documentation
-----------------

[](#api-documentation)

See more on the API documentation at `./docs/html/index.html`.

###  Health Score

45

—

FairBetter than 91% of packages

Maintenance87

Actively maintained with recent releases

Popularity13

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity59

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 ~11 days

Total

11

Last Release

65d ago

Major Versions

v1.0.0 → v2.0.02026-01-08

v2.0.0 → v3.0.02026-02-22

v3.3.1 → v4.0.02026-04-17

### Community

Maintainers

![](https://www.gravatar.com/avatar/5fb36102dfc597a74e864afc65952e328f158bff88f21ad993c1d79c51c80133?d=identicon)[MarcoConsiglio](/maintainers/MarcoConsiglio)

---

Top Contributors

[![MarcoConsiglio](https://avatars.githubusercontent.com/u/39809954?v=4)](https://github.com/MarcoConsiglio "MarcoConsiglio (75 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisRector

### Embed Badge

![Health badge](/badges/marcoconsiglio-modular-arithmetic/health.svg)

```
[![Health](https://phpackages.com/badges/marcoconsiglio-modular-arithmetic/health.svg)](https://phpackages.com/packages/marcoconsiglio-modular-arithmetic)
```

###  Alternatives

[droptica/droopler

Droopler - SEO Friendly CMS & Site Builder - is a Drupal-based website builder that helps you create beautiful, fast, and easy-to-manage websites

6543.8k1](/packages/droptica-droopler)

PHPackages © 2026

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