Db - APIPHP开源框架

>i 本文档的最新修订日期是： > **2024-02-28** # Db :: 本模块底层通过 `PDO` 驱动，进行 `CURD` （增删改查）以及执行自定义SQL语句的操作。 >d 良好的数据库命名习惯是开发优秀程序的必要条件，一时偷懒，遗臭万年。本模块中数据库名称、表名称、字段名只允许由这些ASCII字符组成：`[0-9,a-z,A-Z$_]`，否则可能会出现错误。 >w 尽管PDO能够连接多种数据库，但本模块仍然以 `MySQL` （或兼容MySQL语法的其他数据库）作为主要适配的数据库，并基于此衍生出各种功能特性。也就是说，本模块无法确保在其它数据库中拥有完全一致的使用效果，甚至可能在其他数据库无法使用，这取决于其他数据库对MySQL语法的兼容程度。 # 依赖本模块依赖于基础模块 `Log` 。 # 模块配置配置文件位于 `/config/core/Db.php` 。 * **`log`** `(Bool)` `false` ：用以指定是否将最终执行的SQL语句以 `debug` 级别提交到日志缓存中。 `true` 代表提交到日志、`false` 代表不提交到日志，默认不提交到日志。日志缓存是否会被写入日志文件，取决于 `Log` 模块的相关配置。 * **`dbInfo`** `(Array)` `（省略）` ：此配置项为一个二维数组（Array），用以指定数据库信息。在第一维数组中， `键` 为配置组名称， `值` 为一个数组，且该数组（即第二维数组）只能有以下六个元素： * `type` ：值为数据库驱动类型。取值范围可查阅 [PDO驱动列表](https://www.php.net/manual/zh/pdo.drivers.php) 以及 [获取可用的PDO驱动](https://www.php.net/manual/zh/pdo.getavailabledrivers.php) 。 * `address`：值为数据库地址。如果非远程数据库，请使用默认值 `localhost` 。 * `username`：值为数据库用户名。 * `password`：值为数据库密码。 * `dbname`：值为数据库名称。 * `port`：值为数据库端口号。 * **`default`** `(String)` `'default'`：用以指定默认链接的数据库的名称。值必须为配置项 `dbInfo` 中第一维数组中任意一个元素的键名。 * **`tableAlias`** `(Array)` `[]`：用以指定表的别名。数组元素的键为别名名称，元素的值为对应的真实表名称。 # 公共参数 ## 数据库的指定 * **`db_name（数据库）`** `(String)` `''`：用以指定所操作的数据库的名称。本参数的值必须为配置项 `dbInfo` 中第一维数组中任意一个元素的键名。除 `choose` 方法外，指定本参数不会影响后续操作所使用的数据库，即如果后续操作未指定本参数，则仍然使用默认的数据库。除了使用本参数，还支持在字段、表名中指定数据库。 ## 表的指定 * **`table（表）`** `(Array)` `<必须>`：用以指定所操作的数据表表名。数组键无需定义，每一个元素的值代表一个需要操作的表。如需操作多库，可以将元素的值设置为 `<库名>.<表名>`，例如 `db1.users` 代表的就是 `db1` 数据库的 `users` 表。 >i 通过本方式操作多数据库，请确保连接所使用的账号对需要操作的多个数据库有相应的权限。 ## WHERE子句 * **`field（字段）`** `(Array)` `[]`：用以指定查询条件中的字段。数组键无需定义，每一个元素的值代表一个限制条件，且元素与参数 `value` 以及参数 `condition` （如果传入）中的元素保持相互对应。 * **`value（值）`** `(Array)` `[]`：用以指定查询条件中字段对应的值。数组键无需定义，每一个元素的值代表一个字段，且元素与参数 `field` 以及参数 `condition`（如果传入）中的元素保持相互对应。如果传入的字段对应的值是一个数组（即第一维数组中的元素的值仍为数组），将自动转换为 `JSON字符串` 。 * **`condition（条件）`** `(Array)` `[]`：用以确定参数 `field` 和参数 `value` 之间的比较符以及与下一个条件之间的并列关系，以及指定各个条件之间的优先级关系。当本参数为 `String` 类型时，表示仅限定一个查询条件。当本参数为 `Array` 类型时，数组键 `无需定义` ，值为 `[前置括号,][比较符][,后置括号][,并列关系]` 的字符串，并且每一个元素与参数 `field` 和参数 `value` 中的元素保持相互对应。其中： * `前置括号` 为添加在该条件前的左括号，可以为0个或多个 `(`； * `比较符` 为字段与条件值之间的比较符（`=`，`!=`，`<`，`>`，`>=`，`<=` ，`<>`，`IS NULL`，`IS NOT NULL`，`LIKE`，`NOT LIKE`），默认为 `=`； * `后置括号` 为添加在条件值后、下一个并列关系符前的右括号，可以为0个或多个 `)`； * `并列关系` 为与下一个限制条件之间的并列关系（`and` 或 `or`，未被定义时默认值为 `and`）。如果元素为空字符串，或者未指定元素，那么等同于指定了元素值为 `'=,and'` 。在最终的SQL语句中，框架会根据传入的优先级参数的值，使用括号“()”对查询条件进行优先级的指定，例如： ```sql ... where `id` = '1' and ( `level` = 'a' or `class` > '3' ) ... ``` 若要实现上面的SQL语句，那么应该按下面的方式定义这三个参数： ```php $Field= [ 'id' , 'level' ,'class']; $Value= [ '1' , 'a' ,'3' ]; $Condition=[ '=,and' , '(,=,or' , '>,)' ]; ``` ## ORDER BY子句 * **`order（排序）`** `(Array)` `[]`：用以指定对结果排序时所依据的字段。数组键无需定义，每一个元素的值代表一个排序所依据的字段，且元素与参数 `desc` （如果传入）中的元素保持相互对应。 * **`desc（降序）`** `(Array)` `[]`：用以指定是否使用倒序的排序方式。数组键无需定义，每一个元素的值为一个字段排序所依据的方式，且元素与参数 `order` 中的元素保持相互对应。元素的值应为 `Bool` 类型，`true` 代表倒序、`false` 代表正序，元素不存在时默认正序。例如，将结果按照字段 `id` 正序排序，并且按照字段 `money` 倒序排序： ```php $Order=['id','money']; $Desc=[false,true]; ``` ## 更多子句 * **`limit（限制）`** `(Array)` `[]`：用以从 `位置偏移量` 为起始行取得 `指定行数` 的记录。数组的键无需定义，第一个元素定义 `位置偏移量（最小为0）`，第二个元素定义 `行数` 。例如，从结果中的第3行开始取15行： ```php $Limit=[2,15]; //偏移量从0开始计算，因此第一个元素的值应为3-1。 ``` >i 如果希望 `行数` 为查询结果的最大数量，请将值设置为 `-1` 。 * **`index（索引）`** `(Array)` `[]`：用以指定表索引的使用规则。数组键无需定义，元素与参数 `table` 中的元素保持相互对应，每一个元素的值即为对应表要使用的索引规则。如果参数 `table` 的值是字符串，则默认使用第一个元素作为索引规则。如果不存在对应的元素，则不指定对应表的索引规则。元素的值应该类似于如下形式： ```php $Index=['FORCE INDEX(`PRIMARY`)']; ``` 详细的规则语句，请参阅数据库说明文档。对于MySQL，可参阅如下文档： `v5.7`：[https://dev.mysql.com/doc/refman/5.7/en/index-hints.html](https://dev.mysql.com/doc/refman/5.7/en/index-hints.html) `v8.0`：[https://dev.mysql.com/doc/refman/8.0/en/index-hints.html](https://dev.mysql.com/doc/refman/8.0/en/index-hints.html) `v8.1`：[https://dev.mysql.com/doc/refman/8.1/en/index-hints.html](https://dev.mysql.com/doc/refman/8.1/en/index-hints.html) * **`group_by（分组）`** `(Array)` `[]`：用以指定对结果分组时所依据的字段。数组键无需定义，每一个元素的值代表一个排序所依据的字段。 * **`field_limit（字段限制）`** `(Array)` `[]`：用以指定取回结果的字段范围。当本参数为 `String` 类型时，表示仅指定一个取回的字段。当本参数为 `Array` 类型时，数组键无需定义，每一个元素的值代表一个需要取回的字段。 `*` 代表取回所有字段。如果需要使用 `AS` 关键字，请使用 `->` 代替。 * **`data（数据）`** `(Array)` `默认值见方法参数`：用以指定需要插入或更新的数据。本参数中 `键` 为字段名， `值` 为字段名所对应的值。如果传入的字段对应的值是一个数组（即第一维数组中的元素的值仍为数组），将自动转换为 `JSON字符串` 。 ## 其它参数 * **`row_count（行数统计）`** `(Bool)` `false`：是否统计数据库中受到操作执行影响的行数。当值为 `true` 时统计，值为 `false` 时不统计。 * **`unlock（解锁）`** `(Bool)` `false`：是否允许对不设条件地对整个数据表进行操作。当值为 `true` 时允许，值为 `false` 时不允许。仅当您的预期中会出现改动或删除表中所有记录时，此参数才应传入 `true` 。当出现全表操作，但参数值为 `false` 时，将产生报错。 * **`debug（调试）`** `(Bool)` `false`：是否终止程序并展现执行前的SQL。当值为 `true` 时，最终执行前的SQL字符串将会以报错的当时展现（此时执行流程已被终止，将不会执行SQL语句），当值为`false` 时不允许。当执行结果非预期时，可利用此参数检查其它参数是否正确的被传入。 * **`unlock（解锁）`** `(Bool)` `false`：是否允许对不设条件地对整个数据表进行操作。当值为 `true` 时允许，值为 `false` 时不允许。仅当您的预期中会出现改动或删除表中所有记录时，此参数才应传入 `true` 。当出现全表操作，但参数值为 `false` 时，将产生报错。 * **`json（json）`** `(Array)` `[]`：用以指定将查询结果中的哪些JSON格式的字段转换为JSON字符串对应的数组。数组键无需定义，字段名作为每一个元素的值，代表需要取回的字段。 * **`return_object（返回对象）`** `(Bool)` `false`：用以指定将JSON字符串转换为对象还是数组。当值为 `true` 时转换为对象，值为 `false` 时转换为数组。 # 原生模式：使用数据库函数、关键字或运算符在以下参数： * **`data（数据）`** 中数组元素的键名 * **`field（字段）`** 中数组元素的值 * **`field_limit（字段限制）`** 中数组元素的值如果字符串以 `#` 字符开头时，字符串将不再作为字段名处理，此时可以使用MySQL支持的各种关键字及函数，除了开头的 `#` 字符，其余字符将直接组装入SQL语句中。如果需要对SQL进行PDO参数绑定，可以用 `?` 作为PDO参数绑定的变量，并且： * 对于参数 **`field（字段）`**，应在参数 **`value（值）`** 中的对应位置传入需要PDO参数绑定的值。此时在参数 **`condition（条件）`** 参数中的 `比较符` 不生效，因此需要传入完整的SQL子句。 * 对于参数 **`data（数据）`**，在本模块 `update()` 方法中，应将键名对应的元素值设置为需要PDO参数绑定的值。在原生模式下，如需使用 `表别名` 功能，可以通过 <code>`</code>（反引号）将带有字段名包裹住，形如 <code>`<库名>.<表名>.<字段名>`</code> 或 <code>`<表名>.<字段名>`</code> 。框架会自动进行表别名替换，例如： ```php $Type=intval($_GET['type']); $Config = [ '表' => ['用户摘要表','用户详情表'], '字段' => ['用户摘要表.enable','#`用户摘要表.type`>?','#`用户摘要表.id`=`用户详情表.id`'], '值' => ['0',$Type,''], '条件' => ['>=,AND'], '字段限制' => ['用户摘要表.*'], ]; $Result= \core\Db::selectMore($Config); ``` # 指定数据类型在以下参数： * **`data（数据）`** 中数组元素的键名 * **`field（字段）`** 中数组元素的值 * **`field_limit（字段限制）`** 中数组元素的值在使用MySQL内置JSON函数检索数据时，需要准确指定数据类型才可正确检索。因此，在以上参数中，如果字符串以 `(*)` 开头时，将能够为绑定的参数指定数据类型，否则将绑定的参数作为字符串处理。其中， `*` 可以为这些数据类型： `BOOL|NULL|INT|STR|STR_NATL|STR_CHAR|LOB` 。有关这些数据类型的详细含义，请参阅 [https://www.php.net/manual/zh/pdo.constants.php](https://www.php.net/manual/zh/pdo.constants.php) 。如果需要对SQL进行PDO参数绑定，可以用 `?` 作为PDO参数绑定的变量，并且：在原生模式下，依然可以指定数据类型，例如： ```php $Price=intval($_GET['price']); $Config = [ '表' => ['商品信息表'], '字段' => ['(int)#`price`-> \'$.price_online\' <= ?'], '值' => $Price ]; $Result= \core\Db::selectMore($Config); ``` # 操作多库多表如需操作多库多表，可以将传入的字段名设置为 `<库名>.<表名>.<字段名>` 或 `<表名>.<字段名>` ，例如 `student.id` 代表的就是 `student` 表的 `id` 字段。 >i 通过本方式操作多数据库，请确保连接所使用的账号对需要操作的多个数据库有相应的权限。仅对如下参数有效： * **`field_limit（字段限制）`** * **`group_by（分组）`** * **`desc（降序）`** * **`order（排序）`** * **`field（字段）`** * **`sum（合计）`** * **`data（数据）`** 中的数组键名 # 使用表别名在应用的初期开发中，可能会出现表名称需要调整的情况，如果将真实的表名称写入代码中，后期调整表名称时会非常麻烦。使用表别名，将显著增加代码可读性及解耦代码。表别名在参数 `sql` 中不生效。例如，配置文件中作如下定义： ```PHP <?php $_SERVER['APIPHP']['Config']['core\Db']=[ //已省略无关代码 'tableAlias'=>[ '商品摘要表'=>'goods_summary_list', '商品详情表'=>'goods_detail_list', ] ]; ``` 则可以作如下使用方式： ```PHP <?php $Config = [ '表' => ['商品摘要表','商品详情表'], '字段' => ['商品摘要表.state'], '值' => ['1'] '字段限制' => ['商品摘要表.*'] ]; $List = \core\Db::SelectMore($Config); ``` >i 表别名应当使用与真实表名不同的命名规则，例如使用中文、下划线、增加前缀等方式，增加代码可读性，避免别名与真实表名重复。 # choose() ## 说明 **Db :: choose ( <kbd>传参数组</kbd> )** 在预配置的多个数据库中选择一个数据库。此方法 `支持` 中文参数名。此方法 `支持` 参数简写。此方法会替代配置文件中 `default` 配置项的值，从而影响后续操作在未指定数据库情况下，所使用的默认数据库。 ## 参数以下参数详见本模块 `公共参数` 部分的说明： * **`db_name（数据库）`** `(String)` `<必须>` `可简写` ## 返回无。 # select() ## 说明 **Db :: select ( <kbd>传参数组</kbd> )** 查询单条数据表记录。本方法相比于 `SelectMore` 方法，更适合于例如查询用户信息这样单一的数据，性能更优异。此方法 `支持` 中文参数名。此方法 `支持` 参数简写。 ## 参数以下参数详见本模块 `公共参数` 部分的说明： * **`table（表）`** `(Array)` `<必须>` `可简写` * **`field（字段）`** `(Array)` `[]` * **`value（值）`** `(Array)` `[]` * **`condition（条件）`** `(Array)` `[]` * **`order（排序）`** `(Array)` `[]` * **`desc（降序）`** `(Array)` `[]` * **`index（索引）`** `(Int)` `[]` * **`field_limit（字段限制）`** `(Array)` `[]` * **`db_name（数据库）`** `(String)` `''` * **`json（json）`** `(Bool)` `false` * **`debug（调试）`** `(Bool)` `false` * **`return_object（返回对象）`** `(Bool)` `false` ## 返回 `(Object|Array|Bool)` 类型。查询到记录时，返回值为一个数组，记录的每一个字段为一个 `键` ，每一个记录值为一个数组的 `值` ，且数组中键值的对应关系与记录中字段和记录值的对应关系相同。如果参数 `return_object（返回对象）` 传入的值为 `true` ，则返回的值类型为 `Object` 。当查询到的记录为空时，返回值为 `false` 。 # selectMore() ## 说明 **Db :: selectMore ( <kbd>传参数组</kbd> )** 查询多条数据表记录。此方法 `支持` 中文参数名。此方法 `支持` 参数简写。 ## 参数以下参数详见本模块 `公共参数` 部分的说明： * **`table（表）`** `(Array)` `<必须>` `可简写` * **`field（字段）`** `(Array)` `[]` * **`value（值）`** `(Array)` `[]` * **`condition（条件）`** `(Array)` `[]` * **`order（排序）`** `(Array)` `[]` * **`desc（降序）`** `(Array)` `[]` * **`limit（限制）`** `(Array)` `[]` * **`index（索引）`** `(Array)` `[]` * **`field_limit（字段限制）`** `(Array)` `[]` * **`group_by（分组）`** `(Array)` `[]` * **`db_name（数据库）`** `(String)` `''` * **`json（json）`** `(Bool)` `false` * **`debug（调试）`** `(Bool)` `false` * **`return_object（返回对象）`** `(Bool)` `false` ## 返回 `(Object|Array)` 类型。查询到记录时，返回值为 `二维数组` ，在第一维的数组中，键为从 `0` 开始的自增键，值为一行记录的集合的一维数组；在第二维数组中， `键` 为字段名， `值` 为该条记录中字段所对应的记录值。当查询到的记录为空时，返回值为一个 `空数组` 。如果参数 `return_object（返回对象）` 传入的值为 `true` ，则返回的值类型为 `Object` 。 # total() ## 说明 **Db :: total ( <kbd>传参数组</kbd> )** 统计符合条件的记录数量。此方法 `支持` 中文参数名。此方法 `支持` 参数简写。 ## 参数以下参数详见本模块 `公共参数` 部分的说明： * **`table（表）`** `(Int)` `<必须>` `可简写` * **`field（字段）`** `(Array)` `[]` * **`value（值）`** `(Array)` `[]` * **`condition（条件）`** `(Array)` `[]` * **`order（排序）`** `(Array)` `[]` * **`desc（降序）`** `(Array)` `[]` * **`limit（限制）`** `(Array)` `[]` * **`index（索引）`** `(Array)` `[]` * **`group_by（分组）`** `(Array)` `[]` * **`db_name（数据库）`** `(String)` `''` * **`debug（调试）`** `(Bool)` `false` ## 返回 `(Array)` 类型。当未指定 `group_by` 参数时，将直接返回符合条件的记录总数；否则将返回依据 `group_by` 参数分组而形成的结果集。 # sum() ## 说明 **Db :: sum ( <kbd>传参数组</kbd> )** 对符合条件的指定列的记录值进行累加，并将结果放在一行中。此方法 `支持` 中文参数名。此方法 `支持` 参数简写。 ## 参数 * **`sum（合计）`** `(Array)` `<必须>`：用以指定对结果分组时所依据的字段。每一个元素的键代表一个需要累加的字段，值代表该字段在结果中的字段别名。以下参数详见本模块 `公共参数` 部分的说明： * **`table（表）`** `(Array)` `<必须>` `可简写` * **`field（字段）`** `(Array)` `[]` * **`value（值）`** `(Array)` `[]` * **`condition（条件）`** `(Array)` `[]` * **`order（排序）`** `(Array)` `[]` * **`desc（降序）`** `(Array)` `[]` * **`limit（限制）`** `(Array)` `[]` * **`index（索引）`** `(Array)` `[]` * **`db_name（数据库）`** `(String)` `''` * **`debug（调试）`** `(Bool)` `false` ## 返回 `(Array)` 类型。将返回结果集。 # insert() ## 说明 **Db :: insert ( <kbd>传参数组</kbd> )** 插入数据，并返回新记录的主键。此方法 `支持` 中文参数名。 ## 参数以下参数详见本模块 `公共参数` 部分的说明： * **`table（表）`** `(Array)` `<必须>` * **`data（数据）`** `(Array)` `<必须>` * **`db_name（数据库）`** `(String)` `''` * **`debug（调试）`** `(Bool)` `false` ## 返回 `(Int)` 类型。值为插入成功后该行记录的主键。 # delete() ## 说明 **Db :: delete ( <kbd>传参数组</kbd> )** 删除符合条件的记录。此方法 `支持` 中文参数名。此方法 `支持` 参数简写。 ## 参数以下参数详见本模块 `公共参数` 部分的说明： * **`table（表）`** `(Array)` `<必须>` `可简写` * **`field（字段）`** `(Array)` `[]` * **`value（值）`** `(Array)` `[]` * **`condition（条件）`** `(Array)` `[]` * **`order（排序）`** `(Array)` `[]` * **`desc（降序）`** `(Array)` `[]` * **`limit（限制）`** `(Array)` `[]` * **`index（索引）`** `(Array)` `[]` * **`row_count（行数统计）`** `(Bool)` `false` * **`db_name（数据库）`** `(String)` `''` * **`unlock（解锁）`** `(Bool)` `false` * **`debug（调试）`** `(Bool)` `false` ## 返回 `(NULL|Int)` 类型。返回 `NULL` 或受到影响的行数。 # update() ## 说明 **Db :: update ( <kbd>传参数组</kbd> )** 更新符合条件的记录。此方法 `支持` 中文参数名。此方法 `支持` 参数简写。 ## 参数以下参数详见本模块 `公共参数` 部分的说明： * **`table（表）`** `(Array)` `<必须>` `可简写` * **`field（字段）`** `(Array)` `[]` * **`value（值）`** `(Array)` `[]` * **`condition（条件）`** `(Array)` `[]` * **`order（排序）`** `(Array)` `[]` * **`desc（降序）`** `(Array)` `[]` * **`limit（限制）`** `(Array)` `[]` * **`index（索引）`** `(Array)` `[]` * **`data（数据）`** `(Array)` `[]` * **`row_count（行数统计）`** `(Bool)` `false` * **`db_name（数据库）`** `(String)` `''` * **`unlock（解锁）`** `(Bool)` `false` * **`debug（调试）`** `(Bool)` `false` ## 返回 `(NULL|Int)` 类型。返回 `NULL` 或受到影响的行数。 # raw() ## 说明 **Db :: raw ( <kbd>传参数组</kbd> )** 执行自定义的SQL语句。此方法 `支持` 中文参数名。此方法 `支持` 参数简写。 ## 参数 * **`fetch_result（取回结果）`** `(Bool)` `false`：用以指定是否取回结果集。当值为 `false` 时，将返回 `NULL` ；当值为 `true` 时，将以 `PDO::FETCH_ASSOC` 方式取回数据集，返回一个数组。 * **`sql（sql）`** `(String)` `<必须>` `可简写`：附加在 `WHERE子句` 后的自定义SQL语句。如需进行参数绑定，请在字段名前加上 `:` 字符。 * **`bind（绑定）`** `(Array)` `[]`：用于指定在自定义的SQL语句中进行PDO参数绑定。本参数中 `键` 为字段名（字段名无需 `:` 前缀）， `值` 为字段名所对应的值。 >w 从安全的角度，强烈建议通过 `参数绑定` 避免注入风险。以下参数详见本模块 `公共参数` 部分的说明： * **`db_name（数据库）`** `(String)` `''` ## 返回 `(NULL | Array)` 类型。 `NULL` 或不含任何元素的空数组。 # acid() ## 说明 **Db :: acid ( <kbd>传参数组</kbd> )** 进行事务操作。此方法 `支持` 中文参数名。此方法 `支持` 参数简写。 ## 参数 * **`option（操作）`** `(String)` `<必须>` `可简写`：用以指定执行的事务操作类型。当值为 `start` 时代表开始事务；值为 `commit` 时代表提交事务；值为 `cancel` 时代表回滚事务。以下参数详见本模块 `公共参数` 部分的说明： * **`db_name（数据库）`** `(String)` `<必须>` `可简写` >d 如果在开始事务时指定了本参数，那么直到提交/回滚事务操作结束前，都必须在每一个数据库操作中指定相同的本参数，否则将会中断事务。 ## 返回 `(Bool)` 类型。返回的值为 `true` 时代表操作成功，值为 `false` 时代表操作失败。