README

🇷🇺 Русский · 🇬🇧 English · 🇩🇪 Deutsch · 🇫🇷 Français · 🇪🇸 Español · 🇮🇹 Italiano

CloudCastle Money

Точный value-объект денег для PHP 8.1+: целочисленная арифметика без ошибок плавающей точки, валюты ISO 4217, распределение без потери копеек, семь режимов округления и защита от переполнения. Критично для финтеха.

Установка

composer require cloud-castle/money

Требуется PHP 8.1+ и расширение bcmath.

Быстрый старт

<?php

use CloudCastle\Money\Money;
use CloudCastle\Money\Currency;
use CloudCastle\Money\RoundingMode;

$usd = Currency::of('USD');

$price = Money::of('19.99', $usd);          // 19.99
$total = $price->multipliedBy(3);           // 59.97
$withTax = $price->multipliedBy('1.20');    // 23.99 (округление HalfUp)

// 0.1 + 0.2 в float = 0.30000000000000004; здесь — ровно 0.30.
$sum = Money::of('0.10', $usd)->plus(Money::of('0.20', $usd));   // 0.30

// Распределение без потери копеек: 0.10 на троих → 0.04, 0.03, 0.03.
foreach (Money::of('0.10', $usd)->allocate(1, 1, 1) as $part) {
    echo $part->getAmount() . "\n";
}

// Банковское округление, сравнение, знак.
$half = Money::ofMinor(5, $usd)->dividedBy(2, RoundingMode::HalfEven);   // 0.02
$price->isGreaterThan($sum);                // true

Возможности

Точная арифметика в целых минорных единицах — никаких ошибок float.
Сложение, вычитание, умножение, деление с выбором из 7 режимов округления (HalfUp, HalfEven — банковское, Up, Down, Ceiling, Floor, HalfDown).
Распределение (allocate / allocateTo) по долям без потери и без появления копеек (метод наибольшего остатка).
Валюты ISO 4217: корректное число минорных единиц (JPY — 0, KWD — 3), произвольные валюты через Currency::custom().
Защита от переполнения: выход за целочисленный диапазон бросает исключение, а не искажает сумму молча.
Полное сравнение, предикаты знака, форматирование; иммутабельность.

Сравнение с аналогами

Все таблицы ниже сгенерированы автоматически из честных сравнительных тестов (benchmarks/compare.php) на ОДИНАКОВОЙ операции для всех аналогов, PHP 8.1.34, без Xdebug.

1. Функциональность

Возможность	🏆 CloudCastle	brick	moneyphp	int¹	float¹	bcmath¹
Точная целочисленная арифметика без ошибок float	✅	✅	✅	✅	❌	✅
Распределение без потери копеек (allocate по долям)	✅	✅	✅	❌	❌	❌
Валюты ISO 4217 с проверкой совпадения	✅	✅	✅	❌	❌	❌
Режимы округления (HalfUp/HalfEven/…)	✅	✅	✅	❌	❌	❌
Нулевые внешние зависимости	✅	❌	❌	✅	✅	❌
Всего	🏆 5	4	4	2	1	1

2. Безопасность и корректность

Свойство	🏆 CloudCastle	brick	moneyphp	int¹	float¹	bcmath¹
Иммутабельность value-объекта	✅	✅	✅	❌	❌	❌
Проверка совпадения валют при операциях	✅	✅	✅	❌	❌	❌
Обнаружение переполнения (throw, не тихое искажение)	✅	✅	✅	❌	❌	✅
Распределение сохраняет полную сумму (нет потерянных копеек)	✅	✅	✅	✅	❌	❌
Нулевые внешние зависимости (меньше поверхность атаки)	✅	❌	❌	✅	✅	❌
Всего	🏆 5	4	4	2	1	1

3. Производительность

Создание суммы + allocate 1:1:1, 100 000 раз (минимум из 4).

Решение	Время (мс)	Итог
float¹	11,2	базовый уровень (не библиотека)
int¹	11,4	базовый уровень (не библиотека)
bcmath¹	33	базовый уровень (не библиотека)
🏆 CloudCastle	639,7	быстрейшее среди библиотек
moneyphp	1 119,7	аналог
brick	5 115	аналог

4. Потребление памяти

Пик памяти на 100 000 операций (изолированный процесс, только целевая библиотека).

Решение	Пиковая память (KB)	Итог
🏆 CloudCastle	6 962	легчайшее среди библиотек
moneyphp	6 962	аналог
int¹	6 962	базовый уровень (не библиотека)
float¹	6 962	базовый уровень (не библиотека)
bcmath¹	6 962	базовый уровень (не библиотека)
brick	7 152	аналог

¹ Базовый уровень (нативные вызовы/примитивы без полноты решения) показан для контекста и не претендует на победу среди библиотек-аналогов.

_{Нативные подходы (baseline): float ТЕРЯЕТ копейку при делении (33.33×3=99.99),
целые и bcmath без наивной раздачи остатка тоже теряют; из них лишь ручная целая
раздача корректна, но без валют, округления и защиты value-объекта. brick/money
использует произвольную точность (BigNumber) — корректно, но в разы медленнее
нативной целочисленной арифметики cloud-castle. Память измеряется в изоляции.}

Вывод: CloudCastle Money — самый быстрый среди money-библиотек (native-int арифметика против BigNumber у brick и строк у moneyphp), самый лёгкий по памяти, с точным распределением без потери копеек, режимами округления, защитой от переполнения и нулевыми внешними зависимостями.

Разработка

composer install
composer check    # линтеры + статический анализ + тесты
composer fix      # автоисправления (Rector, PHP CS Fixer, PHPCBF)
composer ci       # полный CI-пайплайн локально

Полный список команд с описаниями: composer run-script --list.

Документация

Репозиторий: https://gitverse.ru/cloud-castle/money
История изменений: CHANGELOG.md
Как внести вклад: CONTRIBUTING.md
Кодекс поведения: CODE_OF_CONDUCT.md
Политика безопасности: SECURITY.md

Лицензия