This commit is contained in:
Daniil Gentili 2024-03-31 19:37:48 +02:00
parent 25e19238ad
commit 9110d6692c
38 changed files with 127 additions and 56 deletions

View File

@ -4,7 +4,9 @@ Async ORM based on amphp, created by Daniil Gentili <daniil@daniil.it> and Alexa
Supports MySQL, Redis, Postgres.
Features read and write-back caching, type-specific optimizations, and much more!
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
@ -19,20 +21,89 @@ There are two main ways to use the ORM: through automatic ORM properties, which
* [Automatic ORM properties example &raquo;](https://github.com/danog/AsyncOrm/blob/master/examples/1-automatic.php)
* [Manual example &raquo;](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 from the specified database.
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
/** @var DbArray<TKey, TValue> $arr */
$fieldConfig = new DbArrayBuilder(
'tableName',
$settings,
KeyType::STRING,
ValueType::OBJECT
);
$value = $arr[$key];
$arr[$key] = $newValue;
$db = $fieldConfig->build();
if (isset($arr[$otherKey])) {
// Some logic
unset($arr[$otherKey]);
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 &raquo;](https://daniil.it/AsyncOrm/docs) to view the API documentation.
Click [here &raquo;](https://github.com/danog/AsyncOrm/blob/master/docs/docs/index.md) to view the API documentation.

View File

@ -71,17 +71,17 @@ final class Application
/**
* This field is automatically connected to the database using the specified Settings.
*
* @var DbArray<string, int>
* @var DbArray<string, MyObject>
*/
#[OrmMappedArray(KeyType::STRING, ValueType::INT)]
#[OrmMappedArray(KeyType::STRING, ValueType::OBJECT)]
private DbArray $dbProperty1;
/**
* This field is automatically connected to the database using the specified Settings.
*
* @var DbArray<string, MyObject>
* @var DbArray<string, int>
*/
#[OrmMappedArray(KeyType::STRING, ValueType::OBJECT)]
#[OrmMappedArray(KeyType::STRING, ValueType::INT)]
private DbArray $dbProperty2;
public function __construct(
@ -93,23 +93,23 @@ final class Application
public function businessLogic(): void
{
// Can store integers, strings, arrays or objects depending on the specified ValueType
$this->dbProperty1['someKey'] = 123;
var_dump($this->dbProperty1['someKey']);
$this->dbProperty1['someOtherKey'] = new MyObject("initialValue");
$this->dbProperty2['someOtherKey'] = new MyObject("initialValue");
// Can store integers, strings, arrays or objects depending on the specified ValueType
$this->dbProperty2['someKey'] = 123;
var_dump($this->dbProperty2['someKey']);
}
public function businessLogic2(string $value): void
{
$obj = $this->dbProperty2['someOtherKey'];
$obj = $this->dbProperty1['someOtherKey'];
$obj->setValue($value);
$obj->save();
}
public function businessLogic3(): string
{
return $this->dbProperty2['someOtherKey']->getValue();
return $this->dbProperty1['someOtherKey']->getValue();
}
public function shutdown(): void

View File

@ -18,7 +18,7 @@
* @author Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2023 Daniil Gentili <daniil@daniil.it>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm;

View File

@ -17,7 +17,7 @@
* @author Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm;

View File

@ -20,7 +20,7 @@
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Alexander Pankratov <alexander@i-c-a.su>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm;

View File

@ -20,7 +20,7 @@
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Alexander Pankratov <alexander@i-c-a.su>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm;

View File

@ -20,7 +20,7 @@
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Alexander Pankratov <alexander@i-c-a.su>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Driver;

View File

@ -20,7 +20,7 @@
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Alexander Pankratov <alexander@i-c-a.su>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Driver;

View File

@ -20,7 +20,7 @@
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Alexander Pankratov <alexander@i-c-a.su>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Driver;

View File

@ -13,7 +13,7 @@
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Alexander Pankratov <alexander@i-c-a.su>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Internal\Containers;

View File

@ -13,7 +13,7 @@
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Alexander Pankratov <alexander@i-c-a.su>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Internal\Containers;

View File

@ -13,7 +13,7 @@
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Alexander Pankratov <alexander@i-c-a.su>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Internal\Containers;

View File

@ -20,7 +20,7 @@
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Alexander Pankratov <alexander@i-c-a.su>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Internal\Driver;

View File

@ -20,7 +20,7 @@
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Alexander Pankratov <alexander@i-c-a.su>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Internal\Driver;

View File

@ -20,7 +20,7 @@
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Alexander Pankratov <alexander@i-c-a.su>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Internal\Driver;

View File

@ -20,7 +20,7 @@
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Alexander Pankratov <alexander@i-c-a.su>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Internal\Driver;

View File

@ -20,7 +20,7 @@
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Alexander Pankratov <alexander@i-c-a.su>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Internal\Driver;

View File

@ -20,7 +20,7 @@
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Alexander Pankratov <alexander@i-c-a.su>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Internal\Serializer;

View File

@ -20,7 +20,7 @@
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Alexander Pankratov <alexander@i-c-a.su>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Internal\Serializer;

View File

@ -20,7 +20,7 @@
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Alexander Pankratov <alexander@i-c-a.su>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Internal\Serializer;

View File

@ -20,7 +20,7 @@
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Alexander Pankratov <alexander@i-c-a.su>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Internal\Serializer;

View File

@ -20,7 +20,7 @@
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Alexander Pankratov <alexander@i-c-a.su>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Internal\Serializer;

View File

@ -20,7 +20,7 @@
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Alexander Pankratov <alexander@i-c-a.su>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Internal\Serializer;

View File

@ -18,7 +18,7 @@
* @author Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2023 Daniil Gentili <daniil@daniil.it>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm;

View File

@ -20,7 +20,7 @@
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Alexander Pankratov <alexander@i-c-a.su>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm;

View File

@ -20,7 +20,7 @@
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Alexander Pankratov <alexander@i-c-a.su>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Serializer;

View File

@ -20,7 +20,7 @@
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Alexander Pankratov <alexander@i-c-a.su>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Serializer;

View File

@ -20,7 +20,7 @@
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Alexander Pankratov <alexander@i-c-a.su>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Serializer;

View File

@ -18,7 +18,7 @@
* @author Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2023 Daniil Gentili <daniil@daniil.it>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm;

View File

@ -18,7 +18,7 @@
* @author Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2023 Daniil Gentili <daniil@daniil.it>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Settings;

View File

@ -18,7 +18,7 @@
* @author Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2023 Daniil Gentili <daniil@daniil.it>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Settings;

View File

@ -18,7 +18,7 @@
* @author Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2023 Daniil Gentili <daniil@daniil.it>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Settings;

View File

@ -18,7 +18,7 @@
* @author Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2023 Daniil Gentili <daniil@daniil.it>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Settings;

View File

@ -18,7 +18,7 @@
* @author Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2023 Daniil Gentili <daniil@daniil.it>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Settings;

View File

@ -18,7 +18,7 @@
* @author Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2023 Daniil Gentili <daniil@daniil.it>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm\Settings;

View File

@ -18,7 +18,7 @@
* @author Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2023 Daniil Gentili <daniil@daniil.it>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\AsyncOrm;
@ -51,7 +51,7 @@ enum ValueType: string
/**
* Values of any scalar type, serialized as specified in the settings.
*
* Using SCALAR worsens performances, please use any of the other types possible.
* Using SCALAR worsens performances, please use any of the other types if possible.
*/
case SCALAR = 'scalar';
}

View File

@ -18,7 +18,7 @@
* @author Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\TestAsyncOrm;

View File

@ -18,7 +18,7 @@
* @author Daniil Gentili <daniil@daniil.it>
* @copyright 2016-2024 Daniil Gentili <daniil@daniil.it>
* @license https://opensource.org/license/apache-2-0 Apache 2.0
* @link https://daniil.it/AsyncOrm AsyncOrm documentation
* @link https://github.com/danog/AsyncOrm AsyncOrm documentation
*/
namespace danog\TestAsyncOrm;