Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Added hydrator filter doc #595

Merged
merged 3 commits into from

2 participants

@iwalz

This doc is related to zendframework/zf2#3359

.../languages/en/modules/zend.stdlib.hydrator.filter.rst
@@ -0,0 +1,312 @@
+.. _zend.stdlib.hydrator.filter:
+
+Zend\\Stdlib\\Hydrator\\Filter
+==============================
+
+The hydrator filters, allows you to manipulate the behaviour, when you want to ``extract()`` your stuff to arrays.
@Maks3w Collaborator
Maks3w added a note

Typo s/behaviour/behavior

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
.../languages/en/modules/zend.stdlib.hydrator.filter.rst
((30 lines not shown))
+If it returns true, the key / value pairs will be in the extracted arrays - if it will return false, you'll not see
+them again.
+
+.. _zend.stdlib.hydrator.filter.implementations:
+
+Filter implementations
+----------------------
+
+- **Zend\\Stdlib\\Hydrator\\Filter\\GetFilter**
+
+ This filter is used in the ``ClassMethods`` hydrator, to decide that getters will be extracted.
+ It checks, if the key that should be extracted starts with ``get`` or looks like this ``Zend\Foo\Bar::getFoo``
+
+- **Zend\\Stdlib\\Hydrator\\Filter\\HasFilter**
+
+ This filter is used in the ``ClassMethods`` hydrator, to decide that has methods will be extracted.
@Maks3w Collaborator
Maks3w added a note

Abnormal redaction "that has methods will"

@Maks3w Collaborator
Maks3w added a note

Ah, has is a special word. Please surround it with ` character

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
.../languages/en/modules/zend.stdlib.hydrator.filter.rst
((35 lines not shown))
+Filter implementations
+----------------------
+
+- **Zend\\Stdlib\\Hydrator\\Filter\\GetFilter**
+
+ This filter is used in the ``ClassMethods`` hydrator, to decide that getters will be extracted.
+ It checks, if the key that should be extracted starts with ``get`` or looks like this ``Zend\Foo\Bar::getFoo``
+
+- **Zend\\Stdlib\\Hydrator\\Filter\\HasFilter**
+
+ This filter is used in the ``ClassMethods`` hydrator, to decide that has methods will be extracted.
+ It checks, if the key that should be extracted starts with ``has`` or looks like this ``Zend\Foo\Bar::hasFoo``
+
+- **Zend\\Stdlib\\Hydrator\\Filter\\IsFilter**
+
+ This filter is used in the ``ClassMethods`` hydrator, to decide that is methods will be extracted.
@Maks3w Collaborator
Maks3w added a note

Abnormal redaction "that is methods will"

@Maks3w Collaborator
Maks3w added a note

same not as above

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
.../languages/en/modules/zend.stdlib.hydrator.filter.rst
((41 lines not shown))
+ It checks, if the key that should be extracted starts with ``get`` or looks like this ``Zend\Foo\Bar::getFoo``
+
+- **Zend\\Stdlib\\Hydrator\\Filter\\HasFilter**
+
+ This filter is used in the ``ClassMethods`` hydrator, to decide that has methods will be extracted.
+ It checks, if the key that should be extracted starts with ``has`` or looks like this ``Zend\Foo\Bar::hasFoo``
+
+- **Zend\\Stdlib\\Hydrator\\Filter\\IsFilter**
+
+ This filter is used in the ``ClassMethods`` hydrator, to decide that is methods will be extracted.
+ It checks, if the key that should be extracted starts with ``is`` or looks like this ``Zend\Foo\Bar::isFoo``
+
+- **Zend\\Stdlib\\Hydrator\\Filter\\MethodMatchFilter**
+
+ This filter allows you to strip methods from the extraction with the correct condition in the composite.
+ It checks, if the key that should be extracted matches a method name. Eiter ``getServiceLocator`` or
@Maks3w Collaborator
Maks3w added a note

Typo s/Eiter/Either

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
.../languages/en/modules/zend.stdlib.hydrator.filter.rst
((42 lines not shown))
+
+- **Zend\\Stdlib\\Hydrator\\Filter\\HasFilter**
+
+ This filter is used in the ``ClassMethods`` hydrator, to decide that has methods will be extracted.
+ It checks, if the key that should be extracted starts with ``has`` or looks like this ``Zend\Foo\Bar::hasFoo``
+
+- **Zend\\Stdlib\\Hydrator\\Filter\\IsFilter**
+
+ This filter is used in the ``ClassMethods`` hydrator, to decide that is methods will be extracted.
+ It checks, if the key that should be extracted starts with ``is`` or looks like this ``Zend\Foo\Bar::isFoo``
+
+- **Zend\\Stdlib\\Hydrator\\Filter\\MethodMatchFilter**
+
+ This filter allows you to strip methods from the extraction with the correct condition in the composite.
+ It checks, if the key that should be extracted matches a method name. Eiter ``getServiceLocator`` or
+ ``Zend\Foo::getServicelocator``. The methodname is specified in the constructor of this filter. The 2nd parameter
@Maks3w Collaborator
Maks3w added a note

missing space between method and name. Also usually is written as "The name of the method"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
.../languages/en/modules/zend.stdlib.hydrator.filter.rst
((43 lines not shown))
+- **Zend\\Stdlib\\Hydrator\\Filter\\HasFilter**
+
+ This filter is used in the ``ClassMethods`` hydrator, to decide that has methods will be extracted.
+ It checks, if the key that should be extracted starts with ``has`` or looks like this ``Zend\Foo\Bar::hasFoo``
+
+- **Zend\\Stdlib\\Hydrator\\Filter\\IsFilter**
+
+ This filter is used in the ``ClassMethods`` hydrator, to decide that is methods will be extracted.
+ It checks, if the key that should be extracted starts with ``is`` or looks like this ``Zend\Foo\Bar::isFoo``
+
+- **Zend\\Stdlib\\Hydrator\\Filter\\MethodMatchFilter**
+
+ This filter allows you to strip methods from the extraction with the correct condition in the composite.
+ It checks, if the key that should be extracted matches a method name. Eiter ``getServiceLocator`` or
+ ``Zend\Foo::getServicelocator``. The methodname is specified in the constructor of this filter. The 2nd parameter
+ decides wheter to use white or blacklisting to decide. Default is blacklisting - pass ``false`` to change it.
@Maks3w Collaborator
Maks3w added a note

Typo s/wheter/whether

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
.../languages/en/modules/zend.stdlib.hydrator.filter.rst
((48 lines not shown))
+- **Zend\\Stdlib\\Hydrator\\Filter\\IsFilter**
+
+ This filter is used in the ``ClassMethods`` hydrator, to decide that is methods will be extracted.
+ It checks, if the key that should be extracted starts with ``is`` or looks like this ``Zend\Foo\Bar::isFoo``
+
+- **Zend\\Stdlib\\Hydrator\\Filter\\MethodMatchFilter**
+
+ This filter allows you to strip methods from the extraction with the correct condition in the composite.
+ It checks, if the key that should be extracted matches a method name. Eiter ``getServiceLocator`` or
+ ``Zend\Foo::getServicelocator``. The methodname is specified in the constructor of this filter. The 2nd parameter
+ decides wheter to use white or blacklisting to decide. Default is blacklisting - pass ``false`` to change it.
+
+- **Zend\\Stdlib\\Hydrator\\Filter\\NumberOfParameterFilter**
+
+ This filter is used in the ``ClassMethods`` hydrator, to check the number of parameters. By convention, the get, has
+ and is methods do not get any parameters - but it may happen. You can add your own number of needed parameters,
@Maks3w Collaborator
Maks3w added a note

Abnormal redaction is methods

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
.../languages/en/modules/zend.stdlib.hydrator.filter.rst
((126 lines not shown))
+
+Or you can add the shipped ones:
+
+.. code-block:: php
+ :linenos:
+
+ $hydrator->addFilter(
+ "servicemanager",
+ new MethodMatchFilter("getServiceManager"),
+ FilterComposite::CONDITION_AND
+ );
+
+The example above will exclude the ``getServiceManager`` method or the key from the extraction, even if the ``get``
+filter wants to add it.
+
+.. _zend.stdlib.hydrator.filter.compisite:
@Maks3w Collaborator
Maks3w added a note

Typo s/compisite/composite

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
.../languages/en/modules/zend.stdlib.hydrator.filter.rst
((141 lines not shown))
+.. _zend.stdlib.hydrator.filter.compisite:
+
+Use the composite for complex filters
+-------------------------------------
+
+The composite implements the ``FilterInterface`` too, so you can add it as a regular filter to the hydrator. One goody
+of this implementation, is that you can add the filters with a condition and you can do even more complex stuff with
+different composites with different conditions. You can pass the condition to the 3rd parameter, when you add a filter:
+
+**Zend\\Stdlib\\Hydrator\\Filter\\FilterComposite::CONDITION_OR**
+
+ At one level of the composite, one of all filters in that condition block has to return true in order to get extracted
+
+**Zend\\Stdlib\\Hydrator\\Filter\\FilterComposite::CONDITION_AND**
+
+ At one level of the composite, all of the filters in that condition block has to return true in order to get extracted
@Maks3w Collaborator
Maks3w added a note

Please surround true with ` character

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Maks3w Maks3w commented on the diff
.../languages/en/modules/zend.stdlib.hydrator.filter.rst
((166 lines not shown))
+ $composite->addFilter("two", $condition2);
+ $composite->addFilter("three", $condition3);
+ $composite->addFilter("four", $condition4, FilterComposite::CONDITION_AND);
+ $composite->addFilter("five", $condition5, FilterComposite::CONDITION_AND);
+
+ // This is what's happening internally
+ if (
+ (
+ $condition1
+ || $condition2
+ || $condition3
+ ) && (
+ $condition4
+ && $condition5
+ )
+ )
@Maks3w Collaborator
Maks3w added a note

According CS guidelines close brace and open curl must share the same line

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
.../languages/en/modules/zend.stdlib.hydrator.filter.rst
((171 lines not shown))
+ // This is what's happening internally
+ if (
+ (
+ $condition1
+ || $condition2
+ || $condition3
+ ) && (
+ $condition4
+ && $condition5
+ )
+ )
+ {
+ //do extraction
+ }
+
+If you've only one condition (only ``and`` or ``or``)block, the other one will be completely ignored.
@Maks3w Collaborator
Maks3w added a note

missing space after )

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
.../languages/en/modules/zend.stdlib.hydrator.filter.rst
((206 lines not shown))
+
+ // Internal
+ if (
+ ( // default composite inside the hydrator
+ (
+ $getFilter
+ || $hasFilter
+ || $isFilter
+ ) && (
+ $numberOfParamterFilter
+ )
+ ) && ( // new composite, added to the one above
+ $serviceManagerFilter
+ && $eventManagerFilter
+ )
+ )
@Maks3w Collaborator
Maks3w added a note

same CS rule

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
.../languages/en/modules/zend.stdlib.hydrator.filter.rst
((219 lines not shown))
+ && $eventManagerFilter
+ )
+ )
+ {
+ // do extraction
+ }
+
+If you perform this on the ``ClassMethods`` hydrator, all getters will get extracted, but not ``getServiceManager``
+and ``getEventManager``.
+
+.. _zend.stdlib.hydrator.filter.provider:
+
+Using the provider interface
+----------------------------
+
+There is also a provider interface, that allows you to configure the behaviour of the hydrator inside your objects.
@Maks3w Collaborator
Maks3w added a note

s/behaviour/behavior

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Maks3w
Collaborator

Thank you for cut the lines within GitHub width.

Despite the number of notes it's a good document. You know, to more text more typos.

@iwalz

Well, kinda more than usual - thanks for the review :)

@Maks3w Maks3w merged commit a39f23a into from
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Jan 12, 2013
  1. @iwalz

    Added hydrator filter doc

    iwalz authored
Commits on Jan 14, 2013
  1. @iwalz

    Fixed typo

    iwalz authored
Commits on Jan 15, 2013
  1. @iwalz

    Fixed typos

    iwalz authored
This page is out of date. Refresh to see the latest.
View
2  docs/languages/en/index.rst
@@ -184,6 +184,7 @@
modules/zend.soap.wsdl
modules/zend.soap.auto-discovery
modules/zend.stdlib.hydrator
+ modules/zend.stdlib.hydrator.filter
modules/zend.tag.introduction
modules/zend.tag.cloud
modules/zend.text.figlet
@@ -624,6 +625,7 @@ Zend\\Stdlib
^^^^^^^^^^^^
* :doc:`modules/zend.stdlib.hydrator`
+ * :doc:`modules/zend.stdlib.hydrator.filter`
.. _zend.tag:
View
310 docs/languages/en/modules/zend.stdlib.hydrator.filter.rst
@@ -0,0 +1,310 @@
+.. _zend.stdlib.hydrator.filter:
+
+Zend\\Stdlib\\Hydrator\\Filter
+==============================
+
+The hydrator filters, allows you to manipulate the behavior, when you want to ``extract()`` your stuff to arrays.
+This is especially useful, if you want to ``extract()`` your objects to the userland and strip some internals (e.g.
+``getServiceManager()``).
+
+It comes with a helpful Composite Implementation and a few filters for common use cases. The filters are implemented on
+the ``AbstractHydrator``, so you can directly start using them if you extend it - even on custom hydrators.
+
+.. code-block:: php
+ :linenos:
+
+ namespace Zend\Stdlib\Hydrator\Filter;
+
+ interface FilterInterface
+ {
+ /**
+ * Should return true, if the given filter
+ * does not match
+ *
+ * @param string $property The name of the property
+ * @return bool
+ */
+ public function filter($property);
+ }
+
+If it returns true, the key / value pairs will be in the extracted arrays - if it will return false, you'll not see
+them again.
+
+.. _zend.stdlib.hydrator.filter.implementations:
+
+Filter implementations
+----------------------
+
+- **Zend\\Stdlib\\Hydrator\\Filter\\GetFilter**
+
+ This filter is used in the ``ClassMethods`` hydrator, to decide that getters will be extracted.
+ It checks, if the key that should be extracted starts with ``get`` or looks like this ``Zend\Foo\Bar::getFoo``
+
+- **Zend\\Stdlib\\Hydrator\\Filter\\HasFilter**
+
+ This filter is used in the ``ClassMethods`` hydrator, to decide that ``has`` methods will be extracted.
+ It checks, if the key that should be extracted starts with ``has`` or looks like this ``Zend\Foo\Bar::hasFoo``
+
+- **Zend\\Stdlib\\Hydrator\\Filter\\IsFilter**
+
+ This filter is used in the ``ClassMethods`` hydrator, to decide that ``is`` methods will be extracted.
+ It checks, if the key that should be extracted starts with ``is`` or looks like this ``Zend\Foo\Bar::isFoo``
+
+- **Zend\\Stdlib\\Hydrator\\Filter\\MethodMatchFilter**
+
+ This filter allows you to strip methods from the extraction with the correct condition in the composite.
+ It checks, if the key that should be extracted matches a method name. Either ``getServiceLocator`` or
+ ``Zend\Foo::getServicelocator``. The name of the method is specified in the constructor of this filter. The 2nd parameter
+ decides whether to use white or blacklisting to decide. Default is blacklisting - pass ``false`` to change it.
+
+- **Zend\\Stdlib\\Hydrator\\Filter\\NumberOfParameterFilter**
+
+ This filter is used in the ``ClassMethods`` hydrator, to check the number of parameters. By convention, the ``get``, ``has``
+ and ``is`` methods do not get any parameters - but it may happen. You can add your own number of needed parameters,
+ simply add the number to the constructor. The default value is 0
+
+.. _zend.stdlib.hydrator.filter.remove:
+
+Remove filters
+--------------
+
+If you want to tell e.g. the ``ClassMethods`` hydrator, to not extract methods that start with ``is``, you can do so:
+
+.. code-block:: php
+ :linenos:
+
+ $hydrator = new ClassMethods(false);
+ $hydrator->removeFilter("is");
+
+The key / value pairs for ``is`` methods will not end up in your extracted array anymore. The filters can be used in
+any hydrator, but the ``ClassMethods`` hydrator is the only one, that has pre-registered filters:
+
+.. code-block:: php
+ :linenos:
+
+ $this->filterComposite->addFilter("is", new IsFilter());
+ $this->filterComposite->addFilter("has", new HasFilter());
+ $this->filterComposite->addFilter("get", new GetFilter());
+ $this->filterComposite->addFilter("parameter", new NumberOfParameterFilter(), FilterComposite::CONDITION_AND);
+
+If you're not fine with this, you can unregister them as above.
+
+.. note::
+
+ The parameter for the filter on the ``ClassMethods`` looks like this by default ``Zend\Foo\Bar::methodName``
+
+.. _zend.stdlib.hydrator.filter.add:
+
+Add filters
+-----------
+
+You can easily add filters to any hydrator, that extends the ``AbstractHydrator``. You can use the ``FilterInterface``
+or any callable:
+
+.. code-block:: php
+ :linenos:
+
+ $hydrator->addFilter("len", function($property) {
+ if (strlen($property) !== 3) {
+ return false;
+ }
+ return true;
+ });
+
+By default, every filter you add will be added with a conditional ``or``. If you want to add it with ``and``
+(as the ``NumberOfParameterFilter`` that is added to the ``ClassMethods`` hydrator by default) you can do that too:
+
+.. code-block:: php
+ :linenos:
+
+ $hydrator->addFilter("len", function($property) {
+ if (strlen($property) !== 3) {
+ return false;
+ }
+ return true;
+ }, FilterComposite::CONDITION_AND);
+
+Or you can add the shipped ones:
+
+.. code-block:: php
+ :linenos:
+
+ $hydrator->addFilter(
+ "servicemanager",
+ new MethodMatchFilter("getServiceManager"),
+ FilterComposite::CONDITION_AND
+ );
+
+The example above will exclude the ``getServiceManager`` method or the key from the extraction, even if the ``get``
+filter wants to add it.
+
+.. _zend.stdlib.hydrator.filter.composite:
+
+Use the composite for complex filters
+-------------------------------------
+
+The composite implements the ``FilterInterface`` too, so you can add it as a regular filter to the hydrator. One goody
+of this implementation, is that you can add the filters with a condition and you can do even more complex stuff with
+different composites with different conditions. You can pass the condition to the 3rd parameter, when you add a filter:
+
+**Zend\\Stdlib\\Hydrator\\Filter\\FilterComposite::CONDITION_OR**
+
+ At one level of the composite, one of all filters in that condition block has to return true in order to get extracted
+
+**Zend\\Stdlib\\Hydrator\\Filter\\FilterComposite::CONDITION_AND**
+
+ At one level of the composite, all of the filters in that condition block has to return ``true`` in order to get extracted
+
+This composition will have a similar logic as the if below:
+
+.. code-block:: php
+ :linenos:
+
+ $composite = new FilterComposite();
+
+ $composite->addFilter("one", $condition1);
+ $composite->addFilter("two", $condition2);
+ $composite->addFilter("three", $condition3);
+ $composite->addFilter("four", $condition4, FilterComposite::CONDITION_AND);
+ $composite->addFilter("five", $condition5, FilterComposite::CONDITION_AND);
+
+ // This is what's happening internally
+ if (
+ (
+ $condition1
+ || $condition2
+ || $condition3
+ ) && (
+ $condition4
+ && $condition5
+ )
+ ) {
@Maks3w Collaborator
Maks3w added a note

According CS guidelines close brace and open curl must share the same line

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ //do extraction
+ }
+
+If you've only one condition (only ``and`` or ``or``) block, the other one will be completely ignored.
+
+A bit more complex filter can look like this:
+
+.. code-block:: php
+ :linenos:
+
+ $composite = new FilterComposite();
+ $composite->addFilter(
+ "servicemanager",
+ new MethodMatchFilter("getServiceManager"),
+ FilterComposite::CONDITION_AND
+ );
+ $composite->addFilter(
+ "eventmanager",
+ new MethodMatchFilter("getEventManager"),
+ FilterComposite::CONDITION_AND
+ );
+
+ $hydrator->addFilter("excludes", $composite, FilterComposite::CONDITION_AND);
+
+ // Internal
+ if (
+ ( // default composite inside the hydrator
+ (
+ $getFilter
+ || $hasFilter
+ || $isFilter
+ ) && (
+ $numberOfParamterFilter
+ )
+ ) && ( // new composite, added to the one above
+ $serviceManagerFilter
+ && $eventManagerFilter
+ )
+ ) {
+ // do extraction
+ }
+
+If you perform this on the ``ClassMethods`` hydrator, all getters will get extracted, but not ``getServiceManager``
+and ``getEventManager``.
+
+.. _zend.stdlib.hydrator.filter.provider:
+
+Using the provider interface
+----------------------------
+
+There is also a provider interface, that allows you to configure the behavior of the hydrator inside your objects.
+
+.. code-block:: php
+ :linenos:
+
+ namespace Zend\Stdlib\Hydrator\Filter;
+
+ interface FilterProviderInterface
+ {
+ /**
+ * Provides a filter for hydration
+ *
+ * @return FilterInterface
+ */
+ public function getFilter();
+ }
+
+The ``getFilter()`` method is getting automatically excluded from ``extract()``. If the extracted object implements the
+``Zend\Stdlib\Hydrator\Filter\FilterProviderInterface``, the returned ``FilterInterface`` instance can also be a
+``FilterComposite``.
+
+For example:
+
+.. code-block:: php
+ :linenos:
+
+ Class Foo implements FilterProviderInterface
+ {
+ public function getFoo()
+ {
+ return "foo";
+ }
+
+ public function hasFoo()
+ {
+ return true;
+ }
+
+ public function getServiceManager()
+ {
+ return "servicemanager";
+ }
+
+ public function getEventManager()
+ {
+ return "eventmanager";
+ }
+
+ public function getFilter()
+ {
+ $composite = new FilterComposite();
+ $composite->addFilter("get", new GetFilter());
+
+ $exclusionComposite = new FilterComposite();
+ $exclusionComposite->addFilter(
+ "servicemanager",
+ new MethodMatchFilter("getServiceManager"),
+ FilterComposite::CONDITION_AND
+ );
+ $exclusionComposite->addFilter(
+ "eventmanager",
+ new MethodMatchFilter("getEventManager"),
+ FilterComposite::CONDITION_AND
+ );
+
+ $composite->addFilter("excludes", $exclusionComposite. FilterComposite::CONDITION_AND);
+
+ return $composite;
+ }
+ }
+
+ $hydrator = new ClassMethods(false);
+ $extractedArray = $hydrator->extract(new Foo());
+
+The ``$extractedArray`` does only have "foo" => "foo" in. All of the others are excluded from the extraction.
+
+.. note::
+
+ All pre-registered filters from the ``ClassMethods`` hydrator are ignored if this interface is used.
Something went wrong with that request. Please try again.