cycle/active-record

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

v1.1.1 2025-09-14 07:34 UTC

Requires

• php: >=8.1
• cycle/database: ^2.11
• cycle/orm: ^2.7
• psr/container: ^2.0
• yiisoft/injector: ^1.2

Requires (Dev)

• buggregator/trap: ^1.5
• cycle/entity-behavior: ^1.3
• ergebnis/phpunit-slow-test-detector: ^2.14
• fakerphp/faker: ^1.23
• illuminate/support: ^10.48 || ^11.0
• infection/infection: >=0.29
• mockery/mockery: ^1.6
• phpunit/phpunit: ^10.5
• psalm/plugin-phpunit: ~0.19.0
• rector/rector: ^1.0
• spiral/boot: ^3.12
• spiral/code-style: ^2.3
• spiral/cycle-bridge: ^2.9
• spiral/framework: ^3.12
• spiral/logger: ^3.12
• spiral/testing: ^2.7
• ta-tikoma/phpunit-architecture-test: ^0.8.5
• vimeo/psalm: ^6.0

Suggests

• spiral/cycle-bridge: Provides integration with Spiral Framework
• wayofdev/laravel-cycle-orm-adapter: Laravel adapter for Cycle ORM
• yiisoft/yii-cycle: Yii Cycle ORM integration

MIT

• Aleksei Gagarin (roxblnfk)
• Andrij Orlenko

• database
• orm
• activerecord
• model
• active-record
• cycle
• cycle-orm

README

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:

• PHP Version: 8.1 or higher
• One of the Cycle ORM adapters:
  • spiral/cycle-bridge official Cycle ORM adapter for the Spiral Framework
  • yiisoft/yii-cycle — official Cycle ORM adapter for the Yii 3
  • wayofdev/laravel-cycle-orm-adapter — package managed by @wayofdev for the Laravel 10.x or higher.

💿 Installation

The preferred way to install this package is through Composer.

composer require cycle/active-record

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();

→ Advanced Usage Examples

Query Builder Integration

// Find users with advanced Cycle ORM filtering
$user = User::query()
    ->where('name', 'John')
    ->where('active', true)
    ->fetchOne();

// Find by primary key
$user = User::findByPK(42);

// Find with conditions
$users = User::findAll(['status' => 'active']);
$user = User::findOne(['email' => '[e-mail]']);

Batch Operations and Transactions

$user1 = new User('Alice');
$user2 = new User('Bob');

// Group multiple operations in a single transaction
ActiveRecord::groupActions(function (EntityManagerInterface $em) use ($user1, $user2) {
    $user1->save();
    $user2->save();
    // Both users saved in one transaction
}, TransactionMode::OpenNew);

// Advanced transaction handling
User::transact(function (DatabaseInterface $db, EntityManagerInterface $em) {
    $user = User::query()->forUpdate()->fetchOne(['name' => 'Charlie']);
    $user->name = 'Charles';
    $user->save();
});

🙌 Want to Contribute?

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

• 🤔 Suggest a feature
• 🐛 Report an issue
• 📖 Improve documentation
• 👨‍💻 Contribute to the code

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