Db - 84PHP开源框架

>i 本文档的最新修订日期是： > **2023-01-10** # Db ## 模块简述本模块底层通过 `PDO` 驱动，进行 `CURD` （增删改查）以及执行自定义SQL语句的操作。 ## 依赖本模块依赖于基础模块 `Log` 。 ## 模块配置配置文件位于 `/config/core/Db.php` 。 * **`log`** `(Bool)` `FALSE` ：用以指定是否将最终执行的SQL语句以 `debug` 级别提交到日志缓存中。 `TRUE` 代表提交到日志、`FALSE` 代表不提交到日志，默认不提交到日志。日志缓存是否会被写入日志文件，取决于 `Log` 模块的相关配置。 * **`dbInfo`** `(Array)` `（省略）` ：此配置项为一个二维数组（Array），用以指定数据库信息。在第一维数组中， `键` 为配置组名称， `值` 为一个数组，且该数组（即第二维数组）只能有以下六个元素： 1. 键为 `type` ，值为数据库驱动类型。取值范围可查阅 [PDO驱动列表](https://www.php.net/manual/zh/pdo.drivers.php) 以及 [获取可用的PDO驱动](https://www.php.net/manual/zh/pdo.getavailabledrivers.php) ； 2. 键为 `address` ，值为数据库地址。如果非远程数据库，请使用默认值 `localhost` ； 3. 键为 `username` ，值为数据库用户名； 4. 键为 `password` ，值为数据库密码； 5. 键为 `dbname` ，值为数据库名称； 6. 键为 `port` ，值为数据库端口号。 * **`default`** `(String)` `'default'`：用以指定默认链接的数据库的名称。值必须为配置项 `dbInfo` 中第一维数组中任意一个元素的键名。 ## 公共参数 ### 数据库的指定 * **`db_name（数据库）`** `(String)` `默认值见方法参数`：用以指定所操作的数据库的名称。本参数的值必须为配置项 `dbInfo` 中第一维数组中任意一个元素的键名。除 `choose` 方法外，指定本参数不会影响后续操作所使用的数据库，即如果后续操作未指定本参数，则仍然使用默认的数据库。 ### 表的指定 * **`table（表）`** `(String | Array)` `<必须>`：用以指定所操作的数据表表名。当本参数为 `String` 类型时，表示仅操作一个表。当本参数为 `Array` 类型时，数组键无需定义，每一个元素的值代表一个需要操作的表。 ### WHERE子句 * **`field（字段）`** `(Array)` `NULL`：用以指定查询条件中的字段。数组键无需定义，每一个元素的值代表一个限制条件，且元素与参数 `value` 以及参数 `condition` （如果传入）中的元素保持相互对应。 >w 如需进行多表操作，可以将传入的字段名设置为 `<表名>.<字段名>` ，例如 `student.id` 代表的就是 `student` 表的 `id` 字段。 * **`value（值）`** `(Array)` `NULL`：用以指定查询条件中字段对应的值。数组键无需定义，每一个元素的值代表一个字段，且元素与参数 `field` 以及参数 `condition`（如果传入）中的元素保持相互对应。 * **`condition（条件）`** `(String | Array)` `'='`：用以确定参数 `field` 和参数 `value` 之间的比较符以及与下一个条件之间的并列关系，以及指定各个条件之间的优先级关系。当本参数为 `String` 类型时，表示仅限定一个查询条件。当本参数为 `Array` 类型时，数组键 `无需定义` ，值为 `比较符[,并列关系]` 的字符串，其中比较符为字段与条件值之间的比较符（ `=` ，`<>` ，`>` ，`>=` ，`<=` ，`<>` ，`LIKE` ，`NOT LIKE` ），并列关系为与下一个限制条件之间的并列关系（ `and` 或 `or` ，未被定义时默认值为 `and` ），并且每一个元素与参数 `field` 和参数 `value` 中的元素保持相互对应。 >w 如需进行多表操作，可以将传入的字段名设置为 `<表名>.<字段名>` ，例如 `student.id` 代表的就是 `student` 表的 `id` 字段。此外，还可以在多个限定条件中，确定条件（或条件组合）之间的优先级。即在最终的SQL语句中，框架会根据传入的优先级参数的值，使用括号“()”对查询条件进行优先级的指定，例如 ```sql ... where `id` = '1' and ( `level` = 'a' or `class` > '3' ) ... ``` 的查询语句。如需使用此特性，则参数 `condition` 必须为数组，且数组的每一个元素的值将由 `String` 类型改变为 `Array` 类型，且包含两个元素，且数组的键无需定义：第一个元素的值为 `比较符[,并列关系]` 的字符串，该字符串的定义方式不再赘述。第二个元素的值为 `前置括号[,后置括号]` 的字符串。其中前置括号为添加在该条件前的左括号，可以为0个或多个 `(` ；后置括号为添加在该条件后、下一个并列关系符前的右括号，可以为0个或多个 `)` 。当仅需要添加右括号时，字符串应当定义为 `,后置括号` ，即起始字符为一个英文逗号。若要实现上面的SQL语句，那么应该按下面的方式定义这三个参数： ```php $Field=array('id', 'level', 'class'); $Value=array('1', 'a', '3'); $Condition=array( '=,and', array( '=,or', '(' ), array( '>', ',)' ) ); ``` ### ORDER BY子句 * **`order（顺序）`** `(String | Array)` `默认值见方法参数`：用以指定对结果排序时所依据的字段。当本参数为 `String` 类型时，表示仅限定一个排序字段。当本参数为 `Array` 类型时，数组键无需定义，每一个元素的值代表一个排序所依据的字段，且元素与参数 `desc` （如果传入）中的元素保持相互对应。 >w 如需进行多表操作，可以将传入的字段名设置为 `<表名>.<字段名>` ，例如 `student.id` 代表的就是 `student` 表的 `id` 字段。 * **`desc（降序）`** `(Bool | Array)` `FALSE`：用以指定是否使用倒序的排序方式。当本参数为 `Bool` 类型时，则指定所有字段的排序方式，`TRUE` 代表倒序、`FALSE` 代表正序，默认倒序。当本参数为 `Array` 类型时，数组键无需定义，每一个元素的值为一个字段排序所依据的方式，且元素与参数 `order` 中的元素保持相互对应。例如，将结果按照字段 `id` 正序排序，并且按照 `money` 倒序排序： ```php $Order=array('id','money'); $Desc=array(FALSE,TRUE); ``` >w 如需进行多表操作，可以将传入的字段名设置为 `<表名>.<字段名>` ，例如 `student.id` 代表的就是 `student` 表的 `id` 字段。 ### 更多子句 * **`limit（限制）`** `(Array)` `NULL`：用以从 `位置偏移量` 为起始行取得 `指定行数` 的记录。数组的键无需定义，当数组仅存在一个元素时，此元素定义 `行数` ，此时位置偏移量 `默认为0` ；当数组存在两个元素时，第一个元素定义 `位置偏移量` ，第二个元素定义 `行数` 。例如，从结果中的第3行开始取15行： ```php $Limit=array(2,15); //偏移量从0开始计算。 ``` >w 如果希望 `行数` 为查询结果的最大数量，请将值设置为 `-1` 。 * **`index（索引）`** `(Int)` `NULL`：用以指定执行操作时使用的索引。 * **`group_by（分组）`** `(String | Array)` `NULL`：用以指定对结果分组时所依据的字段。当本参数为 `String` 类型时，表示仅指定一个分组依据的字段。当本参数为 `Array` 类型时，数组键无需定义，每一个元素的值代表一个排序所依据的字段。 >w 如需进行多表操作，可以将传入的字段名设置为 `<表名>.<字段名>` ，例如 `student.id` 代表的就是 `student` 表的 `id` 字段。 * **`field_limit（字段限制）`** `(String | Array)` `*`：用以指定取回结果的字段范围。当本参数为 `String` 类型时，表示仅指定一个取回的字段。当本参数为 `Array` 类型时，数组键无需定义，每一个元素的值代表一个需要取回的字段。 `*` 代表取回所有字段。 >w 如需进行多表操作，可以将传入的字段名设置为 `<表名>.<字段名>` ，例如 `student.id` 代表的就是 `student` 表的 `id` 字段。 * **`data（数据）`** `(Array)` `默认值见方法参数`：用以指定需要插入或更新的数据。本参数中 `键` 为字段名， `值` 为字段名所对应的值。 >w 如需进行多表操作，可以将传入的字段名设置为 `<表名>.<字段名>` ，例如 `student.id` 代表的就是 `student` 表的 `id` 字段。 ### 自定义SQL语句 * **`sql（sql）`** `(String)` `NULL`：附加在 `WHERE子句` 后的自定义SQL语句。如需进行参数绑定，请在字段名前加上 `:` 字符。 * **`bind（绑定）`** `(Array)` `[]`：用于指定在自定义的SQL语句中进行PDO参数绑定。本参数中 `键` 为字段名（字段名无需 `:` 前缀）， `值` 为字段名所对应的值。 >w 从安全的角度，强烈建议通过 `参数绑定` 避免注入风险。 ### 其它参数 * **`row_count（行数统计）`** `(Bool)` `FALSE`：是否统计数据库中受到操作执行影响的行数。当值为 `TRUE` 时统计，值为 `FALSE` 时不统计。 ## :: choose()方法 ### 语法 **Db :: choose ( <kbd>传参数组</kbd> )** ### 说明在预配置的多个数据库中选择一个数据库。此方法 `支持` 中文参数名。此方法会替代配置文件中 `default` 配置项的值，从而影响后续操作在未指定数据库情况下，所使用的默认数据库。 ### 参数 * **`db_name（数据库）`** `(String)` `<必须>`：详见本模块 `公共参数` 部分的说明。 ### 返回无。 ## :: select()方法 ### 语法 **Db :: select ( <kbd>传参数组</kbd> )** ### 说明查询单条数据表记录。本方法相比于 `SelectMore` 方法，更适合于例如查询用户信息这样单一的数据，性能更优异。此方法 `支持` 中文参数名。 ### 参数 * **`table（表）`** `(String | Array)` `<必须>`：详见本模块 `公共参数` 部分的说明。 * **`field（字段）`** `(String | Array)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`value（值）`** `(String | Array)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`condition（条件）`** `(String | Array)` `'='`：详见本模块 `公共参数` 部分的说明。 * **`order（顺序）`** `(String | Array)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`desc（降序）`** `(Bool | Array)` `FALSE`：详见本模块 `公共参数` 部分的说明。 * **`index（索引）`** `(Int)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`field_limit（字段限制）`** `(String | Array)` `*`：详见本模块 `公共参数` 部分的说明。 * **`sql（sql）`** `(String)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`bind（绑定）`** `(Array)` `[]`：详见本模块 `公共参数` 部分的说明。 * **`db_name（数据库）`** `(String)` `''`：详见本模块 `公共参数` 部分的说明。 ### 返回 `(Array)` 类型。查询到记录时，返回值为一个数组，记录的每一个字段为一个 `键` ，每一个记录值为一个数组的 `值` ，且数组中键值的对应关系与记录中字段和记录值的对应关系相同。当查询到的记录为空时，返回值为一个 `空数组` 。 ## :: selectMore()方法 ### 语法 **Db :: selectMore ( <kbd>传参数组</kbd> )** ### 说明查询多条数据表记录。此方法 `支持` 中文参数名。 ### 参数 * **`table（表）`** `(String | Array)` `<必须>`：详见本模块 `公共参数` 部分的说明。 * **`field（字段）`** `(String | Array)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`value（值）`** `(String | Array)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`condition（条件）`** `(String | Array)` `'='`：详见本模块 `公共参数` 部分的说明。 * **`order（顺序）`** `(String | Array)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`desc（降序）`** `(Bool | Array)` `FALSE`：详见本模块 `公共参数` 部分的说明。 * **`limit（限制）`** `(Array)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`index（索引）`** `(Int)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`field_limit（字段限制）`** `(String | Array)` `*`：详见本模块 `公共参数` 部分的说明。 * **`group_by（分组）`** `(String | Array)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`sql（sql）`** `(String)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`bind（绑定）`** `(Array)` `[]`：详见本模块 `公共参数` 部分的说明。 * **`db_name（数据库）`** `(String)` `''`：详见本模块 `公共参数` 部分的说明。 ### 返回 `(Array)` 类型。查询到记录时，返回值为 `二维数组` ，在第一维的数组中，键为从 `0` 开始的自增键，值为一行记录的集合的一维数组；在第二维数组中， `键` 为字段名， `值` 为该条记录中字段所对应的记录值。当查询到的记录为空时，返回值为一个 `空数组` 。 ## :: total()方法 ### 语法 **Db :: total ( <kbd>传参数组</kbd> )** ### 说明统计符合条件的记录数量。此方法 `支持` 中文参数名。 ### 参数 * **`table（表）`** `(Int)` `<必须>`：详见本模块 `公共参数` 部分的说明。 * **`field（字段）`** `(String | Array)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`value（值）`** `(String | Array)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`condition（条件）`** `(String | Array)` `'='`：详见本模块 `公共参数` 部分的说明。 * **`order（顺序）`** `(String | Array)` `'Total'`：详见本模块 `公共参数` 部分的说明。 * **`desc（降序）`** `(Bool | Array)` `FALSE`：详见本模块 `公共参数` 部分的说明。 * **`limit（限制）`** `(Array)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`index（索引）`** `(Int)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`group_by（分组）`** `(String | Array)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`sql（sql）`** `(String)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`bind（绑定）`** `(Array)` `[]`：详见本模块 `公共参数` 部分的说明。 * **`db_name（数据库）`** `(String)` `''`：详见本模块 `公共参数` 部分的说明。 ### 返回 `(Array)` 类型。当未指定 `group_by` 参数时，将直接返回符合条件的记录总数；否则将返回依据 `group_by` 参数分组而形成的结果集。 ## :: sum()方法 ### 语法 **Db :: sum ( <kbd>传参数组</kbd> )** ### 说明对符合条件的指定列的记录值进行累加，并将结果放在一行中。此方法 `支持` 中文参数名。 ### 参数 * **`table（表）`** `(String | Array)` `<必须>`：详见本模块 `公共参数` 部分的说明。 * **`field（字段）`** `(String | Array)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`value（值）`** `(String | Array)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`condition（条件）`** `(String | Array)` `'='`：详见本模块 `公共参数` 部分的说明。 * **`order（顺序）`** `(String | Array)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`desc（降序）`** `(Bool | Array)` `FALSE`：详见本模块 `公共参数` 部分的说明。 * **`limit（限制）`** `(Array)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`index（索引）`** `(Int)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`sum（合计）`** `(Array)` `<必须>`：用以指定对结果分组时所依据的字段。每一个元素的键代表一个需要累加的字段，值代表该字段在结果中的字段别名。 >w 如需进行多表操作，可以将传入的字段名设置为 `<表名>.<字段名>` ，例如 `student.id` 代表的就是 `student` 表的 `id` 字段。 * **`sql（sql）`** `(String)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`bind（绑定）`** `(Array)` `[]`：详见本模块 `公共参数` 部分的说明。 * **`db_name（数据库）`** `(String)` `''`：详见本模块 `公共参数` 部分的说明。 ### 返回 `(Array)` 类型。将返回结果集。 ## :: insert()方法 ### 语法 **Db :: insert ( <kbd>传参数组</kbd> )** ### 说明插入数据，并返回新记录的主键。此方法 `支持` 中文参数名。 ### 参数 * **`table（表）`** `(String | Array)` `<必须>`：详见本模块 `公共参数` 部分的说明。 * **`data（数据）`** `(Array)` `<必须>`：详见本模块 `公共参数` 部分的说明。 * **`sql（sql）`** `(String)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`bind（绑定）`** `(Array)` `[]`：详见本模块 `公共参数` 部分的说明。 * **`db_name（数据库）`** `(String)` `''`：详见本模块 `公共参数` 部分的说明。 ### 返回 `(Int)` 类型。值为插入成功后该行记录的主键。 ## :: delete()方法 ### 语法 **Db :: delete ( <kbd>传参数组</kbd> )** ### 说明删除符合条件的记录。此方法 `支持` 中文参数名。 ### 参数 * **`table（表）`** `(String | Array)` `<必须>`：详见本模块 `公共参数` 部分的说明。 * **`field（字段）`** `(String | Array)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`value（值）`** `(String | Array)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`condition（条件）`** `(String | Array)` `'='`：详见本模块 `公共参数` 部分的说明。 * **`order（顺序）`** `(String | Array)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`desc（降序）`** `(Bool | Array)` `FALSE`：详见本模块 `公共参数` 部分的说明。 * **`limit（限制）`** `(Array)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`index（索引）`** `(Int)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`row_count（行数统计）`** `(Bool)` `FALSE`：详见本模块 `公共参数` 部分的说明。 * **`sql（sql）`** `(String)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`bind（绑定）`** `(Array)` `[]`：详见本模块 `公共参数` 部分的说明。 * **`db_name（数据库）`** `(String)` `''`：详见本模块 `公共参数` 部分的说明。 ### 返回 `(NULL|Int)` 类型。返回 `NULL` 或受到影响的行数。 ## :: update()方法 ### 语法 **Db :: update ( <kbd>传参数组</kbd> )** ### 说明更新符合条件的记录。此方法 `支持` 中文参数名。 ### 参数 * **`table（表）`** `(String | Array)` `<必须>`：详见本模块 `公共参数` 部分的说明。 * **`field（字段）`** `(String | Array)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`value（值）`** `(String | Array)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`condition（条件）`** `(String | Array)` `'='`：详见本模块 `公共参数` 部分的说明。 * **`order（顺序）`** `(String | Array)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`desc（降序）`** `(Bool | Array)` `FALSE`：详见本模块 `公共参数` 部分的说明。 * **`limit（限制）`** `(Array)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`index（索引）`** `(Int)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`data（数据）`** `(Array)` `默认值见方法参数`：详见本模块 `公共参数` 部分的说明。 * **`auto_operate（自动操作）`** `(String | Array)` `NULL`：用以指定自动更新的方式。例如 `+1` 则会使指定的字段值自动+1，详见数据库对应的官方手册。键无需定义，值为表达式，并且每一个元素与参数 `data` 中的元素保持 `相互对应` 。 * **`row_count（行数统计）`** `(Bool)` `FALSE`：详见本模块 `公共参数` 部分的说明。 * **`sql（sql）`** `(String)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`bind（绑定）`** `(Array)` `[]`：详见本模块 `公共参数` 部分的说明。 * **`db_name（数据库）`** `(String)` `''`：详见本模块 `公共参数` 部分的说明。 ### 返回 `(NULL|Int)` 类型。返回 `NULL` 或受到影响的行数。 ## :: other()方法 ### 语法 **Db :: other ( <kbd>传参数组</kbd> )** ### 说明执行自定义的SQL语句。此方法 `支持` 中文参数名。 ### 参数 * **`sql（sql）`** `(String)` `NULL`：详见本模块 `公共参数` 部分的说明。 * **`fetch_result（取回结果）`** `(Bool)` `FALSE`：用以指定是否取回结果集。当值为 `FALSE` 时，将返回 `NULL` ；当值为 `TRUE` 时，将以 `PDO::FETCH_ASSOC` 方式取回数据集，返回一个数组。 * **`bind（绑定）`** `(Array)` `[]`：详见本模块 `公共参数` 部分的说明。 * **`db_name（数据库）`** `(String)` `''`：详见本模块 `公共参数` 部分的说明。 ### 返回 `(NULL | Array)` 类型。 `NULL` 或不含任何元素的空数组。 ## :: acid()方法 ### 语法 **Db :: acid ( <kbd>传参数组</kbd> )** ### 说明进行事务操作。此方法 `支持` 中文参数名。 ### 参数 * **`option（操作）`** `(String)` `<必须>`：用以指定执行的事务操作类型。当值为 `begin` 时代表开始事务；值为 `commit` 时代表提交事务；值为 `cancel` 时代表回滚事务。 ### 返回 `(Bool)` 类型。返回的值为 `TRUE` 时代表操作成功，值为 `FALSE` 时代表操作失败。