Download the PHP package oceanmoon/quantities without Composer

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.

Examples

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

Claude Chat and 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, PHPStan (to level 9), and PHPUnit to ensure full compliance with 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.

Requirements

• PHP ^8.4
• oceanmoon/core

Installation

Quick start

Concepts

Background on the domain model and how the library represents physical measurements.

1. Terminology — Key terms and definitions used throughout the library.
2. Dimensions and Base Units — Dimension codes, base units, and how the library tracks physical dimensions.
3. Quantity Types — Typed quantity classes like Length, Mass, and Force, and how they map to dimensions.
4. Prefixes — Metric, engineering, and binary prefixes for scaling units.
5. Units — Unit symbol conventions, notation rules, and supported non-ASCII and alternate symbols.
6. Physical Constants — Built-in physical constants as Quantity objects.

Working with Quantities

Practical guides for using the library in your code.

1. Creating Quantities — Creating new quantities with constructors and the factory method.
2. Unit Conversion — Converting between units, expansion, simplification, and auto-prefixing.
3. Arithmetic Operations — Add, subtract, multiply, and divide quantities.
4. Calculation Examples — Real-world physics and engineering calculations.
5. Currency Calculations — Example conversions and calculations involving currencies.
6. Comparison Functions — Exact and approximate equality, ordering, and tolerances.
7. String Functions — Parsing strings into quantities and formatting output (ASCII and Unicode).
8. Part Decomposition — Working with quantities as parts (e.g. 45° 30′ 15″ or 1h 30min 45s).
9. Customization — Adding custom units, conversions, and quantity type classes.

Reference

Main Public API

Other than the quantity type classes (below), these are the main classes you'll use.

Quantity Types

All quantity type classes extend Quantity and define their specific units and conversions. See the Quantity Type reference for the complete list of built-in units for each type.

Services

These classes are predominantly internal, except for adding custom units via UnitService::add(), or registering new quantity types via QuantityTypeService::add().

Internal Types

These types provide the core functionality of the library and will typically not be used directly by end-users.

Classes

Interfaces

Enums

Exceptions

Custom exception types to provide additional context when needed. Both extend DomainException, as they relate to provided values being outside a valid domain.

Currency Classes

Classes for currency data management and exchange rate integration.

Testing

The library includes comprehensive test coverage:

License

MIT License - see LICENSE for details

Support

• Issues: https://github.com/mossy2100/PHP-Quantities/issues
• Documentation: See docs/ directory for detailed class documentation

For questions or suggestions, please open an issue.

Changelog

See CHANGELOG.md for version history and changes.