vjik/cycle-typecast

Helper of typecast data in Cycle ORM

3.0.0 2025-04-18 06:43 UTC

Requires

• php: 8.1 - 8.4
• cycle/orm: ^2.1
• ramsey/uuid: ^4.1

Requires (Dev)

• phpunit/phpunit: ^10.5.45
• roave/infection-static-analysis-plugin: ^1.35
• vimeo/psalm: ^5.26.1 || ^6.10

BSD-3-Clause

• datamapper
• cycle
• typecast

README

The package provides:

• Typecaster that help typecast data in Cycle ORM and abstract TypecastHandler that used it;
• AttributeTypecastHandler that use attributes for typecast data;
• TypeInterface that must be implemented by classes used in Typecaster and AttributeTypecastHandler;
• classes for DateTimeImmutable, UUID, Array and Enum types.

Installation

The package could be installed with composer:

composer require vjik/cycle-typecast

General Usage

Attributes

use Vjik\CycleTypecast\AttributeTypecastHandler;
use Vjik\CycleTypecast\UuidString\UuidStringToBytesType;
use Vjik\CycleTypecast\DateTimeImmutable\DateTimeImmutableToIntegerType;

#[Entity(
    // ...
    typecast: AttributeTypecastHandler::class,
)]
final class User
{
    // ...

    #[Column(type: 'primary', primary: true)]
    #[UuidStringToBytesType]
    private string $id;

    #[Column(type: 'int')]
    #[DateTimeImmutableToIntegerType]
    private DateTimeImmutable $createDate;

Custom Typecast Handler

use Vjik\CycleTypecast\ArrayToStringType;
use Vjik\CycleTypecast\DateTimeImmutable\DateTimeImmutableToIntegerType;
use Vjik\CycleTypecast\TypecastHandler;
use Vjik\CycleTypecast\UuidString\UuidStringToBytesType;

final class UserTypecastHandler extends Vjik\CycleTypecast\TypecastHandler
{
    protected function getConfig(): array
    {
        return [
            'id' => new UuidStringToBytesType(),
            'createDate' => new DateTimeImmutableToIntegerType(),
            'modifyDate' => new DateTimeImmutableToIntegerType(),
            'tags' => new ArrayToStringType(','),
        ];
    }
}

Custom Mapper

use Cycle\ORM\ORMInterface;
use Cycle\ORM\PromiseMapper\PromiseMapper;
use Vjik\CycleTypecast\Typecaster;
use Vjik\CycleTypecast\ArrayToStringType;
use Vjik\CycleTypecast\DateTimeImmutable\DateTimeImmutableToIntegerType;
use Vjik\CycleTypecast\UuidString\UuidStringToBytesType;

final class UserMapper extends PromiseMapper
{
    private Typecaster $typecaster;

    public function __construct(ORMInterface $orm, string $role)
    {
        // Typecast configuration
        $this->typecaster = new Typecaster([
            'id' => new UuidStringToBytesType(),
            'createDate' => new DateTimeImmutableToIntegerType(),
            'modifyDate' => new DateTimeImmutableToIntegerType(),
            'tags' => new ArrayToStringType(','),
        ]);
        
        parent::__construct($orm, $role);
    }

    public function extract($entity): array
    {
        $data = parent::extract($entity);
        
        // Typecast after extract from entity
        return $this->typecaster->prepareAfterExtract($data);
    }

    public function hydrate($entity, array $data)
    {
        // Typecast before hydrate entity
        $data = $this->typecaster->prepareBeforeHydrate($data);
        
        return parent::hydrate($entity, $data);
    }
}

Types

ArrayToStringType

new ArrayToStringType(',');

Entity value: array of strings. For example, ['A', 'B', 'C'].

Database value: array concatenated into string with delimiter setted in constructor. For example, A,B,C.

DateTimeImmutableToIntegerType

new DateTimeImmutableToIntegerType();

Entity value: DateTimeImmutable.

Database value: timestamp as string (example, 1609658768).

IntegerEnumType

new IntegerEnumType(IntegerEnum::class);

Entity value: integer typed enumeration.

Database value: enumeration value of integer type.

StringEnumType

new StringEnumType(StringEnum::class);

Entity value: string typed enumeration.

Database value: enumeration value of string type.

UuidStringToBytesType

new UuidStringToBytesType();

Entity value: string standard representation of the UUID. For example, 1f2d3897-a226-4eec-bd2c-d0145ef25df9.

Database value: binary string representation of the UUID.

Testing

Unit Testing

The package is tested with PHPUnit. To run tests:

./vendor/bin/phpunit

Mutation Testing

The package tests are checked with Infection mutation framework with Infection Static Analysis Plugin. To run it:

./vendor/bin/roave-infection-static-analysis-plugin

Static Analysis

The code is statically analyzed with Psalm. To run static analysis:

./vendor/bin/psalm

License

The Cycle Typecast is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.