PHPackages galaxon/quantities - 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. galaxon/quantities ActiveLibrary[Utility & Helpers](/categories/utility) galaxon/quantities ================== Contains classes for working with measurements such as angles, lengths, etc. v1.1.0(1mo ago)01↓92.3%MITPHPPHP ^8.4 Since Feb 13Pushed 2w agoCompare [ Source](https://github.com/mossy2100/Galaxon-PHP-Quantities)[ Packagist](https://packagist.org/packages/galaxon/quantities)[ RSS](/packages/galaxon-quantities/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (12)Versions (5)Used By (0) OceanMoon PHP Quantities ======================== [](#oceanmoon-php-quantities) This package enables calculations and conversions with physical and non-physical quantities, including support for SI and other systems of units (including data and currencies), metric and binary prefixes, parsing, and formatting. **[License](LICENSE)** | **[Changelog](CHANGELOG.md)** | **[Documentation](docs/)** | **[Examples](docs/WorkingWithQuantities/CalculationExamples.md)** [![PHP 8.4](docs/logo_php8_4.png)](docs/logo_php8_4.png) --- Description ----------- [](#description) This package provides strongly-typed classes for physical quantities (length, mass, time, temperature, etc.) and some non-physical quantities (data, money), with comprehensive unit conversion capabilities. The system automatically finds conversion factors between compatible units, supports metric and binary prefixes, handles offsets for temperature scales, and loads the latest currency exchange rates automatically. Key capabilities include: - **Type-safe measurements**: Each measurement type (Length, Mass, Time, etc.) is a separate class. Plus, you can easily create your own custom quantity type classes. - **Automatic conversion**: Easily convert between any compatible units, with most common units built-in, including SI, imperial, US customary, scientific, nautical, CSS, and currencies. - **Prefix support**: Full support for SI metric and binary prefixes. - **Arithmetic operations**: Add, subtract, multiply, and divide quantities with automatic unit handling. - **Flexible parsing**: Parse strings like `123.45 km/h`, `90deg`, or `25°C` into Quantity objects. - **String formatting**: Format quantities as ASCII or Unicode, with configurable decimal places and locale-specific currency formatting. - **Part decomposition**: Break measurements into components (e.g. `12° 34′ 56″` or `1y 3mo 2d`). - **Physical constants**: Built-in constants like the speed of light, Planck's constant, and Avogadro's number as Quantity objects. - **Up-to-date exchange rates**: Updated automatically as needed using the exchange rate API of your choice. --- Development and Quality Assurance --------------------------------- [](#development-and-quality-assurance) [Claude Chat](https://claude.ai) and [Claude Code](https://www.claude.com/product/claude-code) were used in the development of this package. The core classes were designed, coded, and commented primarily by the author, with Claude providing assistance with code reviews, debugging, and generating tests and documentation. All code was thoroughly reviewed by the author, and validated using industry-standard tools including [PHP\_Codesniffer](https://github.com/PHPCSStandards/PHP_CodeSniffer/), [PHPStan](https://phpstan.org/) (to level 9), and [PHPUnit](https://phpunit.de/index.html) to ensure full compliance with [PSR-12](https://www.php-fig.org/psr/psr-12/) coding standards and comprehensive unit testing with 100% code coverage. This collaborative approach has produced a well-designed, production-ready package with thorough test coverage and documentation. [![Code Coverage](https://camo.githubusercontent.com/32855e94577df9d0a30995653b17d33a5fbfdf644518f96ea0374313397d19b7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f7665726167652d3130302532352d627269676874677265656e)](https://camo.githubusercontent.com/32855e94577df9d0a30995653b17d33a5fbfdf644518f96ea0374313397d19b7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f7665726167652d3130302532352d627269676874677265656e) --- Requirements ------------ [](#requirements) - PHP ^8.4 - oceanmoon/core --- Installation ------------ [](#installation) ``` composer require oceanmoon/quantities ``` --- Quick start ----------- [](#quick-start) ``` use OceanMoon\Quantities\PhysicalConstant; use OceanMoon\Quantities\QuantityType\Angle; use OceanMoon\Quantities\QuantityType\Force; use OceanMoon\Quantities\QuantityType\Frequency; use OceanMoon\Quantities\QuantityType\Length; use OceanMoon\Quantities\QuantityType\Mass; use OceanMoon\Quantities\QuantityType\Money; use OceanMoon\Quantities\QuantityType\Temperature; // Create measurements $distance = new Length(5, 'km'); $temp = new Temperature(25, 'degC'); $angle = new Angle(90, 'deg'); $price = new Money(4269, 'EUR'); // Convert between units $miles = $distance->to('mi'); // 3.10686... miles $fahrenheit = $temp->to('degF'); // 77°F $radians = $angle->to('rad'); // 1.5707... rad $dollars = $price->to('USD'); // e.g. 4621 USD // Convert to SI units $force = new Force(28000, 'lbf'); $force = $force->toSi(); // 124... kN $force = $force->toSiBase(); // 124550... kg⋅m/s² // Arithmetic operations $total = $distance->add(new Length(500, 'm')); // 5.5 km $doubled = $distance->mul(2.0); // 10 km $period = new Frequency(2.4, 'GHz')->inv()->toSi(); // 416.7... ps // Physical constants $h = PhysicalConstant::planck(); $c = PhysicalConstant::speedOfLight(); // Scientific and engineering calculations $G = PhysicalConstant::gravitational(); $earthMass = new Mass(5.972e24, 'kg'); $moonMass = new Mass(7.342e22, 'kg'); $earthMoonDistance = new Length(3.844e8, 'm'); $gravity = $G->mul($earthMass)->mul($moonMass)->div($earthMoonDistance->sqr()); echo $gravity->to('N')->format('e', 2), "\n"; // 1.98×10²⁰ N // Parse from strings $length = Length::parse('123.45 km'); $temp = Temperature::parse('98.6°F'); $angle = Angle::parse("45° 30' 15\""); // Format as parts $angle = new Angle(45.5042, 'deg'); echo $angle->formatParts(precision: 1); // "45° 30′ 15.1″" ``` --- Concepts -------- [](#concepts) Background on the domain model and how the library represents physical measurements. 1. **[Terminology](docs/Concepts/Terminology.md)** — Key terms and definitions used throughout the library. 2. **[Dimensions and Base Units](docs/Concepts/DimensionsAndBaseUnits.md)** — Dimension codes, base units, and how the library tracks physical dimensions. 3. **[Quantity Types](docs/Concepts/QuantityTypes.md)** — Typed quantity classes like Length, Mass, and Force, and how they map to dimensions. 4. **[Prefixes](docs/Concepts/Prefixes.md)** — Metric, engineering, and binary prefixes for scaling units. 5. **[Units](docs/Concepts/Units.md)** — Unit symbol conventions, notation rules, and supported non-ASCII and alternate symbols. 6. **[Physical Constants](docs/Concepts/PhysicalConstants.md)** — Built-in physical constants as Quantity objects. --- Working with Quantities ----------------------- [](#working-with-quantities) Practical guides for using the library in your code. 1. **[Creating Quantities](docs/WorkingWithQuantities/CreatingQuantities.md)** — Creating new quantities with constructors and the factory method. 2. **[Unit Conversion](docs/WorkingWithQuantities/UnitConversion.md)** — Converting between units, expansion, simplification, and auto-prefixing. 3. **[Arithmetic Operations](docs/WorkingWithQuantities/ArithmeticOperations.md)** — Add, subtract, multiply, and divide quantities. 4. **[Calculation Examples](docs/WorkingWithQuantities/CalculationExamples.md)** — Real-world physics and engineering calculations. 5. **[Currency Calculations](docs/WorkingWithQuantities/CurrencyCalculations.md)** — Example conversions and calculations involving currencies. 6. **[Comparison Functions](docs/WorkingWithQuantities/ComparisonFunctions.md)** — Exact and approximate equality, ordering, and tolerances. 7. **[String Functions](docs/WorkingWithQuantities/StringFunctions.md)** — Parsing strings into quantities and formatting output (ASCII and Unicode). 8. **[Part Decomposition](docs/WorkingWithQuantities/PartDecomposition.md)** — Working with quantities as parts (e.g. 45° 30′ 15″ or 1h 30min 45s). 9. **[Customization](docs/WorkingWithQuantities/Customization.md)** — Adding custom units, conversions, and quantity type classes. --- Reference --------- [](#reference) ### Main Public API [](#main-public-api) Other than the quantity type classes (below), these are the main classes you'll use. ClassDescription[Quantity](docs/Reference/Quantity.md)Base class for all measurement types. Provides unit conversion, arithmetic operations, comparison, formatting, and part decomposition.[PhysicalConstant](docs/Reference/PhysicalConstant.md)Access to physical constants (speed of light, Planck constant, etc.) as Quantity objects.### Quantity Types [](#quantity-types) All quantity type classes extend `Quantity` and define their specific units and conversions. See the **[Quantity Type reference](docs/Reference/QuantityType/)** for the complete list of built-in units for each type. ClassDimensionSI or common base unitDescription[Acceleration](docs/Reference/QuantityType/Acceleration.md)T-2Lm/s²Rate of change of velocity.[AmountOfSubstance](docs/Reference/QuantityType/AmountOfSubstance.md)NmolSI base quantity for counting entities.[Angle](docs/Reference/QuantityType/Angle.md)AradAngular measurements with trig functions.[Area](docs/Reference/QuantityType/Area.md)L2m²Two-dimensional extent.[Capacitance](docs/Reference/QuantityType/Capacitance.md)T4L-2M-1I2FAbility to store electric charge.[CatalyticActivity](docs/Reference/QuantityType/CatalyticActivity.md)T-1NkatRate of catalysis.[Conductance](docs/Reference/QuantityType/Conductance.md)T3L-2M-1I2SElectrical conductance.[Data](docs/Reference/QuantityType/Data.md)DBDigital storage with metric and binary prefixes.[Density](docs/Reference/QuantityType/Density.md)L-3Mkg/m³Mass per unit volume.[Dimensionless](docs/Reference/QuantityType/Dimensionless.md)*empty**empty*Ratios, percentages, and pure numbers.[ElectricCharge](docs/Reference/QuantityType/ElectricCharge.md)TICQuantity of electricity.[ElectricCurrent](docs/Reference/QuantityType/ElectricCurrent.md)IASI base quantity for electric current.[Energy](docs/Reference/QuantityType/Energy.md)T-2L2MJCapacity to do work.[Force](docs/Reference/QuantityType/Force.md)T-2LMNInteraction causing acceleration.[Frequency](docs/Reference/QuantityType/Frequency.md)T-1Hz, BqCycles per unit time.[Illuminance](docs/Reference/QuantityType/Illuminance.md)L-2JA2lxLuminous flux per area.[Inductance](docs/Reference/QuantityType/Inductance.md)T-2L2MI-2HProperty opposing current change.[Length](docs/Reference/QuantityType/Length.md)LmSI base quantity for distance.[LuminousFlux](docs/Reference/QuantityType/LuminousFlux.md)JA2lmPerceived light power.[LuminousIntensity](docs/Reference/QuantityType/LuminousIntensity.md)JcdSI base quantity for luminous intensity.[MagneticFlux](docs/Reference/QuantityType/MagneticFlux.md)T-2L2MI-1WbTotal magnetic field through surface.[MagneticFluxDensity](docs/Reference/QuantityType/MagneticFluxDensity.md)T-2MI-1TMagnetic field strength.[Mass](docs/Reference/QuantityType/Mass.md)MkgSI base quantity for mass.[Money](docs/Reference/QuantityType/Money.md)CXAUCurrency conversions and calculations.[Power](docs/Reference/QuantityType/Power.md)T-3L2MWRate of energy transfer.[Pressure](docs/Reference/QuantityType/Pressure.md)T-2L-1MPaForce per unit area.[RadiationDose](docs/Reference/QuantityType/RadiationDose.md)T-2L2Gy, SvAbsorbed and equivalent radiation dose.[Resistance](docs/Reference/QuantityType/Resistance.md)T-3L2MI-2ΩOpposition to electric current.[SolidAngle](docs/Reference/QuantityType/SolidAngle.md)A2srThree-dimensional angular extent.[Temperature](docs/Reference/QuantityType/Temperature.md)HKSI base quantity with affine conversions.[Time](docs/Reference/QuantityType/Time.md)TsSI base quantity for duration.[Velocity](docs/Reference/QuantityType/Velocity.md)T-1Lm/sRate of change of position.[Voltage](docs/Reference/QuantityType/Voltage.md)T-3L2MI-1VElectric potential difference.[Volume](docs/Reference/QuantityType/Volume.md)L3m³Three-dimensional extent.### Services [](#services) These classes are predominantly internal, except for adding custom units via `UnitService::add()`, or registering new quantity types via `QuantityTypeService::add()`. ClassDescription[ConversionService](docs/Reference/Services/ConversionService.md)Manages unit conversions and converters.[DimensionService](docs/Reference/Services/DimensionService.md)Utilities for working with physical dimension codes (validation, composition, transformation).[PrefixService](docs/Reference/Services/PrefixService.md)Manages SI and binary prefixes (lookup, filtering by group).[QuantityTypeService](docs/Reference/Services/QuantityTypeService.md)Registry of quantity types keyed by dimension code.[UnitService](docs/Reference/Services/UnitService.md)Registry of units with lookup, filtering, and loading by system.### Internal Types [](#internal-types) These types provide the core functionality of the library and will typically not be used directly by end-users. #### Classes [](#classes) NameDescription[Unit](docs/Reference/Internal/Unit.md)Represents a single-symbol measurement unit with optional prefix support.[UnitTerm](docs/Reference/Internal/UnitTerm.md)A unit with optional prefix and exponent (e.g., km², ms⁻¹).[CompoundUnit](docs/Reference/Internal/CompoundUnit.md)Compound unit expression combining unit terms via multiplication/division.[Prefix](docs/Reference/Internal/Prefix.md)SI metric and binary prefixes (kilo, mega, kibi, etc.).[Conversion](docs/Reference/Internal/Conversion.md)Represents a unit conversion with factor and error tracking.[Converter](docs/Reference/Internal/Converter.md)Graph-based algorithm for finding conversion paths between units.[FloatWithError](docs/Reference/Internal/FloatWithError.md)Floating-point numbers with tracked error bounds for precision monitoring.[QuantityType](docs/Reference/Internal/QuantityType.md)Data class representing a quantity type with its dimension, SI unit, and PHP class.#### Interfaces [](#interfaces) NameDescription[UnitInterface](docs/Reference/Internal/UnitInterface.md)Interface implemented by Unit, UnitTerm, and CompoundUnit.#### Enums [](#enums) NameDescription[UnitSystem](docs/Reference/Internal/UnitSystem.md)Enum for systems of units (SI, Imperial, US Customary, etc.).### Exceptions [](#exceptions) Custom exception types to provide additional context when needed. Both extend `DomainException`, as they relate to provided values being outside a valid domain. ClassDescription[UnknownUnitException](docs/Reference/Exceptions/UnknownUnitException.md)Thrown when a unit symbol cannot be resolved.[DimensionMismatchException](docs/Reference/Exceptions/DimensionMismatchException.md)Thrown when units have incompatible dimensions.### Currency Classes [](#currency-classes) Classes for currency data management and exchange rate integration. ClassDescription[CurrencyService](docs/Reference/Currencies/CurrencyService.md)Manages currency unit data and exchange rate conversions.[ExchangeRateServiceInterface](docs/Reference/Currencies/ExchangeRateServices/ExchangeRateServiceInterface.md)Contract for exchange rate providers.[CurrencyLayerService](docs/Reference/Currencies/ExchangeRateServices/CurrencyLayerService.md)CurrencyLayer API (USD-based, 1,000 req/month free).[ExchangeRateApiService](docs/Reference/Currencies/ExchangeRateServices/ExchangeRateApiService.md)ExchangeRate-API (any base currency, 1,500 req/month free).[FixerService](docs/Reference/Currencies/ExchangeRateServices/FixerService.md)Fixer.io API (EUR-based, 10,000 req/month free).[FrankfurterService](docs/Reference/Currencies/ExchangeRateServices/FrankfurterService.md)Frankfurter API (ECB data, completely free, no API key).[OpenExchangeRatesService](docs/Reference/Currencies/ExchangeRateServices/OpenExchangeRatesService.md)Open Exchange Rates API (USD-based, free tier available).--- Testing ------- [](#testing) The library includes comprehensive test coverage: ``` # Run all tests vendor/bin/phpunit # Run a specific test file vendor/bin/phpunit tests/Quantity/QuantityArithmeticTest.php # Run tests matching a filter vendor/bin/phpunit --filter=testCompare # Run with coverage (generates HTML report and clover.xml) composer test ``` --- License ------- [](#license) MIT License - see [LICENSE](LICENSE) for details --- Support ------- [](#support) - **Issues**: - **Documentation**: See [docs/](docs/) directory for detailed class documentation For questions or suggestions, please [open an issue](https://github.com/mossy2100/PHP-Quantities/issues). --- Changelog --------- [](#changelog) See [CHANGELOG.md](CHANGELOG.md) for version history and changes. ### Health Score 41 — FairBetter than 87% of packages Maintenance93 Actively maintained with recent releases Popularity1 Limited adoption so far Community8 Small or concentrated contributor base Maturity55 Maturing project, gaining track record Bus Factor1 Top contributor holds 99.1% 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 ~28 days Total 4 Last Release 53d ago Major Versions v0.2.0 → v1.0.02026-04-09 ### Community Maintainers ![](https://www.gravatar.com/avatar/6f9cd1bb5c1b12882db4cb82161c1b5a22e1ccbad8845a54a6ae591647e88c07?d=identicon)[mossy2100](/maintainers/mossy2100) --- Top Contributors [![mossy2100](https://avatars.githubusercontent.com/u/371497?v=4)](https://github.com/mossy2100 "mossy2100 (116 commits)")[![claude](https://avatars.githubusercontent.com/u/81847?v=4)](https://github.com/claude "claude (1 commits)") ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP\_CodeSniffer Type Coverage Yes ### Embed Badge ![Health badge](/badges/galaxon-quantities/health.svg) ``` [![Health](https://phpackages.com/badges/galaxon-quantities/health.svg)](https://phpackages.com/packages/galaxon-quantities) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)