理解Doctrine与原生SQL函数的兼容性
在使用doctrine orm进行数据库操作时，开发者通常倾向于使用其提供的query builder或dql（doctrine query language）来构建查询，以保持orm的抽象层和数据库无关性。然而，某些特定的数据库函数，例如mysql的 binary 关键字用于强制进行区分大小写的字符串比较，并不属于dql的标准范畴。直接在query builder的 where 子句中写入 r.name = binary :name 会导致doctrine无法解析此 binary 函数，从而引发错误。
这是因为DQL被设计为一种数据库抽象语言，它只支持一组通用的SQL函数。对于特定数据库（如MySQL）的非标准函数，Doctrine ORM需要通过“自定义DQL函数”机制进行扩展。
解决方案：引入DoctrineExtensions库
为了在Doctrine中无缝使用 BINARY 这样的MySQL特有函数，最推荐和便捷的方法是利用 beberlei/DoctrineExtensions 库。这个库提供了大量常用的数据库函数作为DQL扩展，极大地增强了Doctrine的灵活性。
1. 安装DoctrineExtensions
首先，通过Composer将 beberlei/DoctrineExtensions 库添加到你的项目中：
composer require beberlei/doctrineextensions
2. 配置Doctrine以注册BINARY函数
安装完成后，需要在Doctrine的配置中注册 BINARY 函数，使其成为一个可识别的DQL函数。这通常在Symfony项目的 config/packages/doctrine.yaml 文件中完成，或者在其他PHP项目中直接通过Doctrine ORM配置。
Symfony配置示例：
# config/packages/doctrine.yaml
doctrine:
orm:
# ... 其他ORM配置
dql:
string_functions:
binary: DoctrineExtensions\Query\Mysql\Binary这段配置告诉Doctrine，当DQL中出现 BINARY 函数时，应该使用 DoctrineExtensions\Query\Mysql\Binary 这个类来处理它。string_functions 表示这是一个处理字符串的函数。
3. 在DQL或Query Builder中使用BINARY
完成上述配置后，你就可以在DQL查询或Query Builder中直接使用 BINARY 关键字进行区分大小写的比较了。
使用Query Builder的示例：
entityManager = $entityManager;
}
/**
* 根据名称进行区分大小写的查询
*
* @param string $name 要查询的名称
* @return array
*/
public function findRecordsCaseSensitive(string $name): array
{
$repo = $this->entityManager->getRepository(Records::class);
return $repo->createQueryBuilder('r')
->select('r.id', 'r.name') // 可以选择更多字段
->where('BINARY(r.name) = :name') // 注意：在DQL中，BINARY通常作为函数使用，如 BINARY(column)
->setParameter('name', $name)
->getQuery()
->getResult();
}
}重要提示： 在DQL中，BINARY 通常作为函数使用，即 BINARY(expression)，而不是像原生SQL那样直接放在列名之前。虽然在某些MySQL原生查询中 WHERE column = BINARY 'text' 是有效的，但在DQL的抽象层中，将其视为一个函数 BINARY(column) 更符合DQL函数的语法习惯。DoctrineExtensions 中的 Binary 类也正是以函数形式注册和解析的。
进一步探索：DoctrineExtensions提供的其他功能
beberlei/DoctrineExtensions 不仅提供了 BINARY 函数，还包含了大量其他实用的MySQL（以及PostgreSQL、SQLite等）函数扩展，涵盖了日期时间、数值和字符串处理等多个方面。例如：
- 日期时间函数: DATE_FORMAT, DATEDIFF, FROM_UNIXTIME 等。
- 数值函数: ACOS, CEIL, FLOOR, ROUND 等。
- 字符串函数: CONCAT_WS, GROUP_CONCAT, MD5, REPLACE, REGEXP 等。
通过查阅 DoctrineExtensions 的官方文档或其GitHub仓库中的 config/mysql.yml 文件，你可以发现更多可以注册和使用的函数。
注意事项与最佳实践
- 数据库兼容性： BINARY 关键字是MySQL特有的。如果你的项目需要支持多种数据库（例如MySQL和PostgreSQL），那么使用 BINARY 可能会降低DQL的可移植性。在这种情况下，你可能需要考虑其他跨数据库的区分大小写处理方法，例如调整数据库列的字符集和排序规则（collation），或者在应用程序层面进行区分大小写处理（但这通常效率较低）。
-
性能影响： 在 WHERE 子句中使用函数（如 BINARY(r.name)）可能会阻止数据库使用为 r.name 列创建的索引，从而导致全表扫描，影响查询性能。如果区分大小写查询是核心需求且数据量大，建议考虑以下替代方案：
- 修改列的排序规则： 将 name 列的排序规则设置为区分大小写（例如 utf8mb4_bin 或 utf8mb4_0900_as_cs）。这样，默认的 = 比较就会区分大小写，无需使用 BINARY 函数，索引也能正常工作。
- 添加区分大小写的索引： 如果不改变列的默认排序规则，可以考虑为 BINARY(name) 创建函数式索引（如果你的数据库版本支持）。
- DQL函数命名： 在 doctrine.yaml 中注册的函数名（例如 binary）将是你在DQL中使用的名称。请确保这个名称清晰且不与DQL内置函数冲突。
总结
通过 beberlei/DoctrineExtensions 库，Doctrine ORM的DQL功能得到了显著增强，允许开发者在保持ORM抽象优势的同时，利用数据库特有的强大函数。对于需要在Doctrine Query Builder中执行区分大小写查询的场景，注册 BINARY DQL函数提供了一个简洁有效的解决方案。然而，在实施此类特定数据库功能时，务必考虑其对数据库兼容性和查询性能的潜在影响，并根据具体需求选择最合适的策略。
