pixie 是一个轻量、无依赖的 php 查询构造器，支持 pdo 驱动、链式构建 sql、自动参数绑定防注入，需手动传入配置好的 pdo 实例，不自动读取环境配置，要求 php ≥ 7.4 且对应 pdo 扩展已启用。
Pixie 是一个轻量、无依赖的 PHP 查询构造器，适合不想引入完整 ORM（如 Eloquent 或 Cycle）但又需要安全、链式构建 SQL 的场景。它不绑定特定数据库驱动，靠适配器工作，但默认支持 PDO，且语法简洁，对新手友好。
安装 Pixie 时要注意 PHP 和 PDO 扩展兼容性
运行 composer require pixie/pixie 即可安装最新版（v3.x），但它要求：
- PHP ≥ 7.4（v3.0+ 不再支持 PHP 7.2/7.3）
-
PDO扩展已启用，且对应数据库驱动（如pdo_mysql或pdo_pgsql）必须加载 - 若用 SQLite，需确认
pdo_sqlite存在，否则Connection实例化会静默失败
常见错误是执行时报 Class 'PDO' not found 或 Driver not found——这不是 Pixie 的问题，而是环境缺失。可用 php -m | grep pdo 快速验证。
初始化 Connection 必须显式传入 PDO 实例
Pixie 不自动创建连接，也不读取 .env 或配置文件。你得自己准备 PDO 实例，并传给 QueryBuilder：
$pdo = new PDO('mysql:host=localhost;dbname=test', $user, $pass, [
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);
$builder = new \Pixie\QueryBuilder\QueryBuilderHandler('mysql', $pdo);
注意三点：
- 第一个参数是方言名（
mysql/pgsql/sqlite），不是 DSN；拼错会导致Unknown driver -
$pdo必须已设置PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION，否则查询失败不抛异常 - 别把
$pdo封装成单例后反复传给多个QueryBuilderHandler实例——Pixie内部不共享状态，但连接复用本身没问题
WHERE 条件嵌套 AND/OR 容易漏掉括号包裹
Pixie 支持闭包式嵌套，但语法和 Laravel Builder 不同：必须用 where + 闭包，且闭包内调用的是同一个 $query 实例：
$builder->table('users')
->where('status', '=', 1)
->where(function ($query) {
$query->where('age', '>=', 18)->orWhere('vip', '=', true);
})
->get();
这生成的 SQL 是：WHERE status = ? AND (age >= ? OR vip = ?)。容易踩的坑：
- 闭包参数名必须是
$query（或任意名，但内部要一致），不能写成$builder——它不是全局实例 - 如果漏掉闭包，直接写
->orWhere(...)，就会变成顶层 OR，破坏逻辑优先级 -
orWhere在闭包外使用时，会脱离前一个AND组，变成WHERE ... OR ...，不是你想的“括号内 OR”
执行查询前必须手动调用 get() / insert() 等终态方法
Pixie 是惰性构建，所有链式调用只是组装 SQL 片段，不发请求。常见误操作：
- 写了
$builder->table('x')->where(...)就以为执行了——其实什么都没发生 - 误用
toString()查看 SQL 时没绑定参数，输出带问号占位符，看不出真实值 - 想获取单行用
first()，但表为空时返回null，不是空数组；要用get()再取[0]需自行判空
安全做法是：查完立刻处理返回值，不要假设结构。例如：
$rows = $builder->table('posts')->where('published', 1)->get();
if (empty($rows)) {
// 无数据
}
Pixie 的链式设计干净，但它的“无魔法”也意味着少了一层保护——每个环节都得自己盯住。最常被忽略的是 PDO 连接配置和嵌套条件的作用域，这两处出错，调试时往往只看到空白结果或 SQL 语法错误，而不是清晰的提示。
