https://github.com/yiisoft/active-record
Active Record database abstraction layer
https://github.com/yiisoft/active-record
active-record activerecord database hacktoberfest optionalforframeworkannounce yii3
Last synced: 23 days ago
JSON representation
Active Record database abstraction layer
- Host: GitHub
- URL: https://github.com/yiisoft/active-record
- Owner: yiisoft
- License: bsd-3-clause
- Created: 2018-08-05T09:34:14.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2025-05-12T06:53:06.000Z (27 days ago)
- Last Synced: 2025-05-16T03:22:45.924Z (23 days ago)
- Topics: active-record, activerecord, database, hacktoberfest, optionalforframeworkannounce, yii3
- Language: PHP
- Homepage: https://www.yiiframework.com/
- Size: 1.28 MB
- Stars: 71
- Watchers: 25
- Forks: 31
- Open Issues: 46
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
Yii ActiveRecord
[](https://packagist.org/packages/yiisoft/active-record)
[](https://packagist.org/packages/yiisoft/active-record)
[](https://codecov.io/gh/yiisoft/active-record)
[](https://dashboard.stryker-mutator.io/reports/github.com/yiisoft/active-record/master)
[](https://github.com/yiisoft/active-record/actions/workflows/static.yml)
[](https://shepherd.dev/github/yiisoft/active-record)
This package provides [ActiveRecord] library.
It is used in [Yii Framework] but is supposed to be usable separately.
[ActiveRecord]: https://en.wikipedia.org/wiki/Active_record_pattern
[Yii Framework]: https://www.yiiframework.com/
## Support databases
| Packages | Versions | CI-Actions |
|-----------------------------------------------------|-----------------|------------|
| [[db-mssql]](https://github.com/yiisoft/db-mssql) | **2017 - 2022** |[](https://github.com/yiisoft/db-mssql/actions?query=workflow%3Abuild) [](https://dashboard.stryker-mutator.io/reports/github.com/yiisoft/db-mssql/master) [](https://codecov.io/gh/yiisoft/db-mssql)|
| [[db-mysql]](https://github.com/yiisoft/db-mysql) | **5.7 - 8.0** |[](https://github.com/yiisoft/db-mysql/actions?query=workflow%3Abuild) [](https://dashboard.stryker-mutator.io/reports/github.com/yiisoft/db-mysql/master) [](https://codecov.io/gh/yiisoft/db-mysql)|
| [[db-oracle]](https://github.com/yiisoft/db-oracle) | **12 - 21** |[](https://github.com/yiisoft/db-oracle/actions?query=workflow%3Abuild) [](https://dashboard.stryker-mutator.io/reports/github.com/yiisoft/db-oracle/master) [](https://codecov.io/gh/yiisoft/db-oracle)|
| [[db-pgsql]](https://github.com/yiisoft/db-pgsql) | **9.0 - 16.0** |[](https://github.com/yiisoft/db-pgsql/actions?query=workflow%3Abuild) [](https://dashboard.stryker-mutator.io/reports/github.com/yiisoft/db-pgsql/master) [](https://codecov.io/gh/yiisoft/db-pgsql)|
| [[db-sqlite]](https://github.com/yiisoft/db-sqlite) | **3:latest** |[](https://github.com/yiisoft/db-sqlite/actions?query=workflow%3Abuild) [](https://dashboard.stryker-mutator.io/reports/github.com/yiisoft/db-sqlite/master) [](https://codecov.io/gh/yiisoft/db-sqlite)|
## Requirements
- PHP 8.1 - 8.4.
## Installation
The package could be installed with [Composer](https://getcomposer.org):
```shell
composer require yiisoft/active-record
```
**Note: You must install the repository of the implementation to use.**
Example:
```shell
composer require yiisoft/db-sqlite
```
## Configure container with database connection
Add the following code to the configuration files, for example:
`config/common/di/db.php`:
```php
use Yiisoft\Db\Connection\ConnectionInterface;
use Yiisoft\Db\Sqlite\Connection;
use Yiisoft\Db\Sqlite\Driver;
return [
ConnectionInterface::class => [
'class' => Connection::class,
'__construct()' => [
'driver' => new Driver($params['yiisoft/db-sqlite']['dsn']),
],
]
];
```
`config/common/params.php`:
```php
return [
'yiisoft/db-sqlite' => [
'dsn' => 'sqlite:' . dirname(__DIR__) . '/runtime/yiitest.sq3',
]
]
```
For more information about how to configure the connection, follow [Yii Database](https://github.com/yiisoft/db/blob/master/docs/guide/en/README.md).
`config/common/bootstrap.php`:
```php
use Psr\Container\ContainerInterface;
use Yiisoft\ActiveRecord\ConnectionProvider;
use Yiisoft\Db\Connection\ConnectionInterface;
return [
static function (ContainerInterface $container): void {
ConnectionProvider::set($container->get(ConnectionInterface::class));
}
];
```
Be sure to include `bootstrap.php` file using `config-plugin` in `extra` section of `composer.json` (see [yiisoft/config](https://github.com/yiisoft/config)):
```
"extra": {
"config-plugin": {
"bootstrap": "common/bootstrap.php"
}
}
```
Or if you use `config-plugin-file` in `extra` section of `composer.json` as follows:
```
"extra": {
"config-plugin-file": "configuration.php"
}
```
add the line `'bootstrap' => 'common/bootstrap.php',` to `configuration.php` file:
```php
return [
'config-plugin' => [
'bootstrap' => 'common/bootstrap.php',
],
];
```
See other ways to [define the DB connection](docs/define-connection.md) for Active Record.
## Defined your active record class
```php
use Yiisoft\ActiveRecord\ActiveRecord;
/**
* Entity User.
*
* Database fields:
* @property int $id
* @property string $username
* @property string $email
**/
#[\AllowDynamicProperties]
final class User extends ActiveRecord
{
public function getTableName(): string
{
return '{{%user}}';
}
}
```
For more information, follow [Create Active Record Model](docs/create-model.md).
## Usage
Now you can use the Active Record:
```php
use App\Entity\User;
$user = new User();
$user->set('username', 'yiiliveext');
$user->set('email', '[email protected]');
$user->save();
```
Usage with `ActiveQuery`:
```php
use App\Entity\User;
use Yiisoft\ActiveRecord\ActiveQuery;
$userQuery = new ActiveQuery(User::class);
$user = $userQuery->where(['id' => 1])->one();
$username = $user->get('username');
$email = $user->get('email');
```
## Documentation
- [Optimistic Locking](docs/optimistic-locking.md)
- [Internals](docs/internals.md)
If you need help or have a question, the [Yii Forum](https://forum.yiiframework.com/c/yii-3-0/63) is a good place for that.
You may also check out other [Yii Community Resources](https://www.yiiframework.com/community).
## License
The Yii Active Record Library is free software. It is released under the terms of the BSD License.
Please see [`LICENSE`](./LICENSE.md) for more information.
Maintained by [Yii Software](https://www.yiiframework.com/).
## Support the project
[](https://opencollective.com/yiisoft)
## Follow updates
[](https://www.yiiframework.com/)
[](https://twitter.com/yiiframework)
[](https://t.me/yii3en)
[](https://www.facebook.com/groups/yiitalk)
[](https://yiiframework.com/go/slack)