From 7c8a9c0f9a2439bc0559ac5d7941327b057a6a06 Mon Sep 17 00:00:00 2001 From: Alexander Date: Wed, 18 Jan 2012 20:50:20 +0100 Subject: [PATCH 1/4] Initial draft for filter documentation --- en/reference/filters.rst | 68 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 en/reference/filters.rst diff --git a/en/reference/filters.rst b/en/reference/filters.rst new file mode 100644 index 000000000..487c52c8d --- /dev/null +++ b/en/reference/filters.rst @@ -0,0 +1,68 @@ +Filters +======= + +Doctrine 2.2 features a filter system that allows the developer to add SQL to +the conditional clauses of queries, regardless the place where the SQL is +generated (e.g. from a DQL query, or by loading associated entities). To give +you an idea on how it works, this chapter starts with an example of a filter. + + +Example filter class +-------------------- +Throughout this document the example ``MyLocaleFilter`` class will be used to +illustrate how the filter feature works. A filter class should extend the base +``Doctrine\ORM\Query\Filter\SQLFilter`` class and implement the ``addFilterConstraint`` +method. The method receives the ClassMetadata of the filtered entity and the +table alias of the table of the entity. + +.. code-block:: php + reflClass->getInterfaceNames())) { + return ""; + } + + return $targetTableAlias.'.locale = ' . $this->getParameter('locale'); + } + } + + + + +Configuration +------------- +Filter classes are added to the configuration as following: + +.. code-block:: php + addFilter("locale", "\Doctrine\Tests\ORM\Functional\MyLocaleFilter"); + + +The ``addFilter()`` method takes a name for the filter and the name of the +class responsible for the actual filtering. + + +Enabling Filters and Setting Parameters +--------------------------------------------------- +Filters can be enabled via the ``FilterCollection`` that is available in the +``EntityManager``. The ``enable`` function will return the filter object. This +object can be used to set certain parameters for the filter. + +.. code-block:: php + getFilters()->enable("locale"); + $filter->setParameter('locale', 'en'); + + +Disabling Filters +----------------- +.. code-block:: php + $filter = $em->getFilters()->disable("locale"); From cfbfac6a51b21fdd287a5df47eee6b1847efea75 Mon Sep 17 00:00:00 2001 From: Alexander Date: Tue, 31 Jan 2012 08:49:16 +0100 Subject: [PATCH 2/4] General information on how the filter work etc + warning on the enabling/disabling part --- en/reference/filters.rst | 32 +++++++++++++++++++++++++------- 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/en/reference/filters.rst b/en/reference/filters.rst index 487c52c8d..d925fae54 100644 --- a/en/reference/filters.rst +++ b/en/reference/filters.rst @@ -3,17 +3,32 @@ Filters Doctrine 2.2 features a filter system that allows the developer to add SQL to the conditional clauses of queries, regardless the place where the SQL is -generated (e.g. from a DQL query, or by loading associated entities). To give -you an idea on how it works, this chapter starts with an example of a filter. +generated (e.g. from a DQL query, or by loading associated entities). +The filter functionality works on SQL level. Whether an SQL query is generated +in a Persister, during lazy loading, in extra lazy collections or from DQL. +Each time the system iterates over all the enabled filters, adding a new SQL +part as a filter returns. + +By adding SQL to the conditional clauses of queries, the filter system filters +out rows belonging to the entities at the level of the SQL result set. This +means that the filtered entities are never hydrated (which can be expensive). + +To give you an idea on how it works, the next section contains an example of a +filter. Example filter class -------------------- Throughout this document the example ``MyLocaleFilter`` class will be used to illustrate how the filter feature works. A filter class should extend the base ``Doctrine\ORM\Query\Filter\SQLFilter`` class and implement the ``addFilterConstraint`` -method. The method receives the ClassMetadata of the filtered entity and the -table alias of the table of the entity. +method. The method receives the ``ClassMetadata`` of the filtered entity and the +table alias of the SQL table of the entity. + +Parameters for the query should be set on the filter object by +``SQLFilter::setParameter()``. Only parameters set via this function used in +the filters. The ``SQLFilter::getParameter()`` function takes care of the +proper quoting of parameters. .. code-block:: php getParameter('locale'); + return $targetTableAlias.'.locale = ' . $this->getParameter('locale'); // Automatically quoted } } - - Configuration ------------- Filter classes are added to the configuration as following: @@ -61,6 +74,11 @@ object can be used to set certain parameters for the filter. $filter = $em->getFilters()->enable("locale"); $filter->setParameter('locale', 'en'); +.. warning:: + Disabling and enabling filters does not have effect on objects that you + already have. If you want to reload an object after you disabled, enabled + or changed a filter, then you should clear the EM and re-fetch the object + so the appropriate SQL will be executed. Disabling Filters ----------------- From ff9e7ef64b5f18941f663ded9aa99bb862455369 Mon Sep 17 00:00:00 2001 From: Alexander Date: Tue, 31 Jan 2012 15:38:27 +0100 Subject: [PATCH 3/4] Processed comments of @Ocramius --- en/reference/filters.rst | 37 +++++++++++++++++-------------------- 1 file changed, 17 insertions(+), 20 deletions(-) diff --git a/en/reference/filters.rst b/en/reference/filters.rst index d925fae54..6c663c465 100644 --- a/en/reference/filters.rst +++ b/en/reference/filters.rst @@ -14,20 +14,18 @@ By adding SQL to the conditional clauses of queries, the filter system filters out rows belonging to the entities at the level of the SQL result set. This means that the filtered entities are never hydrated (which can be expensive). -To give you an idea on how it works, the next section contains an example of a -filter. Example filter class -------------------- Throughout this document the example ``MyLocaleFilter`` class will be used to -illustrate how the filter feature works. A filter class should extend the base +illustrate how the filter feature works. A filter class must extend the base ``Doctrine\ORM\Query\Filter\SQLFilter`` class and implement the ``addFilterConstraint`` method. The method receives the ``ClassMetadata`` of the filtered entity and the table alias of the SQL table of the entity. Parameters for the query should be set on the filter object by -``SQLFilter::setParameter()``. Only parameters set via this function used in -the filters. The ``SQLFilter::getParameter()`` function takes care of the +``SQLFilter#setParameter()``. Only parameters set via this function used in +the filters. The ``SQLFilter#getParameter()`` function takes care of the proper quoting of parameters. .. code-block:: php @@ -45,7 +43,7 @@ proper quoting of parameters. return ""; } - return $targetTableAlias.'.locale = ' . $this->getParameter('locale'); // Automatically quoted + return $targetTableAlias.'.locale = ' . $this->getParameter('locale'); // getParameter applies quoting automatically } } @@ -59,28 +57,27 @@ Filter classes are added to the configuration as following: $config->addFilter("locale", "\Doctrine\Tests\ORM\Functional\MyLocaleFilter"); -The ``addFilter()`` method takes a name for the filter and the name of the +The ``Configuration#addFilter()`` method takes a name for the filter and the name of the class responsible for the actual filtering. -Enabling Filters and Setting Parameters +Disabling/Enabling Filters and Setting Parameters --------------------------------------------------- -Filters can be enabled via the ``FilterCollection`` that is available in the -``EntityManager``. The ``enable`` function will return the filter object. This -object can be used to set certain parameters for the filter. +Filters can be disabled and enabled via the ``FilterCollection`` which is +stored in the ``EntityManager``. The ``FilterCollection#enable($name)`` method +will retrieve the filter object. You can set the filter parameters on that +object. .. code-block:: php getFilters()->enable("locale"); $filter->setParameter('locale', 'en'); -.. warning:: - Disabling and enabling filters does not have effect on objects that you - already have. If you want to reload an object after you disabled, enabled - or changed a filter, then you should clear the EM and re-fetch the object - so the appropriate SQL will be executed. - -Disabling Filters ------------------ -.. code-block:: php + // Disable it $filter = $em->getFilters()->disable("locale"); + +.. warning:: + Disabling and enabling filters has no effect on managed entities. If you + want to refresh or reload an object after having modified a filter or the + FilterCollection, then you should clear the EntityManager and re-fetch your + entities, having the new rules for filtering applied. From 6f56dbe39552d4133fd032833a370ae979139927 Mon Sep 17 00:00:00 2001 From: Alexander Date: Tue, 31 Jan 2012 15:58:31 +0100 Subject: [PATCH 4/4] Added filters to the index --- en/index.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/en/index.rst b/en/index.rst index 8be6565fb..c58b7528c 100644 --- a/en/index.rst +++ b/en/index.rst @@ -80,6 +80,9 @@ Advanced Topics * **Database Integration**: :doc:`Transactions and Concurrency ` +* **Filtering entities**: + :doc:`Filters ` + * **Performance**: :doc:`Improving Performance ` | :doc:`Caching ` |