Initial draft for filter documentation
This commit is contained in:
parent
d378b5aec8
commit
7c8a9c0f9a
68
en/reference/filters.rst
Normal file
68
en/reference/filters.rst
Normal file
@ -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
|
||||
<?php
|
||||
namespace Example;
|
||||
use Doctrine\ORM\Mapping\ClassMetaData,
|
||||
Doctrine\ORM\Query\Filter\SQLFilter;
|
||||
|
||||
class MyLocaleFilter extends SQLFilter
|
||||
{
|
||||
public function addFilterConstraint(ClassMetadata $targetEntity, $targetTableAlias)
|
||||
{
|
||||
// Check if the entity implements the LocalAware interface
|
||||
if (!in_array("LocaleAware", $targetEntity->reflClass->getInterfaceNames())) {
|
||||
return "";
|
||||
}
|
||||
|
||||
return $targetTableAlias.'.locale = ' . $this->getParameter('locale');
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
Filter classes are added to the configuration as following:
|
||||
|
||||
.. code-block:: php
|
||||
<?php
|
||||
$config->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
|
||||
<?php
|
||||
$filter = $em->getFilters()->enable("locale");
|
||||
$filter->setParameter('locale', 'en');
|
||||
|
||||
|
||||
Disabling Filters
|
||||
-----------------
|
||||
.. code-block:: php
|
||||
$filter = $em->getFilters()->disable("locale");
|
Loading…
Reference in New Issue
Block a user