README

“我们可以通过引入额外一层间接性来解决任何问题。”

索引

简介
安装
设置
使用模型
重用模型
配置模型
- 数据库
- 表
- 列
- 主键
- 自动增长
- 时间戳列
- 可选列
- 外键
- 只读
- 软删除
- 软删除模式
高级
- 事件
- ModelManager
变更日志

简介

一个用于数据库相关模型的基框架。

使用此框架，只需为模型配置最少的内容，然后您就可以专注于自己的代码。抽象化与数据库的通信！

为您的应用程序创建新模型很简单，只需扩展 Model 基类并定义一些设置。

为了与数据库交互，使用 catfan/Medoo。

安装

在项目目录中打开终端并运行

composer require aryelgois/medools

设置

在开始使用此框架之前，您需要在应用程序的某个位置创建一个配置文件。它定义了模型可以访问的服务器和数据库。

配置文件为 .php 的原因是它包含敏感数据，如果客户端可以请求它，则不会返回任何内容。

基本上，它包含实例化 catfan/Medoo 对象所需的数据。有关详细信息，请参阅其指南。您还可以参考配置示例。

此文件返回一个包含以下键的数组

servers: 列出可连接的数据库服务器及其凭据。每个项目是一个具有以下键的数组
- server
- port (可选)
- username
- password
- database_type 它需要相应的 PHP_PDO 扩展
databases: 模型类中引用的数据库列表。每个项目是一个包含以下内容的数组
- server 上一列表中的服务器键。如果省略，则使用 default
- database_name
将数据库直接作为字符串设置是仅定义 database_name 的快捷方式

还可以使用其他配置，请参阅指南了解更多信息。您可以在合理的地方添加它们。连接到数据库时，其数组将合并到服务器数组之上。这意味着数据库可以覆盖服务器配置。

如果数据库服务器不是 servers 键，则将其原样使用。因此，服务器数组完全是可选的，只要数据库包含连接到数据库所需的所有数据即可。

此配置文件的主要目的是您可以在同一个服务器中定义多个数据库，而不必重复其配置，还可以在不同的服务器中定义数据库。

此外，您需要将此行包含在代码的开头

<?php

aryelgois\Medools\MedooConnection::loadConfig('path/to/config/medools.php');

将类似 bootstrap.php 的内容放入其中是一个好主意，这需要 composer 的自动加载（在上述行之前），并且您的脚本总是需要它。

MedooConnection 的工作方式类似于 Medoo 工厂，但它重用其实例。

使用模型

创建新模型

您可以通过不带任何参数的实例化新的 Model，来创建一个新的模型对象。然后像在其他对象中一样添加数据到其列。您的代码应该知道哪些列可用，但您可以从该模型调用 getColumns() 获取完整的列列表。

您的更改保存在该对象中，因此您需要调用 save() 才能将其发送到数据库。

从数据库加载

使用其 PRIMARY_KEY 的值来实例化模型，或指定一个关联数组，其中包含您想要筛选的列。只加载一行。

您也可以在创建对象后调用 load()。

保存到数据库

使用 save() 将所有更改发送到数据库，并使用 update() 只发送一些。

由于某些验证过程或数据库默认值，某些您可能已更改的列之后的值可能会有所不同。

从数据库删除

只需使用 delete()。

如果模型已配置 SOFT_DELETE，则它将只更新该列。因此，您可以稍后调用 undelete()。

否则，它将从数据库中完全删除该行，并重置模型对象。

您可以使用 isDeleted() 来检查模型是否被删除。当配置了 SOFT_DELETE 时，这很有用。

访问和操作数据

就像在任何一个对象中一样

$model->column 将返回存储的数据，或一个外键模型 *
$model->column = value 将设置新数据

* 这意味着您可以链接模型
$model->foreign->column

您还可以使用以下方式获取数据

dump()：从模型表返回数据，您可以根据需要筛选您想要的数据行和列
getPrimaryKey()：返回最后保存的主键
toArray()：以数组形式返回模型中的数据（包括外键）

您可以通过以下方式更改数据

fill()：从列 => 值的数组中设置多个列。它返回对象（可链接）

迭代多行

ModelIterator 提供了访问多行，但它一次只提供一行。

给它一个您想要迭代的模型类，以及一些筛选数组。然后它将逐行 load() 每个匹配的行。

您可以直接从模型类中调用 getIterator() 作为快捷方式，这只需请求 $where。

外模型

此框架支持外键模型。您可以在模型类中配置它们，并访问 $model->foreign_column。它们只是其他模型，在您的模型中引用。

它们按需加载，因此您不必担心仅因为您想从模型中获取单个列就加载大量的外键。

⚠️ 警告：请注意不要配置循环外键约束。在序列化模型时，可能会因为递归而失败。

其他方法

可用的有用方法

__isset()：与 isset 一起使用，用于检查列是否为 null
__unset()：与 unset 一起使用，用于将列设置为 null
__wakeup()：您可以反序列化一个模型，即保存到 $_SESSION 并在另一个请求中恢复。
getChangedColumns()：列出已更改的列
getCurrentTimestamp()：从数据库中选择当前时间戳，用于保持时区一致
getData()：提供当前存储的数据
getDatabase()：提供对数据库的直接访问，已连接并准备使用。有关详细信息，请参阅catfan/Medoo
getRequiredColumns()：提供在保存之前必须设置的列列表
getStampColumns()：提供自动接收时间戳的列列表
isFresh()：判断该对象是否是新的模型
jsonSerialize()：您可以对模型进行json_encode！它会扩展外部模型
reload()：用于重新获取具有模型主键的行
undo()：删除更改。传递列名以仅删除该列，否则删除所有更改

您还可以在模型中添加自定义方法，以自动获取某些数据格式或执行特定任务。

还有由某些基方法自动调用的事件方法。

重用模型

为了避免为同一模型创建多个实例，存在一个ModelManager类，其中包含对已创建的模型的指针。要检索它们，请使用getInstance()方法，该方法请求一个模型类和一个where子句（仅选择一行）。快捷方式是从模型直接调用getInstance()，它仅请求$where。

有关详细信息，请参阅高级部分。

如果您愿意，您仍然可以创建已存在模型的新的实例。新对象将不包含旧对象中做出的更改。

配置模型

设置是每个模型类中的常量。您可以省略一些以从父类重用。

定义新模型时，只需TABLE和COLUMNS。

数据库

Medools配置文件中的数据库键

类型：string
默认：'default'

表

模型表示的数据库表

建议使用表名复数形式和模型名单数形式

类型：string

列

模型期望存在的列

类型：string[]
默认：['id']

列后可能跟有一个首选的数据类型。如果没有指定，则默认为 string

<?php

const COLUMNS = [
    'id [Int]',
    'name',
    'data [JSON]',
];

可能类型是Medoo支持的类型

布尔
整数
JSON
数字
对象
字符串

这些类型在访问数据库中的列时使用，但由于Medoo具有类型自动检测功能，因此只需Object和JSON即可自动反序列化/解码数组和对象。您仍然可以使用其他类型进行显式类型转换。

请注意，可以为可空/可选列设置null值。

主键

主键列或列

类型：string[]
默认：['id']

自动增长

自动递增列

类型：string|null
默认：'id'

时间戳列

要自动接收当前时间戳的列列表

类型：string[]
值：'auto'、'date'、'time'或'datetime'
默认：'datetime'

这些列在save()和update()时自动更新为当前时间戳。此常量允许多个时间戳列。如果列被手动更改，则不会覆盖。

这些列是隐式可选的，因为它们在保存/更新模型之前会被更改。例外是 auto 列，这些列必须由数据库控制（MySQL 只允许一个 timestamp）。

以下结构是有效的

<?php

const STAMP_COLUMNS = [
    'column_a' => 'datetime',
    'column_b',
    'column_c' => 'date',
];

在这里，column_b 将使用默认值。

可选列

具有默认值或可空的列列表

您不需要包含隐式可选列，如 AUTO_INCREMENT、STAMP_COLUMNS 和 SOFT_DELETE。

类型：string[]

外键

外键映射

当前模型中指向另一个模型中列的列映射

类型：array[]

示例

<?php

const FOREIGN_KEYS = [
    'local_column' => [
        'Fully\\Qualified\\ClassName',
        'foreign_column'
    ],
];

如果外部类在同一命名空间中，可以使用 ClassName::class。

只读

如果 __set()、save()、update()、delete() 和 undelete() 被禁用

类型：boolean
默认：false

软删除

如果 delete() 实际上删除了行或更改了列

它定义了软删除影响的列

类型：string|null
默认：null

此列是隐式可选的，因此您必须在数据库模式中相应地定义默认值，以符合 SOFT_DELETE_MODE。

软删除模式

软删除的工作方式

应该将 SOFT_DELETE 设置为哪个值。

类型：string
默认：'deleted'

高级

事件

有一些方法可以通过重写事件方法来扩展。这使得扩展某些功能变得更加容易。

目前，这些事件可用

onColumnChange()：当列更改时调用。在将数据存储在模型中之前过滤数据很有用
onFirstSave()：当模型第一次保存时调用
onSave()：每次模型保存时调用
onValidate()：在将数据存储在数据库之前需要验证数据时调用

ModelManager

此类跟踪请求期间加载的每个模型。它旨在避免模型重复，主要是在外键中。

如果您为已存在的模型创建了一个新实例，新实例将替换此类中的旧实例，但指向旧实例的其他指针不会更新。为了避免这种情况，请使用此类或模型中提供的 getInstance() 方法。

aryelgois / medools

维护者

详细信息