README

A general purpose package containing core PHP utility classes and methods for use by other Mossy2100 PHP packages.

License | Changelog | Documentation

Description

This package provides a comprehensive set of utility classes for working with various PHP types and common operations. Most utility classes are final with static methods and cannot be instantiated directly. Console is the exception - an instantiable class with instance methods and internal style state, since its fluent -> chaining API needs a real object to chain off.

Development and Quality Assurance

This package was developed with Claude Code:

The author developed the initial concept, designed the public API, and did most of the initial coding.
Claude Code wrote the tests and most of the documentation.
Claude Code also assisted with multiple code reviews, which led to bug fixes, performance improvements and other refinements.

The code is checked with:

PHP_CodeSniffer, for PSR-12 compliance plus the Mossy2100 coding standard
PHPStan, at level 9
PHPUnit, with 100% code coverage

Requirements

PHP ^8.4
The intl extension, for NumberFormatter in Floats::format()
The mbstring extension
PHPUnit, only if you use the FloatAssertions trait in your tests

Installation

composer require mossy2100/core

Quick Start

use Mossy2100\Core\Floats;
use Mossy2100\Core\Integers;
use Mossy2100\Core\Stringify;

Floats::approxEqual(0.1 + 0.2, 0.3);               // true
Floats::format(0.0001234);                         // '1.234×10⁻⁴'
Integers::mul(PHP_INT_MAX, 2);                     // throws OverflowException
Integers::toSuperscript(-42);                      // '⁻⁴²'
Stringify::stringify(['a' => 1.0, 'b' => [1, 2]]); // "['a' => 1.0, 'b' => [1, 2]]"

See Classes below for what each class does, with links to its full documentation.

Classes

Floats

Float-specific utilities for handling IEEE-754 special values (-0.0, ±INF, NAN), approximate comparison, float space navigation (nextUp/nextDown), random generation, and IEEE-754 component assembly/disassembly.

Integers

Integer arithmetic with overflow checking (add, subtract, multiply, power), overflow-safe modular multiplication (mulMod()), GCD calculation, and Unicode subscript/superscript conversion.

Numbers

Number-related utilities for type checking (distinguishing actual numbers from numeric strings), exact equality that correctly handles mixed int/float comparisons, and sign operations with IEEE-754 signed zero support.

Arrays

Array utility methods: value quoting, serial lists ('a, b, and c'), first/last element extraction, value removal, and circular reference removal.

Types

Type inspection utilities: canonical basic type names, identity comparison (identical()), unique string keys for collections, and trait detection, including inherited and nested traits.

Stringify

Advanced value-to-string conversion with pretty printing, supporting all PHP types with improved readability. This class serves as the basis of the Console::dump() method.

StringifyOptions

Per-call options for Stringify: pretty printing, indent and maximum line length.

Environment

Runtime environment detection: 64-bit architecture checks, and the invariant locale used for number formatting.

Console

ANSI/SGR-styled console output: 16-color foreground/background, text attributes (bold, italic, underline, etc.), method chaining, style snapshot/restore, and higher-level helpers like dump() and severity-colored messages (success(), error(), warn(), info()).

Globals

Useful constants (M_TAU, RECURSION) that are more convenient to use as globals (namespaced to Mossy2100\Core) than as class members.

Traits

Comparison Traits

Equality and ordering comparison operations for custom types. See ComparisonTraits.md for the trait hierarchy and usage guide.

Trait	Description
Equatable	Base trait for exact equality comparison via `equal()`.
Comparable	Extends Equatable with ordering: `lessThan()`, `greaterThan()`, etc.
ApproxEquatable	Extends Equatable with tolerance-based `approxEqual()`.
ApproxComparable	Combines Comparable and ApproxEquatable with `approxCompare()`.

Assert Traits

Custom PHPUnit assertions for test cases. See TestingTraits.md for usage examples.

Trait	Description
FloatAssertions	Provides `assertApproxEqual()` with informative failure messages.

Enums

FloatFormat

Notation styles for Floats::format() - fixed-point, scientific, or automatic selection between the two.

ExponentFormat

Rendering styles for the exponent portion of scientific-notation float output, from plain ASCII e/E through to Unicode and HTML mathematical notation.

Exceptions

FormatException

Exception thrown when a string has an invalid format for the desired operation. Extends DomainException. Useful for parse methods or constructors that accept string arguments.

ArithmeticException

Exception thrown when an arithmetic operation has no defined result for the given operands, such as division by zero or a logarithm of a non-positive number. Extends DomainException. Displaces DivisionByZeroError for userland arithmetic code in value types like Complex, Rational, Vector, and Matrix.

Testing

The library includes comprehensive test coverage:

# Run all tests
vendor/bin/phpunit

# Run specific test class
vendor/bin/phpunit tests/NumbersTest.php

# Run with coverage (generates HTML report and clover.xml)
composer test

License

MIT License - see LICENSE for details

Support

Issues: https://github.com/mossy2100/PHP-Core/issues
Documentation: See docs/ directory for detailed class documentation
Examples: See test files for comprehensive usage examples

For questions or suggestions, please open an issue.

Changelog

See CHANGELOG.md for version history and changes.

oceanmoon / core

Package info

Security

Statistics