README

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

CloudCastle UnitConvertor

Конвертер единиц измерения для PHP 8.1+: 96 категорий и 560+ единиц (СИ, имперские, США, морские, астрономические, исторические русские), размерностный анализ величин (10 м / 2 с = 5 м/с), физически корректные температуры (8 шкал + дельты Δ°C), составные величины («5 ft 3 in»), динамические SI/IEC-префиксы (кветто…кветта, KiB…YiB), произвольная точность на cloud-castle/match, внешние справочники единиц, локализация на 6 языков с плюрализацией, парсинг и форматирование. Единственная runtime-зависимость — cloud-castle/match.

Установка

composer require cloud-castle/unit-convertor

Требуется PHP 8.1+ (проверено вплоть до 8.5).

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

<?php

use CloudCastle\UnitConvertor\Converter;
use CloudCastle\UnitConvertor\Quantity;

$converter = new Converter();

// Простая конверсия — 0.2 мкс на операцию после прогрева пары
$converter->convert(5, 'km', 'mi');            // 3.10685596…
$converter->convert(100, 'celsius', 'fahrenheit'); // 212.0
$converter->convert(8, 'L/100km', 'mpg_us');   // 29.4018… (нелинейная)
$converter->convert(1, 'GiB', 'MB');           // 1073.741824 (IEC ↔ СИ)
$converter->convert(1, 'кВтч', 'Дж');          // русские алиасы работают

// Величины-объекты: иммутабельные, с арифметикой и размерностным анализом
$speed = Quantity::of(100, 'km')->div(Quantity::of(2, 'h'));
$speed->code();                                 // 'm/s'
$speed->to('km/h')->value();                    // 50.0

// Физически корректные температуры
Quantity::of(30, 'celsius')->sub(Quantity::of(20, 'celsius')); // 10 Δ°C
Quantity::of(20, 'celsius')->add(Quantity::of(18, 'delta_fahrenheit')); // 30 °C
// Quantity::of(30, 'celsius')->add(Quantity::of(20, 'celsius')); — исключение!

// Парсинг, разложение, форматирование
Quantity::parse('5 ft 3 in')->to('cm')->value();          // 160.02
Quantity::of(5025, 's')->toCompound(['h', 'min', 's']);   // 1 ч 23 мин 45 с
Quantity::of(1500, 'm')->humanize();                      // «1,5 км»
Quantity::of(5, 'km')->format(1, 'ru', long: true);       // «5 километров»

// Произвольная точность (BCMath через cloud-castle/match)
$converter->convertPrecise('1', 'ly', 'km'); // '9460730472580.8' — точно

Возможности

96 категорий, 560+ единиц из коробки — от длины и массы до дозиметрии (мкЗв/ч, пКи/л), молярных концентраций (°dH жёсткости воды), темпа бега (мин/км), газовых отметок духовки и русских исторических мер (пуд, аршин, верста). Полный список — в wiki.
Размерностный анализ: умножение и деление величин выводит размерность результата; произведение силы на длину само становится джоулями, а неизвестные размерности синтезируются на лету.
Физическая корректность температур: 8 шкал (включая Реомюра, Делиля, Рёмера), дельта-единицы, запрет бессмысленных операций.
Динамические префиксы: любые СИ-приставки от кветто (10⁻³⁰) до кветта (10³⁰) и IEC-приставки KiB…YiB — без раздувания данных, с точными строковыми множителями.
Внешние справочники: свой каталог данных, attachSource() поверх встроенного, программные категории registerCategory() — с генератором индексов IndexBuilder и защитой от перехвата чужих кодов.
Локализация: символы и имена единиц на 6 языках с корректной плюрализацией («5,5 километра», «2 kilometres», «1,5 kilomètre»).
Произвольная точность: convertPrecise() на BigDecimal из cloud-castle/match — 100 знаков после запятой.
Скорость: pair-кэш сводит линейную конверсию к одному умножению и сложению — ~0.2 мкс на операцию.

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

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

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

Легенда: ✅ полная поддержка · ⚠️ частичная · ❌ нет · «н/д» — неприменимо.

Возможность	🏆 unit-convertor	jordanbrauer	php-units-of-measure	crisu83	cartalyst	measurements	🏆 Победитель
Категории из коробки (96)	✅ 96	⚠️ 13	⚠️ 16	⚠️ 20	❌ 0 (конфиг)	⚠️ 22	unit-convertor
Единицы из коробки (559+)	✅ 559	⚠️ ~150	⚠️ ~100	⚠️ ~80	❌ 0 (конфиг)	⚠️ ~170	unit-convertor
Динамические СИ-префиксы (кветто…кветта)	✅	❌	⚠️ метрические	❌	❌	❌	unit-convertor
IEC-префиксы данных (KiB…YiB)	✅	⚠️ часть	❌	⚠️ часть	❌	❌	unit-convertor
Температурные шкалы	✅ 8+дельты	⚠️ 4	⚠️ 5	⚠️ 4	❌	⚠️ 4	unit-convertor
Дельта-температуры (Δ°C ≠ °C)	✅	❌	❌	❌	❌	❌	unit-convertor
Защита аффинной арифметики	✅	❌	❌	❌	❌	❌	unit-convertor
Размерностный анализ (м/с из м и с)	✅	❌	❌	❌	❌	⚠️ юнит-опер.	unit-convertor
Кросс-категорийные конверсии (Дж ↔ Н·м)	✅	❌	❌	❌	❌	❌	unit-convertor
Нелинейные единицы (л/100км ↔ mpg)	✅	✅	❌	⚠️	❌	⚠️ обратн.	unit-convertor
Парсинг строк («5.5 km»)	✅	❌	❌	❌	❌	❌	unit-convertor
Составные величины («5 ft 3 in»)	✅	❌	❌	❌	❌	❌	unit-convertor
Разложение toCompound (1 ч 23 мин 45 с)	✅	❌	❌	❌	❌	❌	unit-convertor
Локализация имён (6 языков, плюрализация)	✅	❌	❌	❌	⚠️ формат	❌	unit-convertor
Произвольная точность вычислений	✅ match	✅ bcmath	❌	❌	❌	❌	unit-convertor
Иммутабельные величины	✅	❌	✅	✅	❌	✅	unit-convertor
Арифметика величин (add/sub/mul/div)	✅	❌	⚠️ add/sub	⚠️ add/sub	❌	✅	unit-convertor
Агрегаты (sum/min/max/avg)	✅	❌	❌	❌	❌	❌	unit-convertor
Сравнения величин (gt/lt/eq с допуском)	✅	❌	❌	❌	❌	✅	unit-convertor
Авто-подбор единицы (1500 м → 1.5 км)	✅	❌	❌	❌	❌	❌	unit-convertor
Пользовательские единицы	✅	✅	✅	❌	✅	✅	unit-convertor
Внешние каталоги-справочники	✅	❌	❌	❌	⚠️ конфиг	❌	unit-convertor
Программные категории	✅	✅	✅	❌	✅	✅	unit-convertor
Подсказки при опечатке	✅	❌	❌	❌	❌	❌	unit-convertor
Сериализация JSON/массив	✅	❌	❌	⚠️ строка	❌	❌	unit-convertor
Русские исторические единицы	✅	❌	❌	❌	❌	❌	unit-convertor
Всего ✅	🏆 26	4	3	1	2	5	unit-convertor

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

Микросекунды на операцию (меньше — лучше); минимум из 2 прогонов по 4000 итераций.

Библиотека	Длина: м → см	Температура: °C → °F	🏆 Победитель
🏆 unit-convertor	0.590	0.525	🏆 unit-convertor
jordanbrauer	12.732	17.515	—
php-units-of-measure	2.950	1.760	—
crisu83	1.787	н/д¹	—
cartalyst	8.805	н/д¹	—
measurements	6.280	2.656	—

¹ cartalyst/converter не поддерживает смещение температурных шкал; crisu83/php-conversion конвертирует температуры линейно и выдаёт физически неверные значения (проверено: 100 °C → 106.96 «°F») — в температурном сценарии обе честно исключены.

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

Рабочий footprint (КБ): создание конвертера + первая конверсия, изолированный процесс на каждый замер.

Библиотека	Длина: м → см	Температура: °C → °F	🏆 Победитель
🏆 unit-convertor	361.0	331.0	—
jordanbrauer	904.2	908.8	—
php-units-of-measure	137.1	135.0	—
crisu83	20.0	н/д¹	🏆 crisu83
cartalyst	104.5	н/д¹	—
measurements	89.3	70.6	—

Честный компромисс: footprint unit-convertor выше лёгких аналогов — это цена 96 категорий и 559 единиц с полным индексом кодов против 8–20 категорий у соперников; при этом он ниже, чем у jordanbrauer/unit-converter. Приоритет пакета — функциональность, корректность и скорость.

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

Свойство	🏆 unit-convertor	jordanbrauer	php-units-of-measure	crisu83	cartalyst	measurements	🏆 Победитель
Лимит длины разбираемых строк (анти-DoS)	✅	—¹	—¹	—¹	—¹	—¹	unit-convertor
Типизированные исключения на весь ввод	✅	⚠️	⚠️	⚠️	⚠️	✅	unit-convertor
Отказ от NAN/INF на входе	✅	❌	❌	❌	❌	❌	unit-convertor
Защита каталога локалей (нормализация кода)	✅	—¹	—¹	—¹	—¹	—¹	unit-convertor
Изоляция чужих справочников (коды не перехватываются)	✅	—¹	—¹	—¹	—¹	—¹	unit-convertor
Физическая корректность (аффинные шкалы, дельты)	✅	❌	❌	❌	❌	❌	unit-convertor
Runtime-зависимости (меньше — уже поверхность)	✅ 1 (cloud-castle/match)	✅ 0	✅ 0	✅ 0	⚠️ 2+	✅ 0	unit-convertor

¹ «—» — свойство неприменимо: у библиотеки нет разбора строк, локалей или внешних справочников.

5. Качество кода

Метрика	🏆 unit-convertor	jordanbrauer	php-units-of-measure	crisu83	cartalyst	measurements	🏆 Победитель
PHPStan	max + strict-rules	level 8?	—	—	—	—	unit-convertor
Psalm (level 1, unused-код)	✅	—	—	—	—	—	unit-convertor
Покрытие строк	100%	~90%	~95%	высокое	—	высокое	unit-convertor
Мутационное тестирование (MSI)	100%	—	—	—	—	—	unit-convertor
PHPMD + Deptrac (слои)	✅	—	—	—	—	—	unit-convertor
Поддержка PHP 8.5	✅	⚠️	⚠️	⚠️	⚠️ (≥8.3 в v10)	⚠️	unit-convertor

Честно о плюсах и минусах

Плюсы:

функциональный суперсет всех сравниваемых аналогов вместе взятых (см. таблицу выше: единственный со строковым парсингом, размерностным анализом, дельта-температурами, локализацией и внешними справочниками);
самая высокая производительность среди аналогов — в 2.3–30 раз быстрее;
100 % покрытие строк и 100 % MSI мутационного тестирования; PHPStan max + strict, Psalm level 1, Deptrac-слои;
физическая корректность там, где аналоги молча считают неверно (линейные «температуры» crisu83, отсутствие offset у cartalyst).

Минусы:

пакет моложе и менее распространён, чем аналоги (меньше звёзд, установок и практики сообщества);
рабочий footprint (~450 КБ) выше лёгких аналогов — цена 96 категорий и полного индекса кодов; если нужна пара конверсий длины в микросервисе с жёстким лимитом памяти, легковес может подойти лучше;
режим произвольной точности тянет cloud-castle/match (ext-bcmath).

Когда и где применять

E-commerce, логистика, доставка — габариты и вес в разных системах, «5 ft 3 in» из американских карточек товара, локализованный вывод.
IoT и телеметрия — датчики в смешанных единицах, температурные дельты без физических ошибок, mkЗв/ч и Бк/м³ для радиометрии.
Финтех и биллинг ресурсов — convertPrecise() для тарификации энергии (кВт·ч ↔ Дж) без накопления float-погрешности.
Медицина и лаборатории — мг/дл, ммоль/л, °dH, МЕ ферментов; строгие исключения вместо тихих ошибок.
Автомобильные сервисы — расход л/100км ↔ mpg (US/UK), крутящий момент Н·м ↔ lbf·ft, давление шин.
Контент и переводы — 6 локалей с плюрализацией, русские исторические меры для образовательных и музейных проектов.
Когда не стоит: нужен неизменяемый набор из двух-трёх фиксированных коэффициентов в скрипте на 20 строк — хватит и умножения на константу.

Разработка

composer install
composer check    # линтеры + статический анализ + тесты
composer fix      # автоисправления (Rector, PHP CS Fixer, PHPCBF)
composer ci       # полный CI-пайплайн локально
composer infection            # мутационное тестирование (MSI 100%)
composer docs:build           # пересборка сравнительных таблиц
php tools/build-index.php     # пересборка индекса данных

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

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

Wiki (6 языков): wiki/docs/ru/Home.md
Репозиторий: https://gitverse.ru/cloud-castle/unit-convertor
История изменений: CHANGELOG.md
Как внести вклад: CONTRIBUTING.md
Кодекс поведения: CODE_OF_CONDUCT.md
Политика безопасности: SECURITY.md

Лицензия