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.
Get Started
Installation
composer require cycle/active-record
Requirements
- PHP 8.2+
- One of the Cycle ORM adapters:
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
→ 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' => 'john@example.com']);
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:
You are more than welcome. Before contributing, kindly check our contribution guidelines.