From 214f9975e01d2454e82c7abde8b21937b4c4d4a2 Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Mon, 12 Feb 2024 13:18:49 +0100 Subject: [PATCH 1/4] [Docs] Rewording, improving structure Page: https://www.doctrine-project.org/projects/doctrine-orm/en/current/cookbook/dql-user-defined-functions.html --- .../cookbook/dql-user-defined-functions.rst | 74 +++++++++---------- 1 file changed, 34 insertions(+), 40 deletions(-) diff --git a/docs/en/cookbook/dql-user-defined-functions.rst b/docs/en/cookbook/dql-user-defined-functions.rst index b189ed59fcd..fa59673aadb 100644 --- a/docs/en/cookbook/dql-user-defined-functions.rst +++ b/docs/en/cookbook/dql-user-defined-functions.rst @@ -3,69 +3,63 @@ DQL User Defined Functions .. sectionauthor:: Benjamin Eberlei -By default DQL supports a limited subset of all the vendor-specific -SQL functions common between all the vendors. However in many cases -once you have decided on a specific database vendor, you will never -change it during the life of your project. This decision for a -specific vendor potentially allows you to make use of powerful SQL -features that are unique to the vendor. - -It is worth to mention that Doctrine ORM also allows you to handwrite -your SQL instead of extending the DQL parser. Extending DQL is sort of an -advanced extension point. You can map arbitrary SQL to your objects -and gain access to vendor specific functionalities using the +By default, DQL supports a limited subset of SQL functions which are common between all the vendors. + +If you need to write vendor-specific SQL, you have two options: + +* You can map arbitrary SQL to your objects +and gain access to vendor-specific functionalities using the ``EntityManager#createNativeQuery()`` API as described in the :doc:`Native Query <../reference/native-sql>` chapter. +* The DQL parser has hooks to register functions that can then be +used in your DQL queries and transformed into SQL, allowing to +extend Doctrine's query capabilities to the vendors strength. This +chapter explains the user-defined functions API of the DQL +parser and shows some examples. +There are three types of functions in DQL: +* those that return a **numerical value** +* those that return a **string** +* and those that return a **date.** -The DQL Parser has hooks to register functions that can then be -used in your DQL queries and transformed into SQL, allowing to -extend Doctrines Query capabilities to the vendors strength. This -post explains the User-Defined Functions API (UDF) of the Dql -Parser and shows some examples to give you some hints how you would -extend DQL. - -There are three types of functions in DQL, those that return a -numerical value, those that return a string and those that return a -Date. Your custom method has to be registered as either one of +Your custom method has to be registered as either one of those. The return type information is used by the DQL parser to -check possible syntax errors during the parsing process, for -example using a string function return value in a math expression. +check possible syntax errors during the parsing process (e.g. +using a string function return value in a math expression). Registering your own DQL functions ---------------------------------- -You can register your functions adding them to the ORM -configuration: +You can register a function by adding them to the ORM configuration: .. code-block:: php addCustomStringFunction($name, $class); - $config->addCustomNumericFunction($name, $class); - $config->addCustomDatetimeFunction($name, $class); + use Doctrine\ORM\Configuration; - $em = new EntityManager($connection, $config); + $configuration = new Configuration(); + $configuration->addCustomStringFunction($name, $class); + $configuration->addCustomNumericFunction($name, $class); + $configuration->addCustomDatetimeFunction($name, $class); -The ``$name`` is the name the function will be referred to in the -DQL query. ``$class`` is a string of a class-name which has to -extend ``Doctrine\ORM\Query\Node\FunctionNode``. This is a class -that offers all the necessary API and methods to implement a UDF. + $em = new EntityManager($connection, $config); -Instead of providing the function class name, you can also provide -a callable that returns the function object: +* ``$name`` is the name of the function to be used in the DQL query. +* ``$class`` is either a fully-qualified class name which has to +extend ``Doctrine\ORM\Query\Node\FunctionNode``. Or a callable that returns the function object: .. code-block:: php addCustomStringFunction($name, function () { + use Doctrine\ORM\Configuration; + + $configuration = new \Doctrine\ORM\Configuration(); + $configuration->addCustomStringFunction($name, function() { return new MyCustomFunction(); }); -In this post we will implement some MySql specific Date calculation -methods, which are quite handy in my opinion: +In this chapter we will implement some MySQL specific date calculation +methods: Date Diff --------- From 3d60ccfdd876d5aa955e2d8e43660460208b9e92 Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Mon, 12 Feb 2024 13:19:39 +0100 Subject: [PATCH 2/4] Update dql-user-defined-functions.rst --- docs/en/cookbook/dql-user-defined-functions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/cookbook/dql-user-defined-functions.rst b/docs/en/cookbook/dql-user-defined-functions.rst index fa59673aadb..ae34cf77fef 100644 --- a/docs/en/cookbook/dql-user-defined-functions.rst +++ b/docs/en/cookbook/dql-user-defined-functions.rst @@ -30,7 +30,7 @@ using a string function return value in a math expression). Registering your own DQL functions ---------------------------------- -You can register a function by adding them to the ORM configuration: +You can register a function by adding it to the ORM configuration: .. code-block:: php From 5cb6c0b92044a2f0d1ed48d7c295b0b1c85c4025 Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Mon, 12 Feb 2024 22:35:59 +0100 Subject: [PATCH 3/4] Update docs/en/cookbook/dql-user-defined-functions.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Grégoire Paris --- docs/en/cookbook/dql-user-defined-functions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/cookbook/dql-user-defined-functions.rst b/docs/en/cookbook/dql-user-defined-functions.rst index ae34cf77fef..4a96b55bbb5 100644 --- a/docs/en/cookbook/dql-user-defined-functions.rst +++ b/docs/en/cookbook/dql-user-defined-functions.rst @@ -46,7 +46,7 @@ You can register a function by adding it to the ORM configuration: * ``$name`` is the name of the function to be used in the DQL query. * ``$class`` is either a fully-qualified class name which has to -extend ``Doctrine\ORM\Query\Node\FunctionNode``. Or a callable that returns the function object: +extend ``Doctrine\ORM\Query\Node\FunctionNode``, or a callable that returns the function object: .. code-block:: php From 48ae9e0a348faeedd7a8efb61431d9b56408d9bc Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Tue, 13 Feb 2024 11:00:18 +0100 Subject: [PATCH 4/4] Update dql-user-defined-functions.rst --- docs/en/cookbook/dql-user-defined-functions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/cookbook/dql-user-defined-functions.rst b/docs/en/cookbook/dql-user-defined-functions.rst index 4a96b55bbb5..db6182af6cd 100644 --- a/docs/en/cookbook/dql-user-defined-functions.rst +++ b/docs/en/cookbook/dql-user-defined-functions.rst @@ -58,7 +58,7 @@ extend ``Doctrine\ORM\Query\Node\FunctionNode``, or a callable that returns the return new MyCustomFunction(); }); -In this chapter we will implement some MySQL specific date calculation +In this article we will implement some MySQL specific date calculation methods: Date Diff