README

喜欢使用纯SQL但不喜欢忍受PDO、mysqli等？试试这个。

$database = Connection::create('mysql:host=localhost;dbname=my_database', 'user', 'pass');
$items = $database->select('SELECT * FROM items WHERE category_id = ?', [3]);

主要功能

• 没有愚蠢的查询构建器，只有古老的SQL。
• 非常轻量，没有外部依赖。它只需要PDO扩展，该扩展在大多数服务器中默认可用。
• 数据库对象是明确提供的，而不是通过静态类。
• 错误时抛出异常。

您可以将其与第三方SQL查询构建器结合使用以在数据库中发挥作用。合适的查询构建器示例：Query Scribe、Nilportugues SQL Query Builder、Aura.SqlQuery、Latitude、Koine Query Builder、Phossa2 Query、Hydrahon。

安装

使用 Composer

在控制台中运行

composer require finesse/micro-db

参考

创建一个 Connection 实例

要创建一个新的 Connection 实例，请调用 create 方法，传递 PDO 构造函数参数。

use Finesse\MicroDB\Connection;

$database = Connection::create('dsn:string', 'username', 'password, ['options']);

或将 PDO 实例传递给构造函数。但请注意：Connection 会更改给定的 PDO 对象，并且您 必须不 改变给定的对象，否则可能会发生意外。

use Finesse\MicroDB\Connection;

$pdo = new PDO(/* ... */);
$database = new Connection($pdo);

选择

选择多行

$rows = $database->select('SELECT * FROM table'); // [['id' => 1, 'name' => 'Bill'], ['id' => 2, 'name' => 'John']]

选择一行

$row = $database->selectFirst('SELECT * FROM table'); // ['id' => 1, 'name' => 'Bill']

单元格值以与PDO返回的方式返回。它们不会自动转换，因为转换可能会造成数据丢失。

插入

插入并获取插入行的数量

$insertedCount = $database->insert('INSERT INTO table (id, price) VALUES (1, 45), (2, 98)'); // 2

插入并获取最后插入行的标识符

$id = $database->insertGetId('INSERT INTO table (weight, price) VALUES (12.3, 45)'); // 3

更新

更新行并获取更新的行数

$updatedCount = $database->update('UPDATE table SET status = 1 WHERE price < 1000');

删除

删除行并获取删除的行数

$deletedCount = $database->delete('DELETE FROM table WHERE price > 1000');

其他查询

执行任何其他语句

$database->statement('CREATE TABLE table(id INTEGER PRIMARY KEY ASC, name TEXT, price NUMERIC)');

如果查询包含多个由分号分隔的语句，则只会执行第一个语句。您可以使用其他方法执行多个语句。

$database->statements("
    CREATE TABLE table(id INTEGER PRIMARY KEY ASC, name TEXT, price NUMERIC);
    INSERT INTO table (name, price) VALUES ('Donald', 1000000);
");

此方法的缺点是它不绑定值。

执行文件

从SQL文件中执行查询

$database->import('path/to/file.sql');

或从资源中执行

$stream = fopen('path/to/file.sql', 'r');
$database->import($stream);

绑定值

您不应直接将值插入SQL查询中，因为这可能导致 SQL注入。相反，请使用绑定。

// WRONG! Don't do it or you will be fired
$rows = $database->select("SELECT * FROM table WHERE name = '$name' LIMIT $limit");

// Good
$rows = $database->select('SELECT * FROM table WHERE name = ? LIMIT ?', [$name, $limit]);

数据库服务器会将占位符（?）安全地替换为给定的值。几乎所有上述方法都接受绑定的值列表作为第二个参数。

您还可以使用命名参数

$rows = $database->select('SELECT * FROM table WHERE name = :name LIMIT :limit', [':name' => $name, ':limit' => $limit]);

您甚至可以在同一个数组中传递命名和匿名参数，但这只在没有值数组与查询文本中占位符顺序相同的情况下才有效。

所有值的基本类型都受支持：字符串、整数、浮点数、布尔值和null。

错误处理

在每次数据库查询错误的情况下都会抛出Finesse\MicroDB\Exceptions\PDOException。如果错误是由SQL查询引起的，则异常消息中包含查询文本和绑定值。它们也可以通过以下方法获取：

$sql = $exception->getQuery();
$bindings = $exception->getValues();

当方法参数格式不正确时，会抛出Finesse\MicroDB\Exceptions\InvalidArgumentException。

在文件读取错误时，会抛出Finesse\MicroDB\Exceptions\FileException。

所有异常都实现了Finesse\MicroDB\IException。

检索底层的PDO对象

$pdo = $database->getPDO();

您必须不要更改检索到的对象，否则可能会发生意外情况。

已知问题

• insertGetId在SQL Server和PostgreSQL中不会返回插入行的标识符。
• statements和import在查询的第二个或后续语句有错误时不会抛出异常。这是PDO的一个bug。

如果您需要解决问题，请发起一个pull request或issue。

版本兼容性

项目遵循语义化版本控制。

许可

MIT。有关详细信息，请参阅LICENSE文件。