README

Strongly typed map objects for PHP 8+

This package provides a lightweight foundation for building domain-driven, immutable, and type-safe map objects in PHP.

Overview

This package provides full implementations for all interfaces defined in compono-kit/maps-interfaces.
For every scalar type, the package includes: - Map interfaces (typed and native) - Mutable/Immutable extensions - Traits implementing core behavior - Abstract classes for validation & JSON processing - Concrete map classes such as FloatMap, IntMap, BooleanMap, etc.

All maps are: - Iterable - JSON serializable - Comparable (equals() & equalsValues()) - Fully unit tested (100% coverage)

Requirements/Dependencies

• PHP 8+
• compono-kit/types-interfaces
• compono-kit/maps-interfaces

🚀 Installation

composer require compono-kit/maps

Usage

Immutables

$map = new FloatMap( [ 'test-key-1' => new FloatType( 1.1 ) ] );
$map = $map->set( 'test-key-2', new FloatType( 1.5 ) );
$map->get( 'test-key-2' ); //FloatType( 1.5 )
$newMap = $map->remove( 'test-key-2' );
$map->exists( 'test-key-2'); //true
$newMap->exists( 'test-key-2'); //false

Mutables

$map = new FloatMap( [ 'test-key-1' => new FloatType( 1.1 ) ] );
$map['test-key-2'] = new FloatType( 1.5 );
$map['test-key-2']; //FloatType( 1.5 )
unset( $map['test-key-2'] );
isset( $map['test-key-2'] ); //false

Architecture

1. Interfaces (Float example)

RepresentsFloatMap

Provides: - typed values (RepresentsFloat) - native array conversion - iterators for values and key/value pairs

RepresentsImmutableFloatMap

• immutable variant\
• set() & remove() always return a new instance

RepresentsMutableFloatMap

• mutable variant\
• supports ArrayAccess

Native Variants

Identical structure, but values are native primitives (float, int, etc.)

Mixed Type Variants

These maps support values of type: - float - int - string - bool - array
or their RepresentsType wrappers.

2. Traits

Each map system is powered by three traits:

RepresentingFloatMap

Contains the shared core implementation: - iteration logic - JSON serialization - equals() and equalsValues() - keys() and values() - toNativeType() and toNativeArray()

RepresentingImmutableFloatMap

• uses RepresentingFloatMap
• all modifying operations (set, remove, mergeMap, addMissing) return a new instance

RepresentingMutableFloatMap

• directly mutates the internal array
• implements ArrayAccess

3. Abstract Classes

AbstractFloatMap (immutable)

Contains: - RepresentingImmutableFloatMap - validation of all values using validate() - fromJson() - abstract isValueValid()

AbstractFloatMap (mutable)

• same behavior as immutable version
• but uses RepresentingMutableFloatMap

BooleanMap (special case)

Boolean maps do not use an abstract class
Validation only checks instanceof RepresentsBoolean.

4. Concrete Map Classes

Example:

class FloatMap extends AbstractFloatMap {
    public static function isValueValid( RepresentsFloat $type ): bool {
        return true;
    }
}

All map types follow this pattern.

JSON Handling

fromJson()

• accepts JSON key/value objects
• converts each value via Builds*Types factory
• ensures strict type validation (float, int, etc.)

The fromJson() static method allows you to create a fully typed Map instance directly from JSON.
It is particularly useful for:

• Loading configuration data from external sources
• Deserializing complex nested structures
• Maintaining strict type safety while working with native JSON values

fromJson() accepts a JSON string and a factory instance that implements the appropriate interface, such as:

• BuildsFloatTypes
• BuildsIntegerTypes
• BuildsStringTypes
• BuildsBooleanTypes
• BuildsMixedTypes

Example

Consider the following example:

MixedTypeMap::fromJson(
    json_encode(
        [
            'test-key-1' => 1.1,
            'test-key-2' => 'test-value-2',
            'test-key-3' => 3,
            'test-key-4' => true,
            'test-key-5' => [
                'test-key-1' => 1.1,
                'test-key-2' => [ 'test-key-1' => 'test-value-2' ],
            ],
        ]
    ),
    new MixedTypeFactory()
);

becomes with corresponding factory:

new MixedTypeMap(
    [
        'test-key-1' => new FloatType( 1.1 ),
        'test-key-2' => new StringType( 'test-value-2' ),
        'test-key-3' => new IntegerType( 3 ),
        'test-key-4' => new BooleanType( true ),
        'test-key-5' => new MixedTypeMap(
            [
                'test-key-1' => new FloatType( 1.1 ),
                'test-key-2' => new MixedTypeMap(
                    [ 'test-key-1' => new StringType( 'test-value-2' ) ]
                ),
            ]
        ),
    ]
);

Testing

• The package provides 100% test coverage
• All combinations (typed/native, mutable/immutable) are fully tested

Purpose

This package serves as the reference implementation for all map interfaces from compono-kit/maps-interfaces