README

DQL 函数

此库提供了一组适用于 MySQL 和 PostgreSQL 的 Doctrine DQL 函数。

可用函数

DATE(expr) - 提取日期或日期时间表达式中的日期部分。
TIME(expr) - 提取提供表达式的时部分。
TIMESTAMP(expr) - 将表达式转换为 TIMESTAMP。
TIMESTAMPDIFF(unit, datetime_expr1, datetime_expr2) - 返回 datetime_expr2 – datetime_expr1，其中 datetime_expr1 和 datetime_expr2 是日期或日期时间表达式。参数 unit 可以取以下值之一：MICROSECOND（微秒）、SECOND、MINUTE、HOUR、DAY、WEEK、MONTH、QUARTER 或 YEAR。
CONVERT_TZ(expr, from_tz, to_tz) - 将时间值 expr 从由 from_tz 给定的时区转换为由 to_tz 给定的时区，并返回结果日期时间值。
DAY(expr) - 返回月份中的天数（0-31）。
DAYOFWEEK(expr) - 返回日期表达式的星期索引（1 = 星期日，2 = 星期一，…，7 = 星期六）。这些索引值对应于 ODBC 标准。
DAYOFMONTH(expr) - 返回日期表达式的月份中的天数，范围在 1 到 31 之间，或者对于 '0000-00-00' 或 '2008-00-00' 等具有零天部分的日期为 0。
DAYOFYEAR(expr) - 返回年份中的天数（1-366）。
HOUR(expr) - 返回从参数中的小时。
MD5(expr) - 计算MD5校验和。
MINUTE(expr) - 返回参数中的分钟。
MONTH(expr) - 返回日期中通过的月份。
QUARTER(expr) - 返回日期中通过的季度。
SECOND(expr) - 返回参数中的秒。
WEEK(expr) - 返回年份中该天所在的周数。根据 ISO 8601，周从星期一开始，该年的第一周包含该年的 1 月 4 日。换句话说，该年的第一个星期四在该年的第 1 周中。
YEAR(expr) - 返回日期中通过的年份。
POW(expr, power) - 返回将参数提升到指定幂的结果。
ROUND(value, ?precision) - 将值四舍五入到指定的精度（如果未指定，默认为 0 精度）。
CEIL(value) - 返回向上取整的值。
SIGN(expr) - 返回参数的符号。
CAST(expr as type) - 任何类型的表达式都生成一个指定类型的值。支持的类型包括：char、string、text、date、datetime、time、int、integer、bigint、decimal、boolean、binary、uuid。
CONCAT_WS - 连接所有除了第一个参数之外的所有参数。第一个参数用作分隔符字符串。
GROUP_CONCAT - 返回一个连接的字符串。GROUP_CONCAT 完整语法

GROUP_CONCAT([DISTINCT] expr [,expr ...]
            [ORDER BY {unsigned_integer | col_name | expr}
                [ASC | DESC] [,col_name ...]]
            [SEPARATOR str_val])

REPLACE(subject, from, to) - 在字符串 subject 中替换所有出现的字符串 from 为 to。
DATE_FORMAT(date, format) - 根据格式字符串格式化日期值。格式字符串中可以使用以下指定符（在指定符字符之前需要使用%字符）

安装

将以下依赖项添加到您的 composer.json 文件中

{
    "require": {
        "oro/doctrine-extensions": "^2.0"
    }
}

注册函数

Doctrine2

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

<?php
$config = new \Doctrine\ORM\Configuration();
$config->addCustomStringFunction('group_concat', 'Oro\ORM\Query\AST\Functions\String\GroupConcat');
$config->addCustomNumericFunction('hour', 'Oro\ORM\Query\AST\Functions\SimpleFunction');
$config->addCustomDatetimeFunction('date', 'Oro\ORM\Query\AST\Functions\SimpleFunction');

$em = EntityManager::create($dbParams, $config);

Symfony

在 Symfony 中，您可以在 config.yml 中注册函数

doctrine:
    orm:
        dql:
            datetime_functions:
                date:           Oro\ORM\Query\AST\Functions\SimpleFunction
                time:           Oro\ORM\Query\AST\Functions\SimpleFunction
                timestamp:      Oro\ORM\Query\AST\Functions\SimpleFunction
                convert_tz:     Oro\ORM\Query\AST\Functions\DateTime\ConvertTz
            numeric_functions:
                timestampdiff:  Oro\ORM\Query\AST\Functions\Numeric\TimestampDiff
                dayofyear:      Oro\ORM\Query\AST\Functions\SimpleFunction
                dayofmonth:     Oro\ORM\Query\AST\Functions\SimpleFunction
                dayofweek:      Oro\ORM\Query\AST\Functions\SimpleFunction
                week:           Oro\ORM\Query\AST\Functions\SimpleFunction
                day:            Oro\ORM\Query\AST\Functions\SimpleFunction
                hour:           Oro\ORM\Query\AST\Functions\SimpleFunction
                minute:         Oro\ORM\Query\AST\Functions\SimpleFunction
                month:          Oro\ORM\Query\AST\Functions\SimpleFunction
                quarter:        Oro\ORM\Query\AST\Functions\SimpleFunction
                second:         Oro\ORM\Query\AST\Functions\SimpleFunction
                year:           Oro\ORM\Query\AST\Functions\SimpleFunction
                sign:           Oro\ORM\Query\AST\Functions\Numeric\Sign
                pow:            Oro\ORM\Query\AST\Functions\Numeric\Pow
                round:          Oro\ORM\Query\AST\Functions\Numeric\Round
                ceil:           Oro\ORM\Query\AST\Functions\SimpleFunction
            string_functions:
                md5:            Oro\ORM\Query\AST\Functions\SimpleFunction
                group_concat:   Oro\ORM\Query\AST\Functions\String\GroupConcat
                concat_ws:      Oro\ORM\Query\AST\Functions\String\ConcatWs
                cast:           Oro\ORM\Query\AST\Functions\Cast
                replace:        Oro\ORM\Query\AST\Functions\String\Replace
                date_format:    Oro\ORM\Query\AST\Functions\String\DateFormat

Laminas 项目

在 Laminas 项目（使用 DoctrineORMModule）中，您可以在 config/autoload/doctrine.global.php 中注册函数

return [
    'doctrine' => [
        'configuration' => [
            'orm_default' => [
                'datetime_functions' => [
                    'date'          => \Oro\ORM\Query\AST\Functions\SimpleFunction::class,
                    'time'          => \Oro\ORM\Query\AST\Functions\SimpleFunction::class,
                    'timestamp'     => \Oro\ORM\Query\AST\Functions\SimpleFunction::class,
                    'convert_tz'    => \Oro\ORM\Query\AST\Functions\DateTime\ConvertTz::class,
                ],
                'numeric_functions' => [
                    'timestampdiff' => \Oro\ORM\Query\AST\Functions\Numeric\TimestampDiff::class,
                    'dayofyear'     => \Oro\ORM\Query\AST\Functions\SimpleFunction::class,
                    'dayofmonth'    => \Oro\ORM\Query\AST\Functions\SimpleFunction::class,
                    'dayofweek'     => \Oro\ORM\Query\AST\Functions\SimpleFunction::class,
                    'week'          => \Oro\ORM\Query\AST\Functions\SimpleFunction::class,
                    'day'           => \Oro\ORM\Query\AST\Functions\SimpleFunction::class,
                    'hour'          => \Oro\ORM\Query\AST\Functions\SimpleFunction::class,
                    'minute'        => \Oro\ORM\Query\AST\Functions\SimpleFunction::class,
                    'month'         => \Oro\ORM\Query\AST\Functions\SimpleFunction::class,
                    'quarter'       => \Oro\ORM\Query\AST\Functions\SimpleFunction::class,
                    'second'        => \Oro\ORM\Query\AST\Functions\SimpleFunction::class,
                    'year'          => \Oro\ORM\Query\AST\Functions\SimpleFunction::class,
                    'sign'          => \Oro\ORM\Query\AST\Functions\Numeric\Sign::class,
                    'pow'           => \Oro\ORM\Query\AST\Functions\Numeric\Pow::class,
                    'round'         => \Oro\ORM\Query\AST\Functions\Numeric\Round::class,
                    'ceil'          => \Oro\ORM\Query\AST\Functions\SimpleFunction::class,
                ],
                'string_functions'  => [
                    'md5'           => \Oro\ORM\Query\AST\Functions\SimpleFunction::class,
                    'group_concat'  => \Oro\ORM\Query\AST\Functions\String\GroupConcat::class,
                    'cast'          => \Oro\ORM\Query\AST\Functions\Cast::class,
                    'concat_ws'     => \Oro\ORM\Query\AST\Functions\String\ConcatWs::class,
                    'replace'       => \Oro\ORM\Query\AST\Functions\String\Replace::class,
                    'date_format'   => \Oro\ORM\Query\AST\Functions\String\DateFormat::class
                ]
            ]
        ]
    ]
];

贡献

架构

DQL 函数解析

大多数只需要一个算术主语参数的函数可以使用 Oro\ORM\Query\AST\Functions\SimpleFunction 进行解析。该类负责解析函数定义并将解析的数据保存到参数中。它扩展了 Oro\ORM\Query\AST\Functions\AbstractPlatformAwareFunctionNode。

SQL 生成

SQL 生成是特定于平台的函数的责任，这些函数扩展了 PlatformFunctionNode。 AbstractPlatformAwareFunctionNode 根据当前连接中使用的数据库平台实例名称和 DQL 函数名称创建一个适当的平台函数实例。

平台函数类的命名规则

Oro\ORM\Query\AST\Platform\Functions\$platformName\$functionName

添加新平台

要添加对新的平台的支持，您只需创建一个新的文件夹 Oro\ORM\Query\AST\Platform\Functions\$platformName，并在其中添加所有必需函数的实现（使用上述指定的命名规则）。

添加新函数

如果您的函数是只有一个算术主语参数的函数，您不需要自定义 DQL 函数解析器，可以使用 Oro\ORM\Query\AST\Functions\SimpleFunction。然后只需要您的函数的特定于平台的 SQL 实现即可。

如果您的函数是更复杂的函数，如 GROUP_CONCAT，则需要 DQL 解析器和 SQL 实现。

如果您想向此库添加新函数，请随意进行分支并创建一个带有您实现功能的拉取请求。请记住更新文档（此 README.md 文件）以包含您的新函数描述，并添加必要的测试（以及/或测试用例）。所有新函数都必须为支持的两个平台（MySQL 和 PostgreSQL）实现。

字段类型

此库还提供以下字段类型

MoneyType
PercentType
ObjectType
ArrayType

ObjectType 和 ArrayType 使用 Base64 编码字符串来在数据库中存储值，而不是存储序列化字符串。为了向后兼容，已存储在数据库中的值将在 Base64 编码之前进行反序列化。新值在保存到数据库之前将进行 Base64 编码，在反序列化之前将进行 Base64 解码。

durimjusaj / doctrine-extensions

维护者

详情