README

基于 AMPHP v3 和 fibers 的异步 ORM，由 Daniil Gentili (https://daniil.it) 和 Alexander Pankratov (https://github.com/xtrime-ru) 创建。

支持 MySQL、Redis、Postgres。

具有读取和写入缓存、类型特定优化等功能！

此 ORM 库最初是为 MadelineProto 创建的，它是一个异步 PHP 客户端 API，用于 Telegram MTProto 协议。

安装

composer require danog/async-orm

用法

使用 ORM 的两种主要方式：通过自动 ORM 属性，它自动将适当标记的 DbArray 属性连接到指定的数据库，或者通过手动使用 DbArrayBuilder 实例化 DbArray。

通过以下方法之一获得的 DbArray 是一个抽象数组对象，它自动从指定的数据库存储和检索指定 类型 的元素。

类型为 ValueType::OBJECT 的 DbArray 可以包含扩展 DbObject 的对象。

扩展 DbObject 的类有一个特殊的 save 方法，可以用于将对象更改持久化到数据库，如 示例 所示。

自动 ORM 属性示例

<?php declare(strict_types=1);

use Amp\Mysql\MysqlConfig;
use Amp\Postgres\PostgresConfig;
use Amp\Redis\RedisConfig;
use danog\AsyncOrm\Annotations\OrmMappedArray;
use danog\AsyncOrm\DbArray;
use danog\AsyncOrm\DbAutoProperties;
use danog\AsyncOrm\DbObject;
use danog\AsyncOrm\KeyType;
use danog\AsyncOrm\Settings;
use danog\AsyncOrm\Settings\MysqlSettings;
use danog\AsyncOrm\Settings\PostgresSettings;
use danog\AsyncOrm\Settings\RedisSettings;
use danog\AsyncOrm\ValueType;

require __DIR__ . '/../vendor/autoload.php';

// Any of the following database backends can be used,
// remove the ones you don't need.
$settings = new MysqlSettings(
    new MysqlConfig(
        host: "/var/run/mysqld/mysqld.sock",
        user: 'user',
        password: 'password',
        database: 'database'
    ),
    cacheTtl: 100
);
$settings = new PostgresSettings(
    new PostgresConfig(
        host: "127.0.0.1",
        user: "user",
        password: "password",
        database: "database"
    ),
    cacheTtl: 100
);
$settings = new RedisSettings(
    RedisConfig::fromUri("redis://127.0.0.1"),
    cacheTtl: 100
);

/**
 * An object stored in a database.
 */
class MyObject extends DbObject
{
    public function __construct(
        private string $value
    ) {
    }
    public function setValue(string $value): void
    {
        $this->value = $value;
    }
    public function getValue(): string
    {
        return $this->value;
    }
}

/**
 * Main class of your application.
 */
final class Application
{
    use DbAutoProperties;

    /**
     * This field is automatically connected to the database using the specified Settings.
     *
     * @var DbArray<string, MyObject>
     */
    #[OrmMappedArray(KeyType::STRING, ValueType::OBJECT)]
    private DbArray $dbProperty1;

    /**
     * This field is automatically connected to the database using the specified Settings.
     *
     * @var DbArray<string, int>
     */
    #[OrmMappedArray(KeyType::STRING, ValueType::INT)]
    private DbArray $dbProperty2;

    public function __construct(
        Settings $settings,
        string $tablePrefix
    ) {
        $this->initDbProperties($settings, $tablePrefix);
    }

    public function businessLogic(): void
    {
        $this->dbProperty1['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->dbProperty1['someOtherKey'];
        $obj->setValue($value);
        $obj->save();
    }

    public function businessLogic3(): string
    {
        return $this->dbProperty1['someOtherKey']->getValue();
    }

    public function shutdown(): void
    {
        // Flush all database caches, saving all changes.
        $this->saveDbProperties();
    }
}

$app = new Application($settings, 'tablePrefix');
$app->businessLogic();
$app->businessLogic2("newValue");
var_dump($app->businessLogic3());
$app->shutdown();

手动 ORM 属性示例

请参阅这里。

设置

如上例所示，有多个设置类，可用于连接到特定数据库类型

• MysqlSettings: MySQL 后端设置。
• PostgresSettings: Postgres 后端设置。
• RedisSettings: Redis 后端设置。

所有这些类都有多个字段，具体请参阅各自的文档（单击每个类名查看）。

缓存

最重要的设置之一是 cacheTtl 字段，它指定读取和写入缓存的持续时间。

如果非零，则从数据库检索的所有数组元素都将存储在内存中的 读取缓存 中，持续指定的时间（秒）；对同一字段的多次访问将分别推迟该字段的刷新 cacheTtl 秒。

应用程序写入数组的所有元素也将存储在内存中的 写入缓存 中，并且每 cacheTtl 秒刷新到数据库。

如果数组具有 对象值类型 (ValueType::OBJECT)，则禁用写入缓存。

如果 cacheTtl 为 0，则禁用读取和写入缓存。

特殊设置类用于创建不基于数据库的 DbArray，在某些情况下也可能很有用

• MemorySettings: MemorySettings 后端设置。

键和值类型

每个 DbArray 必须具有特定的键和值类型。

为了最佳性能，指定的类型必须尽可能严格，以下是允许的类型列表

键类型

• KeyType::STRING - 仅字符串键
• KeyType::INT - 仅整数键
• KeyType::STRING_OR_INT - 字符串或整数键（不推荐，出于性能原因，请始终指定 STRING 或 STRING_OR_INT）。

值类型

• ValueType::STRING：直接存储UTF-8字符串值。
• ValueType::INT：直接存储整数值。
• ValueType::BOOL：直接存储布尔值。
• ValueType::FLOAT：直接存储浮点数（双精度）值。
• ValueType::SCALAR：任何标量类型的值（包括blob和数组，不包括对象），按照设置进行序列化。使用SCALAR会降低性能，如果可能，请使用其他任何类型。
• ValueType::OBJECT：扩展DbObject的对象，按照设置进行序列化。

最重要的值类型之一是 ValueType::OBJECT，它用于将扩展了DbObject类的整个对象存储到数据库中。

扩展DbObject的对象有一个特殊的save方法，可以用来将对象更改持久化到数据库中，如示例中所示。

API 文档

点击这里查看API文档。