cycle / active-record

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

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.2 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')]
    private int $id;

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

    public function __construct(string $name)
    {
        $this->name = $name;
    }
    
    public function id(): int
    {
        return $this->id;
    }
    
    public function name()
    {
        return $this->name;
    }
}

Create a new record

$user = new User(name: 'John');
$user->save();

🧪 Running Tests

→ PHPUnit tests

To run tests, run the following command:

make test

→ Mutation tests

To run mutation tests, using infection/infection:

make infect

→ Static Analysis

Code quality using PHPStan:

make lint-stan

and using Psalm:

make lint-psalm

→ Coding Standards Fixing

Fix code using The PHP Coding Standards Fixer (PHP CS Fixer) to follow our standards:

make lint-php

→ Lint Yaml files

Lint all yaml files in project:

make lint-yaml

→ Lint Markdown files

Lint all yaml files in project:

make lint-md

→ Lint GitHub Actions

Lint all yaml files in project:

make lint-actions

🔒 Security Policy

This project has a security policy.

🙌 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.

🫡 Contributors

🌐 Social Links

• Twitter: Follow our organization @SpiralPHP.
• Discord: Join our community on Discord.

⚖️ License

active-record's Issues

[Docs]: Document how to use Collections instead of arrays

Describe the bug

Currently documentation says that Collections can be used

To Reproduce

https://active-record.wayof.dev/active-entities/retrieving-entities#collections

Media prove

Describe the solution you would like

1. Implement this PR: #20
2. Document how to use Collections

Additional context

No response

[Feature]: replace ::transact() with ::group()

Is your feature request related to a problem? Please describe.

Meaning of ::transact() method may be not clear.
A programmer may think that method opens a transaction before the callable call and closes after it.
But the method just groups OPRM actions inside using EM transaction mode option. And all the custom SQL queries mill not be included in the same EM's ORM transaction.

Describe the solution you'd like

• rename ::transact() method to ::group()
• add a new ::transact() method that will open and close a transaction

Describe alternatives you've considered

No response

Additional context

No response

[Feature]: add Entity::make()

Is your feature request related to a problem? Please describe.

It's not recommended to create entities using constructor. Best practice is use ORM::make().
But with AR patter we should have some syntax to avoid using ORM directly

Describe the solution you'd like

Add ActiveRecord::make(array $data) method that will use ORM::make under the hood

Describe alternatives you've considered

No response

Additional context

No response