README

特性

ActiveRecord 数据模型，可以以数组形式指定各种数据库搜索条件。

DataModel 方法

PDO 注入

• Model::setPDOInstance(PDO $pdo, string $name='default'): void 支持保留多个 PDO 对象
• Model::getPDOInstance(string $name='default'): PDO 获取指定名称的 PDO 对象

日志相关

• Model::setLogger(LoggerInterface$logger): void
  • 指定日志器以输出 SQL 查询
• Model::getLogger(): LoggerInterface
  • 获取日志器。未指定时返回 NullLogger 实例

模型定义相关

• Model::getTableName(): string
• Model::loadSchema(array $schema): void
  • 读取表架构。
  • iamcal/sql-parser 的输出文件可直接指定。
• Model::getFieldNames(bool $with_hidden=false): array
• Model::getField(string $name): ?array
• Model::getIndexes(): array
• Model::getPrimaryKeys(): array
• Model::_isPrivate(bool $field): bool

实例数据操作

• $model->__set(string $field, $value): void
• $model->set(string $key, $value): void
• $model->__get(string $field)
• $model->get($key, $default=null)
• $model->setData($data=null): void
• $model->getData($with_hidden=false): array
• $model->setDirtyField(string $field, $value): void
• $model->isDirty($fields=null): bool
• $model->convertData($data): array
• $model->getKeyNotFoundMessage(string $key): string

数据库操作

• Model::find(array $params=[], ?array $opts=null, ?PDO $pdo=null): array
• Model::findById($data, ?array $opts=null, ?PDO $pdo=null)
• Model::findOne(array $params=[], ?array $opts=null, ?PDO $pdo=null)
• Model::count(array $params=[], ?array $opts=null, ?PDO $pdo=null): int
• Model::paginate($params): array
• $model->insert(?PDO $pdo=null, $ignore=false): void
• $model->update(?PDO $pdo=null, bool $diff=false): self
• $model->delete(?bool $hard=false, ?PDO $pdo=null): self

实用工具

• $model->convertJsonFields($data): array
• backupLoaded(): void
• getDiffs(): array
• getMsecDate(): string
• setDiffs(): void

DataModel 属性

• soft_delete_field : 将指定的字段作为逻辑删除字段进行搜索等操作
• json_fields : 指定要编码/解码为 JSON 的字段
  • 在实例保存时自动对目标字段进行 JSON 序列化
  • 通过实例属性或 $model->get(), $model->getData() 获取数据时，将自动转换为数组数据
  • 在 find() 系方法输出数组时，不会进行 JSON 化。如果需要，可以使用 Model::convertJsonFields($data) 进行转换。
• 如果未设置 updated_at 的值，将自动赋予值
  • 如果手动设置值，则用该值覆盖

find(array $params=[], ?array $opts=null, ?PDO $pdo=null)

• $params 搜索条件的参数关联数组

[
    Sql::SELECT => [], // 指定が有る場合は、モデルインスタンスではなく配列を返す
    Sql::JOIN   => [  // 指定が有る場合は、モデルインスタンスではなく配列を返す
        [
            'inner' => ['table_a tbl_a', [
                ['tbl_a.tbl_id', 'tbl.id'],
                ['tbl_a.deleted_at' => null],
                ['tbl_a.owner_id' => [Sql::EQ => 999]]
            ]]
        ]
    ],
    Sql::WHERE  => [
        Sql::OP_OR => [
            ['field1' => 'value1'], // 省略時は self::OP_EQ
            ['field2' => [Sql::OP_NE => 'value2']],
            [Sql::OP_AND => [
                ['field3' => [Sql::OP_GE => 'value3']],
                ['field4' => [Sql::OP_LT => 'value4']]
            ],
        ]
    ],
    Sql::ORDER_BY => [],
    Sql::LIMIT => M, // 数値
    Sql::OFFSET => N, // 数値
    Sql::FOR_UPDATE => false / true
]

• SELECT 可指定的条件：以下任一字符串表示的数组元素

  • 'table.field alias' 使用反引号括起来的 table, field
  • 'table.field' 使用反引号括起来的 table, field
  • 'field' 使用反引号括起来的 field
  • '@@...' 无转换地作为 SQL 输出

• 未指定 SELECT 时，Model::getFieldNames() 将被设置

• JOIN 可指定的条件：包含 INNER 或 OUTER JOIN 条件的数组

  • ※※※ INNER 或 OUTER JOIN 条件数组本身不工作，需要包含多个 JOIN 条件的外部数组 ※※※
  • Sql::INNER | Sql::OUTER => ['tablename_to_join alias', [ON 约束条件, ...]]
    • ※※※ ON 约束条件本身不工作，需要包含多个约束条件的外部数组 ※※※
    • 指定了多个 ON 约束条件时，将自动使用 AND 约束
    • ON 约束条件的格式请参考搜索条件
  • 'tablename_to_join alias' 部分可以使用 [tablename, alias] 的形式
    • 这样可以在 tablename 部分指定子查询

• WHERE 可指定的条件：搜索条件、或者由 AND 或 OR 括起来的多个搜索条件

  • 单个搜索条件
  • 以 Sql::AND 或 Sql::OR 为键的关联数组，值是包含多个搜索条件的数组

• 搜索条件：以字段名为键的关联数组

  • ['field2' => [Sql::OP_NE => 'value2']] // 值是包含比较运算符的键和比较对象的值
  • ['field1' => 'value1'] // 值为单一值时，省略比较运算符则默认为等于

• 排序条件：以下任一字符串表示的数组元素

  • 'table.field [ASC | DESC]'
  • 'field [ASC | DESC]'
  • 'alias [ASC | DESC]'

• $opts 选项

[
    static::WITH_HIDDEN  => false|true,
    static::WITH_DELETED => false|true,
    static::FETCH_MODE   => PDO::FETCH_FUNC | PDO::FETCH_ASSOC | PDO::FETCH_CLASS,
    static::FOR_UPODATE  => false|true
]

findById($data, ?array $opts=null, ?PDO $pdo=null)

• $data 包含主键和值的关联数组或类实例
• $opts, $pdo 与 find() 相同
• 未指定 $opts 的 FETCH_MODE 时，返回模型类的实例
• 结果超过 1 件时抛出异常，0 件时返回 null

findOne(array $params=[], ?array $opts=null, ?PDO $pdo=null)

• $params 可以唯一确定结果的一个字段和值的关联数组
  • 省略 Sql::WHERE
  • 多个条件的连接仅使用 AND，省略 Sql::AND 键
  • 多个搜索无需分别分割到各个数组中，而应汇总到一个关联数组中 ['field1' => [EQ => 'value1'], 'field2' => [EQ => 'value2']]
• $opts, $pdo 与 find() 相同
• 未指定 $opts 的 FETCH_MODE 时，返回模型类的实例
• 结果超过 1 件时抛出异常，0 件时返回 null