README

Pebble\Database 是一个用于简化与 SQL 数据库交互的工具集。

Pebble\Database\DriverInterface : 连接到数据库并执行查询。
Pebble\Database\StatementInterface : 表示预查询及其相关结果集。
Pebble\Database\Factory : 该类是一个简单的工厂，用于创建一个 PDO 对象。

错误

错误会触发 Pebble\Database\Exception 异常。

错误代码

CONNECT = 1 : 连接到数据库的错误。
PREPARE = 2 : 创建预查询时的错误。
BIND = 3 : 将值绑定到参数时的错误。
EXECUTE = 4 : 执行查询时的错误。
TRANSACTION = 5 : 事务错误。

快捷方式

Exception::connect(string $message)
Exception::prepare(string $message)
Exception::bind(string $message)
Exception::execute(string $message)
Exception::transaction(string $message)

查询

Pebble\Database\Query 类用于存储 SQL 查询及其数据。

该类实现了 Pebble\Database\QueryInterface 接口。

__construct(string $statement = '', array $data = []) : 构造函数
setStatement(string $statement = '') : Query : 修改 SQL 查询
setData(array $data = []) : Query : 修改查询数据。
getStatement() : string : 返回 SQL 查询
getData() : array 返回用于执行查询的数据数组。

StatementInterface

Pebble\Database\StatementInterface 接口用于描述对 SQL 查询结果的访问。

方法

bind(... $args) : StatementInterface : 将数据绑定到一个预查询。
execute(array $data = []) : StatementInterface : 执行一个预查询。
count() : 返回结果数量
next($object = true) : 返回下一个结果
all(bool|string $object = true) : 以数组形式返回查询的 0-n 个结果
one(bool|string $object = true) : 如果查询恰好有一个结果，则返回该结果。如果没有结果，则返回 null

某些查询可以返回混合结果

以关联数组形式（$object === false）。
以 \stdClass 对象形式（$object === true）。
或以自定义对象形式（$object === $classname）。

DriverInterface

Pebble\Database\DriverInterface 接口用于描述与数据库的交互，并准备查询。

use(string $database) : 更改当前数据库。
getId() : int : 返回最后插入的标识符（自增）。
escape(string $str) : string 转义一个值。
transaction() : DriverInterface : 开始一个事务。
commit() : DriverInterface : 确认一个事务。
rollback() : DriverInterface : 取消一个事务。
query(string $sql) : StatementInterface : 从字符串执行预查询。
prepare(string $statement) : StatementInterface : 从字符串准备一个预查询。
exec(QueryInterface $query) : StatementInterface : 从实现 QueryInterface 的对象执行查询。

查询构建器：QB

Le query builder Pebble\Database\QB 是一个可独立使用的类，允许构建 SQL 查询。

需要使用该构建器构建查询，进行个性化设置，然后渲染 Pebble\Database\Query 对象。

$qb = new QB('ma_table')
$qb->whereEq('id', 1);
$query = $qb->read();

构建

__construct(string $table = '')
static create(string $table = '') : QB

表名是可选的，因为某些查询可能根本不作用于表。

个性化

这些方法是可链式的。

选择

select(string ...$cols) : QB : 选择列。默认情况下，返回所有列。
distinct() : QB : 仅选择具有不同值的列。

表

from(string $table) : 赋值，修改表。
join(string $table, string $cond) : 内连接。
left(string $table, string $cond) : 左外连接。
right(string $table, string $cond) : 右外连接。

条件

操作符 AND

where(string $statement, ...$values) : QB : 向查询添加条件。
whereNull(string $field) : QB : 列的值必须为空。
whereNotNull(string $field) : QB : 列的值不能为空。
whereEq(string $field, $value) : 列的值必须等于所需值。
whereNot(string $field, $value) : 列的值必须不同于所需值。
whereSup(string $field, $value) : QB : 列的值必须大于所需值。
whereInf(string $field, $value) : QB : 列的值必须小于所需值。
whereSupEq(string $field, $value) : QB : 列的值必须大于或等于所需值。
whereInfEq(string $field, $value) : QB : 列的值必须小于或等于所需值。
whereIn(string $col, array $values) : QB : 列的值必须对应于所需值之一。
whereNotIn(string $col, array $values) : QB : 列的值不得对应于所需值之一。
like(string $field, $value) : QB : 列的值必须对应于所需模式。
notLike(string $field, $value) : QB : 列的值不得对应于所需模式。

操作符 OR

orWhere(string $statement, ...$values) : QB : 向查询添加条件。
orWhereNull(string $field) : QB : 列的值必须为空。
orWhereNotNull(string $field) : QB : 列的值不能为空。
orWhereEq(string $field, $value) : 列的值必须等于所需值。
orWhereNot(string $field, $value) : 列的值必须不同于所需值。
orWhereSup(string $field, $value) : QB : 列的值必须大于所需值。
orWhereInf(string $field, $value) : QB : 列的值必须小于所需值。
orWhereSupEq(string $field, $value) : QB : 列的值必须大于或等于所需值。
orWhereInfEq(string $field, $value) : QB : 列的值必须小于或等于所需值。
orWhereIn(string $col, array $values) : QB : 列的值必须对应于所需值之一。
orWhereNotIn(string $col, array $values) : QB : 列的值不得对应于所需值之一。
orLike(string $field, $value) : QB : 列值必须与指定模式匹配。
orNotLike(string $field, $value) : QB : 列值不能与指定模式匹配。

条件块

groupStart() : QB : 开始一个块（操作符 AND）
orGroupStart() : QB : 开始一个块（操作符 OR）
groupEnd() : QB : 结束一个块（操作符 AND/OR）

分组

groupBy(string ...$cols) : QB : 按列分组结果。
having(string $statement, ...$values) : QB : 为统计函数添加条件（操作符 AND）
orHaving(string $statement, ...$values) : QB : 为统计函数添加条件（操作符 OR）

排序

orderBy(string ...$statements) : QB : 排序（升序或降序）。
orderAsc(string ...$col) : QB : 升序排序。
orderDesc(string ...$col) : QB : 降序排序。

示例

$qb->orderBy('etat', 'dat_creatione_creation desc');
$qb->orderAsc('etat')->orderDesc('date_creation');

限制

limit(int $limit, int $offset = 0) : QB : 限制结果数量

添加数据

这些方法用于在数据库中插入、替换、修改数据。

add(string $col, $value) : QB : 添加数据。数据受保护。
addList(array $data) : QB : 添加数据列表。数据受保护。
addRaw(string $col, $value) : QB : 添加数据。数据不受保护/转义。
addListRaw(array $data) : QB : 添加数据列表。数据不受保护/转义。
increment(string $col, $val = 1) : QB : 增加列。
decrement(string $col, $val = 1) : QB : 减少列。

渲染

read() : Query : 创建选择数据查询。
count() : Query : 创建计数数据查询。
insert() : Query : 创建添加数据查询。
replace() : Query : 创建替换数据查询。
update() : Query : 创建修改数据查询。
delete() : Query : 创建删除数据查询。

多行插入/替换

insertAll(array $data) : Query
replaceAll(array $data) : Query

会话：SessionHandler

Pebble\Database\SessionHandler 类允许管理数据库会话。该类实现了 \SessionHandlerInterface，并可以使用原生函数 session_set_save_handler 使用其实例。

构造函数的第一个参数必须是一个实现 Pebble\Database\DriverInterface 的对象。
第二个参数是可选的，允许配置数据库的表名和字段名
- table : 表名（默认为 sessions）
- id : 标识符的名称（默认为 id）
- time : 存储过期时间的字段名（默认为 ts）
- data : 存储数据的字段名（默认为 data）

理想的 SQL 配置

CREATE TABLE `sessions` (
`id` char(40) NOT NULL,
`ts` int(10) NOT NULL DEFAULT 0,
`data` blob NOT NULL,
PRIMARY KEY (`id`),
KEY `session_ts_idx` (`ts`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8

操作表：DBForge

DBForge 类允许操作数据库或表的结构。该类生成查询（Query 对象），因此它不会自动执行查询。

创建 DBForge 对象

$forge = DBForge::create()

创建数据库

createSchema(string $name, string $charset = 'utf8mb4', string $collate = 'utf8mb4_general_ci'): string

name : 数据库名称。
charset : 使用的字符集。
collate : 数据库的校对。

示例

$db->query(
    DBForge::create()->createSchema('donnons')
);

删除数据库

dropSchema(string $name): string

name : 数据库名称。

创建表

createTable(string $name, string $comment = ""): string

列、键和索引必须预先声明。

name：表名。
comment：表描述。

删除表

dropTable(string $name): string

name：表名。

重命名表

renameTable(string $from, string $to): string

from：表名
to：新的表名

修改表

alterTable(string $name)

name：表名。

列、键和索引的操作必须预先声明。

SQL 提示：在一个查询中同时处理外键列和列通常会导致 SQL 错误。请考虑将查询分步骤进行。

添加列

addColumn(string $name, ?callable $callback = null) : DBForge

name：列名
callback：用于配置列属性的回调函数。

删除列

dropColumn(string $name) : DBForge

name：列名。

修改列

changeColumn(string $name, ?string $new_name = null, ?callable $callback = null) : DBForge

name：列名
new_name：如果提供，则为列的新名称
callback：用于配置列属性的回调函数。

配置列属性

属性配置在addColumn和changeColumn方法的回调函数中进行。

示例

function(Column $column) {
    $column->char(40);
}

`type(string $type, ...$constraints) : Column`

type：字段类型
constraints：约束

`bool(bool $default = false) : Column`

布尔类型：无符号的 tinyint(1) not null，带有默认值。

default：默认值：如果为真，则为 1，否则为 0

`int($prefix = '') : Column`

INT 类型

prefix：TINY, SMALL, MEDIUM, BIG.

`float() : Column`

FLOAT 类型

`decimal(int $len = 10, int $precision = 2) : Column`

DECIMAL 类型

precision：总的有效数字数
scale：数字的小数部分的有效数字数。

`char(int $len) : Column`

CHAR 类型

len：保留的字符数

`varchar(int $len = 255) : Column`

VARCHAR 类型

len：字符数

`text($prefix = '') : Column`

TEXT 类型

prefix：TINY, MEDIUM, LONG

`blob($prefix = '') : Column`

BLOB 类型

prefix：TINY, MEDIUM, LONG

`timestamp() : Column`

TIMESTAMP 类型

`datetime() : Column`

DATETIME 类型

`date() : Column`

DATE 类型

`time() : Column`

TIME 类型

`unsigned(bool $value = true) : Column`

对于数值字段，添加 UNSIGNED 选项。

`notNull() : Column`

字段不能为空。

`defaultValue($value, bool $quote = true) : Column`

默认值。激活 notNull()。

value：值
quote：转义或不转义值。

`defaultTimestamp($on_update = false) : Column`

默认值：CURRENT_TIMESTAMP

on_update：如果为真，则添加 ON UPDATE CURRENT_TIMESTAMP

`autoIncrement() : Column`

对于整数字段，添加自增。

`comment(string $value) : Column`

添加注释。

`first() : Column`

将字段置于第一位置（ALTER TABLE）

`after(string $name): Column`

将字段置于name字段之后（ALTER TABLE）

处理主键

addPrimary(... $names) : DBForge：将一个或多个列添加到主键中。
dropPrimary() : DBForge：删除主键。

处理索引

`addIndex(string $name, array $cols = []) : DBForge`

添加一个索引，格式为 {table}_{name}_idx ('name' ASC)。

自动添加表名和后缀。

要自定义列列表，需要传递一个关联数组：* 键：列名 * 值：如果为 true 则为 ASC，否则为 DESC

`addUnique(string $name, array $cols = []) : DBForge`

添加格式为 {table}_{name}_unq ('name' ASC) 的唯一索引。

自动添加表名和后缀。

要自定义列列表，需要传递一个关联数组：* 键：列名 * 值：如果为 true 则为 ASC，否则为 DESC

`dropIndex(string $name) : DBForge`

删除索引。将自动添加表名和后缀。

`dropUnique(string $name) : DBForge`

删除唯一索引。将自动添加表名和后缀。

外键键值操作

`addFk(string $field, string $target, $delete = 'CASCADE', $update = 'CASCADE') : DBForge`

添加外键。

field : 列名
target : 目标列，格式为 TABLE.COLUMN
delete : 删除选项
update : 更新选项

`addFkIndex(string $field)` : DBForge

为外键添加索引。

`dropFk(string $field) : DBForge`

删除外键。

`dropFkIndex(string $field) : DBForge`

删除外键索引。

示例

创建表

DBForge::create()
    ->addColumn('id', function(Column $col) {
        $col->type('int', 11)->unsigned()->autoIncrement();
    })
    ->addColumn('name', function(Column $col) {
        $col->type('varchar', 50)->notNull();
    })
    ->addColumn('captain', function(Column $col) {
        $col->->type('int', 11)->unsigned();
    })
    ->addColumn('assistant'function(Column $col) {
        $col->->type('int', 11)->unsigned();
    })
    ->addPrimary('id')
    ->addFk('captain', 'players.id')
    ->addFk('assistant', 'players.id')
    ->createTable('tests.teams')

修改表

DBForge::create()
    ->changeColumn('id', function(Column $col) {
    $col->type('int', 11)->unsigned()->autoIncrement();
    })
    ->addPrimary('id')
    ->alterTable('tests.teams')

sopheos / pebble_database

维护者

详细信息

README

错误

错误代码

快捷方式

查询

StatementInterface

DriverInterface

查询构建器：QB

构建

个性化

选择

表

条件

操作符 AND

操作符 OR

条件块

分组

排序

限制

添加数据

渲染

多行插入/替换

会话：SessionHandler

操作表：DBForge

创建 DBForge 对象

创建数据库

删除数据库

创建表

删除表

重命名表

修改表

添加列

删除列

修改列

配置列属性

type(string $type, ...$constraints) : Column

bool(bool $default = false) : Column

int($prefix = '') : Column

float() : Column

decimal(int $len = 10, int $precision = 2) : Column

char(int $len) : Column

varchar(int $len = 255) : Column

text($prefix = '') : Column

blob($prefix = '') : Column

timestamp() : Column

datetime() : Column

date() : Column

time() : Column

unsigned(bool $value = true) : Column

notNull() : Column

defaultValue($value, bool $quote = true) : Column

defaultTimestamp($on_update = false) : Column

autoIncrement() : Column

comment(string $value) : Column

first() : Column

after(string $name): Column