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.

v3.3.1(1mo ago)0441MITPHPPHP ^8.4

Since Jan 4Pushed 1mo 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 1mo ago

READMEChangelog (9)Dependencies (10)Versions (11)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/879743ec562556168e1d580d970810f25f49194f7370452b5cf10a8281341418/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d76332e332e312d7768697465)](https://camo.githubusercontent.com/879743ec562556168e1d580d970810f25f49194f7370452b5cf10a8281341418/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d76332e332e312d7768697465)
[![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.

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

[](#requirement)

- PHP ^8.4

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

[](#installation)

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

Usage
-----

[](#usage)

Construct a modular number with its modulus.

```
use Marcoconsiglio\ModularArithmetic\ModularInteger;

$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.

```

Modular Arithmetic
------------------

[](#modular-arithmetic-1)

### 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);
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

```

Error Exceptions
----------------

[](#error-exceptions)

### DifferentModulusError

[](#differentmoduluserror)

This error is thrown when you try to perform an arithmetic operation using two `ModularInteger` with different modulus.

```
use Marcoconsiglio\ModularArithmetic\ModularNumber;

$a = new ModularNumber(3, 7);
$b = new ModularNumber(5, 12);
$sum = $a->add($b); // Throws DifferentModulusError
```

```
Marcoconsiglio\ModularArithmetic\Exceptions\DifferentModulusError: Two different modulus cannot be used (7 and 12).

```

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

[](#api-documentation)

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

###  Health Score

45

—

FairBetter than 92% of packages

Maintenance92

Actively maintained with recent releases

Popularity11

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity58

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

Total

9

Last Release

40d ago

Major Versions

v1.0.0 → v2.0.02026-01-08

v2.0.0 → v3.0.02026-02-22

### 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 (73 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

[yahnis-elsts/plugin-update-checker

A custom update checker for WordPress plugins and themes. Useful if you can't host your plugin in the official WP repository but still want it to support automatic updates.

2.5k1.5M79](/packages/yahnis-elsts-plugin-update-checker)[2bj/phanybar

Control AnyBar from your php

627.4M2](/packages/2bj-phanybar)[ghanem/rating

Rating system for Laravel

8615.5k](/packages/ghanem-rating)[microman/kirby-column-blocks

Use columns in block fields based on the layout field.

422.5k](/packages/microman-kirby-column-blocks)[bangerkuwranger/magento-2-1-3-category-limit-bug-workaround

Workaround for bug from v2.1.3 that arbitrarily limits indexed products in category to 500

1414.0k](/packages/bangerkuwranger-magento-2-1-3-category-limit-bug-workaround)

PHPackages © 2026

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