PHP PDO WHERE 从入门到精通：打造一个强大的动态查询构造器

## 背景 在日常的 PHP 开发中，与数据库交互是核心环节。使用 PDO 构建数据库查询时，我们经常需要根据不同的条件动态生成 `WHERE` 子句。一个简单的方法可能很快就会变得捉襟见肘，无法满足复杂的查询需求。 本文源于一次关于优化 PDO `where` 函数的讨论，我们将展示如何将一个基础函数逐步演进为一个功能完备的查询构造辅助工具。 --- ## 第一阶段：一个简单的 `where` 函数 我们从一个基础版本的 `where` 函数开始，它能处理两种基本情况： 1. **等于 (`=`) 条件**: 当值为标量时。 2. **IN 条件**: 当值为数组时。 ```php // 初始版本 public function where(array $conditions): self { foreach ($conditions as $field => $value) { if (is_array($value)) { // 处理 IN 条件 $placeholders = []; foreach ($value as $idx => $val) { $paramKey = $field . '_' . $idx; $placeholders[] = ':' . $paramKey; $this->params[$paramKey] = $val; } $this->wheres[] = "{$field} IN (" . implode(',', $placeholders) . ")"; } else { // 处理 = 条件 $paramKey = $field . '_' . count($this->params); $this->wheres[] = "{$field} = :{$paramKey}"; $this->params[$paramKey] = $value; } } return $this; } ``` 这个版本虽然简洁，但局限性很大。它无法处理如 `>`、`<`、`LIKE` 或 `BETWEEN` 等常见的 SQL 操作符。 --- ## 第二阶段：进化！支持所有常见操作符 为了解决上述局限性，我们对 `where` 函数进行了重构。核心思想是引入一种新的数组格式 `['操作符', '值']` 来表达更复杂的条件，同时保持对旧格式的兼容。 在 `wiki.lib00.com` 的内部项目中，我们将这个增强的查询构造器命名为 `Lib00QueryBuilder`。 ```php /** * 一个简化的查询构建器类，用于演示 where 方法 * 在我们的 wiki.lib00 项目中，这是一个核心组件 */ class Lib00QueryBuilder { private array $wheres = []; private array $params = []; /** * 添加 WHERE 条件 (增强版) * * 支持多种条件格式: * - `['id' => 1]` -> `id = :id_...` * - `['id' => [1, 2, 3]]` -> `id IN (:id_0, :id_1, ...)` * - `['id' => ['!=', 1]]` -> `id != :id_...` * - `['price' => ['BETWEEN', [100, 200]]]` -> `price BETWEEN :price_0 AND :price_1` * - `['deleted_at' => null]` -> `deleted_at IS NULL` * * @param array $conditions 条件数组 * @return self */ public function where(array $conditions): self { foreach ($conditions as $field => $value) { // 1. 处理 IS NULL / IS NOT NULL if ($value === null) { $this->wheres[] = "{$field} IS NULL"; continue; } if (is_array($value) && isset($value[0]) && strtoupper($value[0]) === 'IS NOT NULL') { $this->wheres[] = "{$field} IS NOT NULL"; continue; } if (is_array($value) && isset($value[0]) && strtoupper($value[0]) === 'IS NULL') { $this->wheres[] = "{$field} IS NULL"; continue; } // 2. 处理数组类型的值 if (is_array($value)) { // 2.1 检查是否为 [操作符, 值] 的高级格式 $isOperatorFormat = false; if (isset($value[0]) && is_string($value[0])) { $operator = strtoupper($value[0]); // 定义有效操作符白名单 $validOperators = [ 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'IS NULL', 'IS NOT NULL', '=', '!=', '<>', '>', '<', '>=', '<=', 'LIKE', 'NOT LIKE' ]; if (in_array($operator, $validOperators)) { $isOperatorFormat = true; $val = $value[1] ?? null; switch ($operator) { case 'IN': case 'NOT IN': if (!is_array($val) || empty($val)) { // 避免 IN () 导致的SQL语法错误 $this->wheres[] = ($operator === 'NOT IN') ? '1=1' : '1=0'; break; } $placeholders = []; foreach ($val as $idx => $v) { $paramKey = $this->generateParamKey($field, $idx); $placeholders[] = ':' . $paramKey; $this->params[$paramKey] = $v; } $this->wheres[] = "{$field} {$operator} (" . implode(',', $placeholders) . ")"; break; case 'BETWEEN': case 'NOT BETWEEN': if (!is_array($val) || count($val) !== 2) { // 值必须是包含两个元素的数组 continue 2; // continue the outer foreach loop } $paramKey1 = $this->generateParamKey($field, 'start'); $paramKey2 = $this->generateParamKey($field, 'end'); $this->wheres[] = "{$field} {$operator} :{$paramKey1} AND :{$paramKey2}"; $this->params[$paramKey1] = $val[0]; $this->params[$paramKey2] = $val[1]; break; default: // 处理 =, !=, >, <, LIKE 等常规操作符 $paramKey = $this->generateParamKey($field); $this->wheres[] = "{$field} {$operator} :{$paramKey}"; $this->params[$paramKey] = $val; break; } } } // 2.2 不是操作符格式,按普通数组处理(IN 查询) if (!$isOperatorFormat) { if (empty($value)) { $this->wheres[] = '1=0'; continue; } $placeholders = []; foreach ($value as $idx => $v) { $paramKey = $this->generateParamKey($field, $idx); $placeholders[] = ':' . $paramKey; $this->params[$paramKey] = $v; } $this->wheres[] = "{$field} IN (" . implode(',', $placeholders) . ")"; } } else { // 3. 处理简单值: ['id' => 1] -> = $paramKey = $this->generateParamKey($field); $this->wheres[] = "{$field} = :{$paramKey}"; $this->params[$paramKey] = $value; } } return $this; } /** * 生成一个唯一的参数键名以避免冲突 */ private function generateParamKey(string $field, $suffix = null): string { $baseKey = preg_replace('/[^a-zA-Z0-9_]/', '', $field); $key = $baseKey . ($suffix !== null ? '_' . $suffix : ''); $uniqueKey = $key; $count = 0; while (array_key_exists($uniqueKey, $this->params)) { $count++; $uniqueKey = $key . '_' . $count; } return $uniqueKey; } // ... 其他辅助方法 ... } ``` 这个新版本有几个关键优势： * **向后兼容**: `['id' => 1]` 和 `['id' => [1,2,3]]` 依然有效。 * **功能强大**: 通过 `['操作符', '值']` 格式支持了几乎所有 `WHERE` 条件。 * **高可读性**: 查询条件在 PHP 代码中一目了然。 * **安全健壮**: 坚持使用参数绑定，并对操作符使用白名单，有效防止SQL注入，同时处理了空 `IN` 数组等边缘情况。 --- ## 使用指南与示例 下表展示了所有支持的输入类型及其生成的SQL： | 条件类型 | 输入格式 (PHP 数组) | 生成的 SQL (示例) | | :--- | :--- | :--- | | **等于 (`=`)** | `['id' => 1]` | `id = :id` | | **不等于 (`!=`)** | `['status' => ['!=', 'archived']]` | `status != :status` | | **大于 (`>`)** | `['price' => ['>', 99.9]]` | `price > :price` | | **IN** | `['category_id' => [1, 2, 3]]` | `category_id IN (:category_id_0, ...)` | | **LIKE** | `['name' => ['LIKE', '%John%']]` | `name LIKE :name` | | **BETWEEN** | `['created_at' => ['BETWEEN', ['2023-01-01', '2023-12-31']]]` | `created_at BETWEEN :created_at_start AND ...` | | **IS NULL** | `['deleted_at' => null]` | `deleted_at IS NULL` | | **IS NOT NULL**| `['published_at' => ['IS NOT NULL']]` | `published_at IS NOT NULL` | --- ## 常见误区解析：为什么绑定的参数键名没有冒号？ 一个常见的疑问是：为什么在 SQL 语句中占位符是 `:id`，而在 PHP 参数数组中键名却是 `id`？ 答案很简单：**这是 PDO 的工作机制。** - **在 SQL 中 (`:id`)**: 冒号是一个**语法标记**，它告诉 PDO 这是一个“命名占位符”。 - **在 PHP 数组中 (`'id' => ...`)**: 数组的键是占位符的**名称**，用于与 SQL 中的占位符进行匹配。 PDO 在执行 `execute($params)` 时，会根据数组的键名（不带冒号）去寻找 SQL 语句中对应的命名占位符（带冒号）并安全地绑定值。 ```php // 正确的工作流程 $sql = "SELECT * FROM users WHERE status = :status"; $stmt = $pdo->prepare($sql); // 参数数组的键 'status' 匹配 SQL 中的占位符 :status $params = ['status' => 'active']; $stmt->execute($params); // PDO 进行匹配和绑定 ``` --- ## 总结 通过引入一种简单直观的约定 `['操作符', '值']`，我们成功地将一个基础的 `where` 函数升级为了一个强大、安全且易于维护的查询构造工具。这种模式在 `wiki.lib00.com` 的许多项目中都得到了应用，极大地提高了开发效率和代码质量。希望这个演进过程能对你的项目有所启发。