Added hydrator filter doc #595

Merged
merged 3 commits into from Jan 15, 2013

Projects

None yet

2 participants

Contributor
iwalz commented Jan 12, 2013

This doc is related to zendframework/zendframework#3359

@Maks3w Maks3w commented on an outdated diff Jan 15, 2013
.../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
Maks3w Jan 15, 2013 Member

Typo s/behaviour/behavior

@Maks3w Maks3w commented on an outdated diff Jan 15, 2013
.../languages/en/modules/zend.stdlib.hydrator.filter.rst
+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
Maks3w Jan 15, 2013 Member

Abnormal redaction "that has methods will"

Maks3w
Maks3w Jan 15, 2013 Member

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

@Maks3w Maks3w commented on an outdated diff Jan 15, 2013
.../languages/en/modules/zend.stdlib.hydrator.filter.rst
+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
Maks3w Jan 15, 2013 Member

Abnormal redaction "that is methods will"

Maks3w
Maks3w Jan 15, 2013 Member

same not as above

@Maks3w Maks3w commented on an outdated diff Jan 15, 2013
.../languages/en/modules/zend.stdlib.hydrator.filter.rst
+ 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
Maks3w Jan 15, 2013 Member

Typo s/Eiter/Either

@Maks3w Maks3w commented on an outdated diff Jan 15, 2013
.../languages/en/modules/zend.stdlib.hydrator.filter.rst
+
+- **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
Maks3w Jan 15, 2013 Member

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

@Maks3w Maks3w commented on an outdated diff Jan 15, 2013
.../languages/en/modules/zend.stdlib.hydrator.filter.rst
+- **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
Maks3w Jan 15, 2013 Member

Typo s/wheter/whether

@Maks3w Maks3w commented on an outdated diff Jan 15, 2013
.../languages/en/modules/zend.stdlib.hydrator.filter.rst
+- **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
Maks3w Jan 15, 2013 Member

Abnormal redaction is methods

@Maks3w Maks3w commented on an outdated diff Jan 15, 2013
.../languages/en/modules/zend.stdlib.hydrator.filter.rst
+
+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
Maks3w Jan 15, 2013 Member

Typo s/compisite/composite

@Maks3w Maks3w commented on an outdated diff Jan 15, 2013
.../languages/en/modules/zend.stdlib.hydrator.filter.rst
+.. _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
Maks3w Jan 15, 2013 Member

Please surround true with ` character

@Maks3w Maks3w commented on the diff Jan 15, 2013
.../languages/en/modules/zend.stdlib.hydrator.filter.rst
+ $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
Maks3w Jan 15, 2013 Member

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

@Maks3w Maks3w commented on an outdated diff Jan 15, 2013
.../languages/en/modules/zend.stdlib.hydrator.filter.rst
+ // 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
Maks3w Jan 15, 2013 Member

missing space after )

@Maks3w Maks3w commented on an outdated diff Jan 15, 2013
.../languages/en/modules/zend.stdlib.hydrator.filter.rst
+
+ // Internal
+ if (
+ ( // default composite inside the hydrator
+ (
+ $getFilter
+ || $hasFilter
+ || $isFilter
+ ) && (
+ $numberOfParamterFilter
+ )
+ ) && ( // new composite, added to the one above
+ $serviceManagerFilter
+ && $eventManagerFilter
+ )
+ )
Maks3w
Maks3w Jan 15, 2013 Member

same CS rule

@Maks3w Maks3w commented on an outdated diff Jan 15, 2013
.../languages/en/modules/zend.stdlib.hydrator.filter.rst
+ && $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
Maks3w Jan 15, 2013 Member

s/behaviour/behavior

Member
Maks3w commented Jan 15, 2013

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.

Contributor
iwalz commented Jan 15, 2013

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

@Maks3w Maks3w merged commit a39f23a into zendframework:develop Jan 15, 2013
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment