[](https://github.com/cycle/active-record/actions)
[](https://packagist.org/packages/cycle/active-record)
[](https://packagist.org/packages/cycle/active-record)
[](https://packagist.org/packages/cycle/active-record)
[](https://packagist.org/packages/cycle/active-record)
[](https://app.codecov.io/gh/cycle/active-record)
[](https://shepherd.dev/github/cycle/active-record)
[](https://dashboard.stryker-mutator.io/reports/github.com/cycle/active-record/master)
[](https://discord.gg/spiralphp)
[](https://x.com/intent/follow?screen_name=SpiralPHP)
# Active Record Implementation for Cycle ORM
This library extends Cycle ORM by integrating the [Active Record pattern](https://en.wikipedia.org/wiki/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`](https://github.com/spiral/cycle-bridge) official Cycle ORM adapter for the [Spiral Framework](https://github.com/spiral/framework)
- [`yiisoft/yii-cycle`](https://github.com/yiisoft/yii-cycle) โ official Cycle ORM adapter for the [Yii 3](https://www.yiiframework.com)
- [`wayofdev/laravel-cycle-orm-adapter`](https://github.com/wayofdev/laravel-cycle-orm-adapter) โ package managed by [@wayofdev](https://github.com/wayofdev) for the [Laravel](https://laravel.com) 10.x or higher.
## ๐ฟ Installation
The preferred way to install this package is through [Composer](https://getcomposer.org/).
```bash
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](https://github.com/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
[!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](https://github.com/yiisoft/yii-cycle/blob/master/docs/guide/en/installation.md).
### โ Other Frameworks
This package uses [PSR-11](https://www.php-fig.org/psr/psr-11/) compatible `container` to resolve dependencies. After container initialization you need to pass `container` instance to the static facade:
```php
\Cycle\ActiveRecord\Facade::setContainer($container);
```
## ๐ Usage
> [!NOTE]
> For detailed usage instructions, refer to the [documentation](/docs/README.md).
### โ Basic Example
#### Define Entity with ActiveRecord
```php
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
```php
$user = new User(name: 'John');
$user->save();
```
## ๐งช Running Tests
### โ PHPUnit tests
To run tests, run the following command:
```bash
make test
```
### โ Mutation tests
To run mutation tests, using [`infection/infection`](https://github.com/infection/infection):
```bash
make infect
```
### โ Static Analysis
Code quality using PHPStan:
```bash
make lint-stan
```
and using Psalm:
```bash
make lint-psalm
```
### โ Coding Standards Fixing
Fix code using The PHP Coding Standards Fixer (PHP CS Fixer) to follow our standards:
```bash
make lint-php
```
### โ Lint Yaml files
Lint all yaml files in project:
```bash
make lint-yaml
```
### โ Lint Markdown files
Lint all yaml files in project:
```bash
make lint-md
```
### โ Lint GitHub Actions
Lint all yaml files in project:
```bash
make lint-actions
```
## ๐ Security Policy
This project has a [security policy](.github/SECURITY.md).
## ๐ 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](https://github.com/cycle/active-record/issues/new?assignees=&labels=type%3A+enhancement&projects=&template=2-feature-request.yml&title=%5BFeature%5D%3A+)
- ๐ [Report an issue](https://github.com/cycle/active-record/issues/new?assignees=&labels=type%3A+documentation%2Ctype%3A+maintenance&projects=&template=1-bug-report.yml&title=%5BBug%5D%3A+)
- ๐ [Improve documentation](https://github.com/cycle/active-record/issues/new?assignees=&labels=type%3A+documentation%2Ctype%3A+maintenance&projects=&template=4-docs-bug-report.yml&title=%5BDocs%5D%3A+)
- ๐จโ๐ป Contribute to the code
You are more than welcome. Before contributing, kindly check our [contribution guidelines](.github/CONTRIBUTING.md).
[](https://conventionalcommits.org)
## ๐ซก Contributors
## ๐ Social Links
- **Twitter:** Follow our organization [@SpiralPHP](https://twitter.com/intent/follow?screen_name=spiralphp).
- **Discord:** Join our community on [Discord](https://discord.gg/SpiralPHP).
## โ๏ธ License
[](./LICENSE.md)
