README

EasyDb 是一个简单的 myslqi 扩展包装器。

这个库为你提供了什么？

使用不同类型的数据占位符安全地传递数据到查询中。
只需一个方法即可选择单个单元格或所有行。
通过传递列-值数组来插入和更新行。
仅用一个方法使用事务。
执行多个查询来加载你的 SQL 备份。
在不写大量代码的情况下执行多个插入和 insert... on duplicate update 查询。

安装

使用 composer 安装库。

composer require silverslice/easydb

连接到数据库

use Silverslice\EasyDb\Database;

// connect options
$options = [
    'host'     => 'localhost',
    'username' => 'root',
    'password' => '',
    'dbname'   => 'testdb',
    'charset'  => 'utf8'
];

// mysql options (not required)
$mysqlOptions = [MYSQLI_INIT_COMMAND => 'SET AUTOCOMMIT = 0'];

$db = new Database($options, $mysqlOptions);

数据占位符

EasyDb 使用数据占位符在查询中放置数据。

占位符类型

? - 智能型

在大多数情况下，您可以使用此占位符。它会自动检测您的值并正确格式化。

整数值将被原样插入。
NULL 值将被插入为 NULL 关键字。
数据库表达式将被原样插入。
在其他情况下，值将作为字符串插入。

?i - 整数

值将被 cast 到 int 类型，使用 intval 函数。

?s - 字符串

值将被 mysqli 内部转义函数转义，并用单引号括起来。

?f - 浮点数

值将被 cast 到 float 类型，使用 floatval 函数。

?a - 数组

此占位符期望数组，正确转义和引号其值，并用逗号分隔。它适用于如 SELECT * FROM table WHERE id IN (1, 2, 3) 的查询。

$db->getAll('SELECT * FROM table WHERE id IN (?a)', [1, 2, 3]);

// generated sql: SELECT * FROM table WHERE id IN (1, 2, 3)

?u - 集合

此占位符期望列-值数组并生成 SET 子句的代码。

$db->query('UPDATE products SET ?u', ['key' => 'foo', 'value' => 1]);

// generated sql: UPDATE products SET `key` = 'foo', `value` = 1

?e - 转义

值将被 mysqli 内部转义函数转义。

?p - 部分

值将被原样插入。使用此占位符插入已准备好的 SQL 查询部分。

动态构建查询

如果您的查询依赖于某些条件，您可以使用 prepare 方法将所有占位符替换为传递的参数。此字符串可以安全地插入查询中。

$pricePart = '';
if ($price) {
    $pricePart = $db->prepare(' AND price < ?', $price);
}

$db->getAll('SELECT * FROM products WHERE category_id = ? ?p', $categoryId, $pricePart);

异常

EasyDb 将所有数据库错误转换为 \Silverslice\EasyDb\Exception。使用 getQuery 方法获取导致错误的查询。

示例

try {
    $this->db->query("SELECTT 1");
} catch (Exception $e) {
    // get error code
    $code = $e->getCode();

    // get query with error
    $query = $e->getQuery();

    // get error message: code, error and query
    $message = $e->getMessage();
}

选择行

getOne

执行查询并从第一条结果行的第一个单元格中获取数据

参数

string $query - SQL 查询
mixed $param1 - 第一个占位符的参数
mixed $param2 - 第二个占位符的参数
...

getOne($query, $param1, $param2...)

string|null

getAssoc

执行查询并将第一条结果行作为关联数组获取

getAssoc($query, $param1, $param2...)

array|null

getAll

执行查询并将所有结果行作为关联数组获取

getAll($query, $param1, $param2...)

array

getColumn

执行查询并将结果集中的单个列作为枚举数组获取

getColumn($query, $param1, $param2...)

array

getPairs

执行查询并将结果集中的键值对获取

getPairs($query, $param1, $param2...)

array

getAllKeyed

执行查询并将结果集中的键值对获取

getAllKeyed($query, $param1, $param2...)

array|bool

修改行

insert

将行插入到表中

insert($table, $params, $ignore = false)

参数

string $table - 表名
array $params - 列-值对
bool $ignore - 使用或不使用 IGNORE 关键字

mixed - 插入的行 ID 或如果没有自增字段则为 true

update

更新表行

update($table, $params, $where = array())

参数

string $table - 表名
array $params - 列-值对
array $where - UPDATE WHERE 子句。多个条件将使用 AND 关键字连接

int - 受影响的行数

insertUpdate

使用 INSERT... ON DUPLICATE KEY UPDATE 子句插入或更新表行

insertUpdate($table, $insert, $update = array())

参数

string $table - 表名
array $insert - 要插入的列值对
array $update - 如果键已在表中存在，则更新的列值对

int - 受影响的行数：如果行被插入，则为 1；如果行被更新，则为 2

multiInsert

向表中插入多行

multiInsert($table, $fields, $data, $ignore = false)

参数

string $table - 表名
array $fields - 字段名
array $data - 要插入的数据的二维数组
bool $ignore - 使用或不使用 IGNORE 关键字

int - 受影响的行数

delete

删除表行

delete($table, $where = array())

参数

string $table - 表名
array $where - UPDATE WHERE 子句。多个条件将使用 AND 关键字连接

int - 受影响的行数

使用事务

beginTransaction

开始一个事务

beginTransaction()

commit

提交当前事务

commit()

rollback

回滚当前事务

rollback()

transaction

在事务中运行代码

transaction($process)

参数

callable $process - 处理回调

bool - 如果事务成功提交，则为 true，否则为 false

抛出异常

\Silverslice\EasyDb\Exception

示例

$this->db->transaction(function () {
    $this->db->query("INSERT INTO test (id, code, price) VALUES (3003, '1', 1)");
    $this->db->query("INSERT INTO test (id, code, price) VALUES (3004, '1', 1)");
});

高级

表达式

在 SQL 查询中，列有时是表达式，而不是简单的表列名。您可以使用类型为 Expression 的对象将表达式插入到 SQL 中。

$this->db->insert('test', [
    'time' => new Expression('NOW()')
]);

// or use expression alias

$this->db->insert('test', [
    'time' => $this->db->expression('NOW()')
]);

多查询

使用 multiQuery 方法执行多个查询，这些查询由分号连接，例如从文件中加载 SQL 转储。

multiQuery

执行一个或多个由分号连接的查询

multiQuery($queries)

参数

string $queries

bool