A sort-of-kind-of ActiveModel type'ish base for Models that rely on an array of attributes. Includes a type-casting sub-system for casting attributes to values. Extracted from read-models.
The focus is for creating read-only Model representations for use in presentation layers. This library is used by somnambulist/read-models and api-client.
- PHP 8.1+
- pragmarx/ia-str
Install using composer, or checkout / pull the files from github.com.
- composer require somnambulist/attribute-model
Extend to a model e.g. User; or implement into a base model and add extra functionality. Use attribute casting if needed before passing attributes into the model.
<?php
use Somnambulist\Components\AttributeModel\AbstractModel;
use Somnambulist\Components\AttributeModel\AttributeCaster;
use Somnambulist\Components\AttributeModel\TypeCasters\AreaCaster;
use Somnambulist\Components\AttributeModel\TypeCasters\MoneyCaster;
class User extends AbstractModel
{
}
$caster = new AttributeCaster([
new AreaCaster(),
new MoneyCaster(),
]);
$attrs = [];
$user = new User($caster->cast($attrs, ['area' => 'area', 'money' => 'money',]));The following casters are built-in and are largely configurable by type or attribute name(s):
| Caster | Output | Comments |
|---|---|---|
| AreaCaster | Somnambulist\Components\Models\Types\Measure\Area | convert a value + unit to an Area value object |
| CoordinateCaster | Somnambulist\Components\Models\Types\Geography\Coordinate | convert lat/long/srid strings to value object |
| DateTimeCaster | Somnambulist\Components\Models\Types\DateTime\DateTime | convert a date/time in a format to a DateTime object |
| DistanceCaster | Somnambulist\Components\Models\Types\Measure\Distance | convert a value + unit to a Distance value object |
| EnumCaster | BackedEnum | returns a PHP 8.1 backed enum |
| EnumerableKeyCaster | Somnambulist\Components\Models\AbstractEnumeration | returns instantiated enumeration object using the member key; may also be a multiton |
| EnumerableValueCaster | Somnambulist\Components\Models\AbstractEnumeration | returns instantiated enumeration object using the member value |
| ExternalIdentityCaster | Somnambulist\Components\Models\Identity\ExternalIdentity | decodes a JSON string into an ExternalIdentity value object |
| JsonArrayCaster | array | decodes a JSON string into a simple array |
| JsonCollectionCaster | Somnambulist\Collection\MutableCollection | decodes a JSON string into a collection object |
| MoneyCaster | Somnambulist\Components\Models\Types\Money\Money | convert a value + ISO currency to value object |
| SimpleValueObjectCaster | Somnambulist\Components\Models\AbstractValueObject | creates value-objects from a single string value e.g. EmailAddress |
Many of the casters accept alternative attribute names for matching and type overrides. Suitable defaults are provided where appropriate (e.g.: json, json_array, json_collection).
More casters can be added by implementing the interface and attaching to the AttributeCaster.
An existing caster can be re-used on another type by calling $caster->extend(<type>, [new, types, here]).
The configuration of the caster cannot be changed; it adds extra type keys that the caster will
respond to.
PHPUnit 9+ is used for testing. Run tests via vendor/bin/phpunit.