README

Practical extensions for Cycle ORM: base repositories, entity traits, typecasts, and more.

Overview

This package provides a collection of practical extensions for Cycle ORM, including:

Entity traits for common functionality (timestamps, UUIDs, etc.)
Base repository implementations
Custom typecasts
Event listeners
And more

Requirements

PHP 8.1, 8.2, 8.3, or 8.4
Cycle ORM 2.10+
Ramsey UUID 4.7+

Installation

Install the package via composer:

composer require sirix/cycle-orm-extensions

Features

Entity Traits

The package provides several traits for common entity functionality:

Standard Traits

HasChronosCreateTrait - Adds creation timestamp functionality
HasChronosUpdateTrait - Adds update timestamp functionality
HasChronosDeleteTrait - Adds deletion timestamp functionality
HasIdIdentifierTrait - Adds integer ID primary key functionality
HasUuidIdentifierTrait - Adds UUID primary key functionality

Annotated Traits

Annotated versions of the traits that include Cycle ORM annotations:

HasChronosCreateTimestampAnnotatedTrait - Adds creation timestamp with annotations
HasChronosCreateDatetimeAnnotatedTrait - Adds creation datetime with annotations
HasChronosUpdateTimestampAnnotatedTrait - Adds update timestamp with annotations
HasChronosUpdateDatetimeAnnotatedTrait - Adds update datetime with annotations
HasChronosDeleteTimestampAnnotatedTrait - Adds deletion timestamp with annotations
HasChronosDeleteDatetimeAnnotatedTrait - Adds deletion datetime with annotations
HasIdIdentifierAnnotatedTrait - Adds integer ID primary key with annotations
HasUuidIdentifierAnnotatedTrait - Adds UUID primary key with annotations

Repositories

Base repository implementations for common operations:

AbstractReadRepository - Base repository for read-only operations
AbstractWriteRepository - Base repository for read-write operations

Typecasts

Custom typecasts for various data types:

Array typecasts
Boolean typecasts
Chronos datetime typecasts
Currency typecasts
CurrencyCode typecasts
Money typecasts
UUID typecasts

Event Listeners

The EventListeners attribute lets you declare Cycle ORM entity listeners directly on the entity class. It injects the configured listeners into the entity schema under SchemaInterface::LISTENERS.

Note: To use listeners, you must install the Cycle Entity Behavior package:

composer require cycle/entity-behavior

You can provide listeners as simple class-strings or as [class, args] tuples. You may also mix both forms in one array. Passing an empty args array [] is equivalent to specifying the class directly; the attribute normalizes this for you.

Simple listeners (class-strings only)

<?php

use Sirix\Cycle\Extension\Behavior\EventListeners;
use Sirix\Cycle\Extension\Listener\ChronosCreateListener;
use Sirix\Cycle\Extension\Listener\ChronosUpdateListener;

#[EventListeners(listeners: [
    ChronosCreateListener::class,
    ChronosUpdateListener::class,
])]
final class User {}

Listeners with constructor arguments (mixed usage)

<?php

use Sirix\Cycle\Extension\Behavior\EventListeners;
use Sirix\Cycle\Extension\Listener\ChronosSoftDeleteListener;
use App\Cycle\Listener\AuditListener;

#[EventListeners(listeners: [
    ChronosSoftDeleteListener::class,
    [AuditListener::class, ['timezone' => 'UTC', 'captureOldValues' => true]],
])]
final class User {}

Example listener class consuming the named arguments:

<?php

namespace App\Cycle\Listener;

final class AuditListener
{
    public function __construct(
        private readonly string $timezone = 'UTC',
        private readonly bool $captureOldValues = false,
    ) {}

    // Implement handle methods as required by Cycle ORM's listener contracts
}

For a complete entity example that uses listeners, see the annotated entity example below.

Usage Examples

The package includes several example files in the src/Example directory that demonstrate how to use its features:

Example Files

AnnotatedEntityExample.php: Demonstrates how to create an entity with annotations, using traits for UUID identifier and Chronos timestamps, and configuring event listeners.
AnnotatedEntityExampleTypecastHandler.php: Shows how to create a typecast handler for Chronos datetime fields.
ReadRepositoryExample.php: Demonstrates how to create a read-only repository.
WriteRepositoryExample.php: Shows how to create a repository with writing capabilities.

Creating an Annotated Entity

<?php

declare(strict_types=1);

namespace Sirix\Cycle\Extension\Example;

use Cycle\Annotated\Annotation\Column;
use Cycle\Annotated\Annotation\Entity;
use Sirix\Cycle\Extension\Behavior\EventListeners;
use Sirix\Cycle\Extension\Domain\Contract\EntityInterface;
use Sirix\Cycle\Extension\Entity\Trait\Annotated\HasChronosCreateTimestampAnnotatedTrait;
use Sirix\Cycle\Extension\Entity\Trait\Annotated\HasChronosUpdateTimestampAnnotatedTrait;
use Sirix\Cycle\Extension\Entity\Trait\Annotated\HasUuidIdentifierAnnotatedTrait;
use Sirix\Cycle\Extension\Listener\ChronosCreateListener;
use Sirix\Cycle\Extension\Listener\ChronosSoftDeleteListener;
use Sirix\Cycle\Extension\Listener\ChronosUpdateListener;

#[Entity(
    repository: WriteRepositoryExample::class,
    table: 'users',
    database: 'default',
    typecast: [
        AnnotatedEntityExampleTypecastHandler::class
    ]
)]
#[EventListeners(
    listeners: [
        ChronosCreateListener::class,
        ChronosUpdateListener::class,
        ChronosSoftDeleteListener::class,
    ],
)]
class AnnotatedEntityExample implements EntityInterface
{
    // Include the annotated traits
    use HasUuidIdentifierAnnotatedTrait;
    use HasChronosCreateTimestampAnnotatedTrait;
    use HasChronosUpdateTimestampAnnotatedTrait;

    // Define additional properties with annotations
    #[Column(type: 'string')]
    private string $name;

    #[Column(type: 'string')]
    private string $email;

    public function getName(): string
    {
        return $this->name;
    }

    public function setName(string $name): void
    {
        $this->name = $name;
    }

    public function getEmail(): string
    {
        return $this->email;
    }

    public function setEmail(string $email): void
    {
        $this->email = $email;
    }
}

Creating a Typecast Handler

<?php

namespace Sirix\Cycle\Extension\Example;

use Sirix\Cycle\Extension\Typecast\Chronos\ChronosToTimestampType;
use Vjik\CycleTypecast\TypecastHandler;

class AnnotatedEntityExampleTypecastHandler extends TypecastHandler
{
    protected function getConfig(): array
    {
       return [
           'createdAt' => new ChronosToTimestampType(),
           'updatedAt' => new ChronosToTimestampType(),
           'deletedAt' => new ChronosToTimestampType(),
       ];
    }
}

Creating a Write Repository

<?php

declare(strict_types=1);

namespace Sirix\Cycle\Extension\Example;

use Cycle\ORM\Select\Repository;
use DateTimeInterface;
use Sirix\Cycle\Extension\Repository\AbstractWriteRepository;

/**
 * @extends Repository<AnnotatedEntityExample>
 */
class WriteRepositoryExample extends AbstractWriteRepository
{
    /**
     * Example of finding entities created after a certain date.
     */
    public function findUsersCreatedAfter(DateTimeInterface $date): array
    {
        $select = $this->select()
            ->where('createdAt', '>', $date->getTimestamp());

        return $select->fetchAll();
    }

    protected function getEntityClass(): string
    {
        return AnnotatedEntityExample::class;
    }
}

Optional Dependencies

The package suggests the following dependencies for additional functionality:

cakephp/chronos: Required for Chronos datetime support
cycle/annotated: Required for annotated entity support
cycle/entity-behavior: Required for entity behaviors and lifecycle hooks support
sirix/money: Required for Money and Currency typecast support
vjik/cycle-typecast: Required for Typecast support

License

This package is licensed under the MIT License - see the LICENSE file for details.

sirix / cycle-orm-extensions

Maintainers

Details