mirror of
https://github.com/danog/AsyncOrm.git
synced 2024-11-26 20:34:55 +01:00
115 lines
5.0 KiB
Markdown
115 lines
5.0 KiB
Markdown
# Async ORM
|
|
|
|
[](https://codecov.io/gh/danog/AsyncOrm)
|
|
[](https://shepherd.dev/github/danog/AsyncOrm)
|
|
[](https://shepherd.dev/github/danog/AsyncOrm)
|
|
|
|
|
|
Async ORM based on AMPHP v3 and fibers, created by Daniil Gentili <daniil@daniil.it> and Alexander Pankratov <alexander@i-c-a.su>.
|
|
|
|
Supports MySQL, Redis, Postgres.
|
|
|
|
Features read and write-back caching, type-specific optimizations, and much more!
|
|
|
|
This ORM library was initially created for [MadelineProto](https://docs.madelineproto.xyz), an async PHP client API for the telegram MTProto protocol.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
composer require danog/async-orm
|
|
```
|
|
|
|
## Usage
|
|
|
|
There are two main ways to use the ORM: through automatic ORM properties, which automatically connects appropriately marked `DbArray` properties to the specified database, or by manually instantiating a `DbArray` with a `DbArrayBuilder`.
|
|
|
|
* [Automatic ORM properties example »](https://github.com/danog/AsyncOrm/blob/master/examples/1-automatic.php)
|
|
* [Manual example »](https://github.com/danog/AsyncOrm/blob/master/examples/2-manual.php)
|
|
|
|
The `DbArray` obtained through one of the methods above is an abstract array object that automatically stores and fetches elements of the specified type, from the specified database.
|
|
|
|
### Settings
|
|
|
|
As specified in the examples above, there are multiple settings classes that can be used to connect to a specific database type:
|
|
|
|
* [MysqlSettings: MySQL backend settings.](https://github.com/danog/AsyncOrm/blob/master/docs/docs/danog/AsyncOrm/Settings/MysqlSettings.md)
|
|
* [PostgresSettings: Postgres backend settings.](https://github.com/danog/AsyncOrm/blob/master/docs/docs/danog/AsyncOrm/Settings/PostgresSettings.md)
|
|
* [RedisSettings: Redis backend settings.](https://github.com/danog/AsyncOrm/blob/master/docs/docs/danog/AsyncOrm/Settings/RedisSettings.md)
|
|
|
|
All these classes have multiple fields, described in their respective documentation (click on each class name to view it).
|
|
|
|
#### Caching
|
|
|
|
One of the most important settings is the `cacheTtl` field, which specifies the duration of the read and write cache.
|
|
|
|
If non-zero, all array elements fetched from the database will be stored in an in-memory *read cache* for the specified number of seconds; multiple accesses to the same field will each postpone flushing of that field by `cacheTtl` seconds.
|
|
|
|
All elements written to the array by the application will also be stored in an in-memory *write cache*, and flushed to the database every `cacheTtl` seconds.
|
|
|
|
If the array has an [object value type (ValueType::OBJECT)](#key-and-value-types), write caching is disabled.
|
|
|
|
If `cacheTtl` is 0, read and write caching is disabled.
|
|
|
|
A special setting class is used to create `DbArray`s backed by no database, which can also be useful in certain circumstances:
|
|
|
|
* [MemorySettings: MemorySettings backend settings.](https://github.com/danog/AsyncOrm/blob/master/docs/docs/danog/AsyncOrm/Settings/MemorySettings.md)
|
|
|
|
|
|
### Key and value types
|
|
|
|
Each DbArray must have a specific key and value type.
|
|
|
|
For optimal performance, the specified types must be as strict as possible, here's a list of allowed types:
|
|
|
|
#### Key types
|
|
|
|
* `KeyType::STRING` - String keys only
|
|
* `KeyType::INT` - Integer keys only
|
|
* `KeyType::STRING_OR_INT` - String or integer keys (not recommended, for performance reasons please always specify either `STRING` or `STRING_OR_INT`).
|
|
|
|
#### Value types
|
|
|
|
* `ValueType::STRING`: Direct storage of UTF-8 string values.
|
|
* `ValueType::INT`: Direct storage of integer values.
|
|
* `ValueType::BOOL`: Direct storage of boolean values.
|
|
* `ValueType::FLOAT`: Direct storage of floating point (double precision) values.
|
|
* `ValueType::SCALAR`: Values of any scalar type (including arrays, excluding objects), serialized as specified in the settings.
|
|
Using SCALAR worsens performances, please use any of the other types if possible.
|
|
* `ValueType::OBJECT`: Objects extending DbObject, serialized as specified in the settings.
|
|
|
|
One of the most important value types is `ValueType::OBJECT`, it is used to store entire objects extending the `DbObject` class to the database.
|
|
|
|
Objects extending `DbObject` have a special `save` method that can be used to persist object changes to the database.
|
|
|
|
```php
|
|
$fieldConfig = new DbArrayBuilder(
|
|
'tableName',
|
|
$settings,
|
|
KeyType::STRING,
|
|
ValueType::OBJECT
|
|
);
|
|
|
|
$db = $fieldConfig->build();
|
|
|
|
class MyObject extends DbObject
|
|
{
|
|
public function __construct(
|
|
public readonly string $value
|
|
) {
|
|
}
|
|
}
|
|
|
|
$db->set("a", new MyObject('v'));
|
|
$obj = $db->get("a");
|
|
|
|
var_dump($obj->value);
|
|
$obj->value = 'newValue';
|
|
$obj->save();
|
|
|
|
var_dump($db->get("a")->value); // newValue
|
|
```
|
|
|
|
## API Documentation
|
|
|
|
Click [here »](https://github.com/danog/AsyncOrm/blob/master/docs/docs/index.md) to view the API documentation.
|