README

DoctrineJsonFunctions

Doctrine 2+ 的扩展集合，增加了对JSON函数的支持。+支持MySQL、MariaDb和PostgreSQL的函数。

目录

• 每个版本的变更日志
• 安装
• 测试
• 函数注册
  • Doctrine
  • Symfony
• 使用方法
  • 使用MySQL 5.7+ JSON运算符
  • 使用PostgreSQL 9.3+ JSON运算符
  • 使用SQLite JSON运算符
• DQL函数
  • MySQL 5.7+ JSON运算符
  • PostgreSQL 9.3+ JSON运算符
  • SQLite json1扩展运算符
• 可扩展性和数据库支持
  • 架构
  • 添加新平台
  • 添加新函数

变更日志

每个github发布中都记录了每个版本的变更。您可以在以下位置找到概述：https://github.com/ScientaNL/DoctrineJsonFunctions/releases

安装

安装DoctrineJsonFunctions的推荐方式是通过Composer。

运行以下命令来安装包

composer require scienta/doctrine-json-functions

或者，您可以下载源代码文件并解压。

测试

此仓库使用phpunit进行测试。如果您只想运行测试，可以使用docker composer镜像安装和运行phpunit。有一个docker-compose文件具有正确的挂载，但如果您只想使用docker，您可以运行以下命令

php8

docker run -it -v ${PWD}:/app scienta/php-composer:php8 /bin/bash -c "composer install && ./vendor/bin/phpunit"

函数注册

Doctrine ORM

Doctrine文档：“DQL用户定义函数”

<?php

use Scienta\DoctrineJsonFunctions\Query\AST\Functions\Mysql as DqlFunctions;

$config = new \Doctrine\ORM\Configuration();
$config->addCustomStringFunction(DqlFunctions\JsonExtract::FUNCTION_NAME, DqlFunctions\JsonExtract::class);
$config->addCustomStringFunction(DqlFunctions\JsonSearch::FUNCTION_NAME, DqlFunctions\JsonSearch::class);

$em = EntityManager::create($dbParams, $config);
$queryBuilder = $em->createQueryBuilder();

Symfony与Doctrine包

Symfony文档：“DoctrineBundle配置”

# config/packages/doctrine.yaml
doctrine:
    orm:
        dql:
            string_functions:
                JSON_EXTRACT: Scienta\DoctrineJsonFunctions\Query\AST\Functions\Mysql\JsonExtract
                JSON_SEARCH: Scienta\DoctrineJsonFunctions\Query\AST\Functions\Mysql\JsonSearch

请注意，doctrine缺少boolean_functions条目。您可以将布尔函数注册为string_functions，并使用= true进行比较以避免DQL解析错误。例如，要检查JSONB数组中是否存在元素，请使用andWhere('JSONB_EXISTS(u.roles, :role) = true')。

使用方法

请注意在创建表达式时的比较，并转义参数以使其成为有效的JSON。

使用MySQL 5.7+ JSON运算符

$q = $queryBuilder
  ->select('c')
  ->from('Customer', 'c')
  ->where("JSON_CONTAINS(c.attributes, :certificates, '$.certificates') = 1");

$result = $q->execute(array(
  'certificates' => '"BIO"',
));

使用PostgreSQL 9.3+ JSON运算符

请注意，您需要使用函数名称。此库不支持自定义运算符，如@>。

$q = $queryBuilder
  ->select('c')
  ->from('Customer', 'c')
  ->where("JSON_GET_TEXT(c.attributes, 'gender') = :gender");

 $result = $q->execute(array(
    'gender' => 'male',
 ));

布尔函数需要注册为字符串函数并与“true”进行比较，因为Doctrine DQL不了解布尔函数。

$q = $queryBuilder
  ->select('c')
  ->from('Customer', 'c')
  ->where('JSONB_CONTAINS(c.roles, :role) = true');

 $result = $q->execute(array(
    'role' => 'ROLE_ADMIN',
 ));

使用SQLite JSON运算符

$q = $queryBuilder
  ->select('c')
  ->from('Customer', 'c')
  ->where("JSON_EXTRACT(c.attributes, '$.gender') = :gender");

 $result = $q->execute();

DQL函数

库提供以下DQL函数集。

MySQL 5.7+ JSON运算符

• JSON_ARRAY_APPEND(json_doc, path, val[, path, val] ...)
  • 将值追加到JSON文档中指定的数组的末尾并返回结果。
• JSON_ARRAYAGG(value)
  • 将结果集聚合为一个由行组成的单个JSON数组。
• JSON_ARRAY_INSERT(json_doc, path, val[, path, val] ...)
  • 更新JSON文档，在文档中的数组中插入数据并返回修改后的文档。
• JSON_ARRAY([val[, val] ...])
  • 评估一个（可能为空）的值列表，并返回包含这些值的JSON数组。
• JSON_CONTAINS_PATH(json_doc, one_or_all, path[, path] ...)
  • 返回0或1以指示JSON文档是否包含给定路径或路径中的数据。
• JSON_CONTAINS(json_doc, val[, path])
  • 返回0或1以指示特定值是否包含在目标JSON文档中，或者，如果提供了路径参数，则在目标文档的特定路径中。
• JSON_DEPTH(json_doc)
  • 返回JSON文档的最大深度。
• JSON_EXTRACT(json_doc, path[, path] ...)
  • 从JSON文档中返回数据，从与路径参数匹配的文档部分中选择。
• JSON_OVERLAPS(json_doc1, json_doc2)
  • 比较两个JSON文档。如果两个文档有共同的键值对或数组元素，则返回true（1）。如果两个参数都是标量，则函数执行简单的相等性测试。
• JSON_INSERT(json_doc, path, val[, path, val] ...)
  • 将数据插入JSON文档并返回结果。
• JSON_KEYS(json_doc[, path])
  • 返回JSON对象的顶层值作为JSON数组，或者，如果提供了路径参数，返回所选路径的顶层键。
• JSON_LENGTH(json_doc[, path])
  • 返回JSON文档的长度，或者，如果提供了路径参数，返回由路径标识的文档中的值的长度。
• JSON_MERGE(json_doc, json_doc[, json_doc] ...)
  • 合并两个或多个JSON文档并返回合并结果。
• JSON_MERGE_PRESERVE(json_doc, json_doc[, json_doc] ...)
  • 合并两个或多个JSON文档并返回合并结果。如果任何参数为NULL，则返回NULL。如果任何参数不是有效的JSON文档，则发生错误。
• JSON_MERGE_PATCH(json_doc, json_doc[, json_doc] ...)
  • 执行符合RFC 7396的合并，并返回合并结果。
• JSON_OBJECT([key, val[, key, val] ...])
  • 评估一个（可能为空）的键值对列表，并返回包含这些对的JSON对象。
• JSON_OBJECTAGG(key, val)
  • 将两个列名或表达式作为参数，第一个用作键，第二个用作值，并返回包含键值对的JSON对象。
• JSON_PRETTY(json_val)
  • 提供与PHP和其他语言以及数据库系统实现的类似的美化打印的JSON值。
• JSON_QUOTE(json_val)
  • 通过将字符串用双引号括起来并转义内部引号和其他字符，然后将结果作为utf8mb4字符串返回，将字符串引用为JSON值。
• JSON_REMOVE(json_doc, path[, path] ...)
  • 从JSON文档中删除数据并返回结果。
• JSON_REPLACE(json_doc, path, val[, path, val] ...)
  • 替换JSON文档中的现有值并返回结果。
• JSON_SEARCH(json_doc, one_or_all, search_str[, escape_char[, path] ...])
  • 返回JSON文档中给定字符串的路径。
• JSON_SET(json_doc, path, val[, path, val] ...)
  • 在JSON文档中插入或更新数据，并返回结果。
• JSON_TYPE(json_val)
  • 返回表示JSON值类型的utf8mb4字符串。
• JSON_UNQUOTE(val)
  • 取消JSON值的引号，并以utf8mb4字符串返回结果。
• JSON_VALID(val)
  • 返回0或1以指示值是否为有效的JSON文档。

注意，如果兼容，您可以使用MySQL运算符与MariaDb数据库一起使用。

MariaDb 10.2.3 JSON运算符

• JSON_VALUE(json_doc, path)
  • 返回由路径指定的标量。如果没有匹配项，则返回NULL。
• JSON_EXISTS(json_doc, path)
  • 确定指定的JSON值是否存在于给定数据中。如果找到，则返回1；如果没有找到，则返回0；如果任何输入为NULL，则返回NULL。
• JSON_QUERY(json_doc, path)
  • 给定一个JSON文档，返回由路径指定的对象或数组。如果没有给出有效的JSON文档或没有匹配项，则返回NULL。

MariaDb 10.2.4 JSON运算符

• JSON_COMPACT(json_doc)
  • 删除所有不必要的空格，使json文档尽可能短。
• JSON_DETAILED(json_doc[, tab_size])
  • 以最易于理解的方式表示JSON，强调嵌套结构。
• JSON_LOOSE(json_doc)
  • 向JSON文档添加空格，使其更具可读性。

MariaDb 10.7.0 JSON运算符

• JSON_EQUALS(json_doc, json_doc)
  • 检查两个json对象之间是否存在相等性。如果存在，则返回1；如果不相等，则返回0；如果任何参数为null，则返回null。
• JSON_NORMALIZE(json_doc)
  • 递归排序键并删除空格，允许比较json文档以检查相等性。

PostgreSQL 9.3+ JSON运算符

JSON运算符的基本支持已实现。即使与Doctrine\DBAL v2.5一起使用，也能正常工作。JSON运算符的官方文档。

• JSONB_CONTAINS(jsonb, jsonb)
  • 展开为jsonb @> jsonb
• JSONB_EXISTS(jsonb, text)
  • 作为JSONB_EXISTS(jsonb, text)执行，相当于jsonb ? text
• JSONB_EXISTS_ALL(jsonb, array)
  • 作为JSONB_EXISTS_ALL(jsonb, array)执行，相当于jsonb ?& array
• JSONB_EXISTS_ANY(jsonb, array)
  • 作为JSONB_EXISTS_ANY(jsonb, array)执行，相当于jsonb ?| array
• JSONB_IS_CONTAINED(jsonb, jsonb)
  • 展开为jsonb <@ jsonb
• JSONB_INSERT
  • 直接执行
• JSON_EXTRACT_PATH
  • 直接执行
• JSON_GET(jsondoc, path)
  • 在path为数值时展开为jsondoc->path（用于JSON数组）
  • 在path为非数值时展开为jsondoc->'path'（用于JSON对象）
• JSON_GET_TEXT(jsondoc, path)
  • 在path为数值时展开为jsondoc->>path（用于JSON数组）
  • 在path为非数值时展开为jsondoc->>'path'（用于JSON对象）
• JSON_GET_PATH(jsondoc, path)
  • 展开为jsondoc#>'path'
• JSON_GET_PATH_TEXT(jsondoc, path)
  • 展开为jsondoc#>>'path'

请注意，不支持JSON运算符的链式调用。

SQLite JSON1扩展运算符

支持JSON1扩展文档中看到的全部标量函数和聚合函数。

标量函数

• JSON(json)
  • 验证其参数是否为有效的JSON字符串，并返回该JSON字符串的最小化版本。
• JSON_ARRAY([val[, val] ...])
  • 接受零个或多个参数，并返回由这些参数组成的格式良好的JSON数组。
• JSON_ARRAY_LENGTH(json[, path])
  • 返回JSON数组json中的元素数量，如果json是除数组之外的其他类型的JSON值，则返回0。
• JSON_EXTRACT(json, path[, path ], ...)
  • 从格式良好的JSON中提取并返回一个或多个值。
• JSON_INSERT(json[, path, value],...)
  • 给定零个或多个路径和值的集合，它会在json的对应路径插入每个值（不会覆盖）。
• JSON_OBJECT(label, value[, label, value], ...)
  • 接受零个或多个参数对，并返回由这些参数组成的格式良好的JSON对象。
• JSON_PATCH(target, patch)
  • 将补丁应用于target。
• JSON_QUOTE(value)
  • 将SQL中的value（一个数字或字符串）转换为相应的JSON表示。
• JSON_REMOVE(json[, path], ...)
  • 移除每个给定路径的值。
• JSON_REPLACE(json[, path, value],...)
  • 给定零个或多个路径和值的集合，它会覆盖json中对应路径的每个值。
• JSON_SET(json[, path, value],...)
  • 给定零个或多个路径和值的集合，它会在json的对应路径插入或覆盖每个值。
• JSON_TYPE(json[, path])
  • 返回json最外层元素的类型或路径上的值的类型。
• JSON_VALID(json)
  • 如果参数json是格式良好的JSON则返回1，否则返回0。

聚合函数

• JSON_GROUP_ARRAY(value)
  • 返回由聚合中的所有value组成的JSON数组。
• JSON_GROUP_OBJECT(name, value)
  • 返回由聚合中的所有name/value对组成的JSON对象。

可扩展性和数据库支持

架构

平台函数类命名规则是

Scienta\DoctrineJsonFunctions\Query\AST\Functions\$platformName\$functionName

添加新的平台

要添加对新平台的支持，只需创建新的文件夹Scienta\DoctrineJsonFunctions\Query\AST\Functions\$platformName并在其中根据命名规则实现所需的功能。

添加新的函数

如果您想向此库添加新功能，请随意将其分支出来并创建带有您实现的pull request。请记住，更新文档以包含您的新功能。

另请参阅

dunglas/doctrine-json-odm：将普通PHP对象序列化/反序列化到JSON列。