Split out FilterProviderTrait from FilterEnabledTrait

Separates out the `FilterProviderInterface` implementation from
`FilterEnabledTrait`, creating a new trait, `FilterProviderTrait`.
`FilterEnabledTrait` now uses that internally.

docs/book/v3/filter.md

@@ -179,47 +179,47 @@ For example:
 ```php
 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;
-     }
+    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);
@@ -234,6 +234,30 @@ excluded from extraction.
 > All pre-registered filters from the `ClassMethods` hydrator are ignored when
 > this interface is used. More on those methods below.
 
+### FilterProviderTrait
+
+We provide `Zend\Hydrator\Filter\FilterProviderTrait` as a default
+implementation of `FilterProviderInterface`. It lazy-loads a `FilterComposite`
+instance and returns it. This allows you to define filters in your constructor,
+or to allow others to define composite filters for specific instances:
+
+```php
+// Within a constructor:
+$this->getFilter()->addFilter(
+    'servicemanager',
+    new MethodMatchFilter('getServiceManager'),
+    FilterComposite::CONDITION_AND
+);
+
+// By a consumer:
+$hydrator = new SomeFilterEnabledHydrator();
+$hydrator->getFilter()->addFilter(
+    'servicemanager',
+    new MethodMatchFilter('getServiceManager'),
+    FilterComposite::CONDITION_AND
+);
+```
+
 ## Filter-enabled hydrators and the composite filter
 
 Hydrators can indicate they are filter-enabled by implementing

src/Filter/FilterEnabledTrait.php

@@ -14,16 +14,9 @@
  */
 trait FilterEnabledTrait
 {
-    /**
-     * Composite filter for the purpose of determining if a property should be
-     * extracted or hydrated. A FilterComposite is specified to allow the
-     * ability to compose many filters, allowing each to inspect specific
-     * properties or to aggregate multiple criteria when determining if a
-     * property can be addressed.
-     *
-     * @var FilterComposite
-     */
-    protected $filterComposite;
+    // FilterEnabledInterface extends FilterProviderInterface; we will use
+    // the FilterProviderTrait to implement that part of the interface.
+    use FilterProviderTrait;
 
     /**
      * Add a new filter to take care of what needs to be hydrated.
@@ -75,18 +68,4 @@ public function removeFilter(string $name) : void
         $this->getFilter();
         $this->filterComposite->removeFilter($name);
     }
-
-    /**
-     * Get the filter instance
-     *
-     * @return FilterComposite
-     */
-    public function getFilter() : FilterInterface
-    {
-        if (! isset($this->filterComposite)) {
-            $this->filterComposite = new FilterComposite();
-        }
-
-        return $this->filterComposite;
-    }
 }

src/Filter/FilterProviderTrait.php

@@ -0,0 +1,41 @@
+<?php
+/**
+ * @see       https://github.com/zendframework/zend-hydrator for the canonical source repository
+ * @copyright Copyright (c) 2018 Zend Technologies USA Inc. (https://www.zend.com)
+ * @license   https://github.com/zendframework/zend-hydrator/blob/master/LICENSE.md New BSD License
+ */
+
+declare(strict_types=1);
+
+namespace Zend\Hydrator\Filter;
+
+/**
+ * Provides a default implementation of FilterProviderInterface.
+ */
+trait FilterProviderTrait
+{
+    /**
+     * Composite filter for the purpose of determining if a property should be
+     * extracted or hydrated. A FilterComposite is specified to allow the
+     * ability to compose many filters, allowing each to inspect specific
+     * properties or to aggregate multiple criteria when determining if a
+     * property can be addressed.
+     *
+     * @var FilterComposite
+     */
+    protected $filterComposite;
+
+    /**
+     * Get the filter instance
+     *
+     * @return FilterComposite
+     */
+    public function getFilter() : FilterInterface
+    {
+        if (! isset($this->filterComposite)) {
+            $this->filterComposite = new FilterComposite();
+        }
+
+        return $this->filterComposite;
+    }
+}