cycle/active-record

Provides a simple way to work with your database using Active Record pattern and Cycle ORM

v1.0.0 2025-08-31 19:52 UTC

README


CycleORM Logo

Codecov Coverage Type Coverage Mutation testing badge Discord Follow on Twitter (X)

Active Record Implementation for Cycle ORM

This library extends Cycle ORM by integrating the Active Record pattern, providing developers with an intuitive, object-centric way to interact with databases.

Unlike Cycle ORM's default Data Mapper pattern, which separates the in-memory object representations from database operations, Active Record combines data access and business logic in a single entity.

This allows for more straightforward and rapid development cycles, particularly for simpler CRUD operations, by enabling direct data manipulation through the object's properties and methods.


🚩 Prerequisites

Before you begin, ensure your development environment meets the following requirements:


💿 Installation

The preferred way to install this package is through Composer.

composer require cycle/active-record

PHP Version Require Latest Stable Version License Total Downloads

After package install you need to, optionally, register bootloader / service-provider in your application.

→ Spiral Framework

Note

If you are installing the package on the Spiral Framework with the spiral-packages/discoverer package, then you don't need to register bootloader by yourself. It will be registered automatically.

Update Bootloader list in your application configuration:

<?php

declare(strict_types=1);

namespace App\Application;

use Spiral\Cycle\Bootloader as CycleBridge;
use Cycle\ActiveRecord\Bridge\Spiral\Bootloader\ActiveRecordBootloader;

class Kernel extends \Spiral\Framework\Kernel
{
    public function defineBootloaders(): array
    {
        return [
            // ...

            // ORM
            CycleBridge\SchemaBootloader::class,
            CycleBridge\CycleOrmBootloader::class,
            CycleBridge\AnnotatedBootloader::class,

            // ActiveRecord
            ActiveRecordBootloader::class,

            // ...
        ];
}

For more information about bootloaders, refer to the Spiral Framework documentation.

→ Laravel

Note

If you are using Laravel, then you don't need to register service-provider by yourself. It will be registered automatically.

→ Yii 3

For configuration instructions refer to yii-cycle installation guide.

→ Other Frameworks

This package uses PSR-11 compatible container to resolve dependencies. After container initialization you need to pass container instance to the static facade:

\Cycle\ActiveRecord\Facade::setContainer($container);

📖 Usage

Note

For detailed usage instructions, refer to the documentation.

→ Basic Example

Define Entity with ActiveRecord

use Cycle\ActiveRecord\ActiveRecord;
use Cycle\Annotated\Annotation\Column;
use Cycle\Annotated\Annotation\Entity;

#[Entity(table: 'users')]
class User extends ActiveRecord
{
    #[Column(type: 'primary', typecast: 'int')]
    public ?int $id = null;

    #[Column(type: 'string')]
    public string $name;

    public function create(string $name)
    {
        return self::make([
            'name' => $name,
        ]);
    }
}

Create a new record

$user = User::create(name: 'John');
$user->saveOrFail();

🙌 Want to Contribute?

Thank you for considering contributing to the cycle community! We are open to all kinds of contributions. If you want to:

You are more than welcome. Before contributing, kindly check our contribution guidelines.

Conventional Commits Contributors