Add the ability to pass in configuration to a given filter

This enables us to do interesting things, such as modifying a filter at runtime to whitelist keys from modification etc.

Author: josegonzalez

README.markdown

@@ -213,7 +213,14 @@ It is possible to optionally filter the environment data produced by php-dotenv
 <?php
 class LollipopFilter
 {
-    public function __invoke(array $environment)
+    /**
+     * Sets every key's value to the string `lollipop`
+     *
+     * @param array $environment Array of environment data
+     * @param array $config Array of configuration data that includes the callable
+     * @return array
+     */
+    public function __invoke(array $environment, array $config)
     {
         $newEnvironment = [];
         foreach ($environment as $key => $value) {
@@ -234,7 +241,18 @@ $Loader = (new josegonzalez\Dotenv\Loader('path/to/.env'))
 ?>
 ```
 
-Filters can also be callables functions, which is useful in one-off situations:
+Note that you can optionally set configuration for your filters. These are passed to the `__invoke` method as the second argument.:
+
+```php
+<?php
+$Loader = (new josegonzalez\Dotenv\Loader('path/to/.env'))
+              ->setFilters([
+                'LollipopFilter' => ['paintshop'],
+              ]); // Takes an array of namespaced class names
+?>
+```
+
+Filters can also be callables functions, which is useful in one-off situations. They are wrapped by the special `CallableFilter`.
 
 ```php
 <?php
@@ -245,6 +263,22 @@ $Loader = (new josegonzalez\Dotenv\Loader('path/to/.env'))
 ?>
 ```
 
+If you need special configuration for your callable filters, you can prefix your callable with `__callable__N`, where `N` is the integer index the callable is in your array. The callable itself should be contained in a `callable` config key, as follows:
+
+```php
+<?php
+$Loader = (new josegonzalez\Dotenv\Loader('path/to/.env'))
+              ->setFilters([
+                '__callable__0' => [
+                  'callable' => function ($data, $config) {
+                    return $data;
+                  },
+                  'someKey' => 'value',
+                ]
+              ]);
+?>
+```
+
 Finally, to invoke a filter, you must call `filter()` after calling `parse()`.
 
 ```php
@@ -260,6 +294,7 @@ $Loader = (new josegonzalez\Dotenv\Loader('path/to/.env'))
 
 The following filters are built into php-dotenv.
 
+- `josegonzalez\Dotenv\Filter\CallableFilter`: Wraps a callable and invokes it upon the environment.
 - `josegonzalez\Dotenv\Filter\LowercaseKeyFilter`: Lowercases all the keys for an environment to a single-depth.
 - `josegonzalez\Dotenv\Filter\NullFilter`: Returns the environment data without any changes.
 - `josegonzalez\Dotenv\Filter\UnderscoreArrayFilter`: Expands a flat array to a nested array. For example, `['0_Foo_Bar' => 'Far']` becomes `[['Foo' => ['Bar' => 'Far']]]`.

src/josegonzalez/Dotenv/Filter/CallableFilter.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace josegonzalez\Dotenv\Filter;
+
+class CallableFilter
+{
+    /**
+     * Wraps a callable and invokes it upon the environment.
+     *
+     * @param array $environment Array of environment data
+     * @param array $config Array of configuration data that includes the callable
+     * @return array
+     */
+    public function __invoke(array $environment, array $config)
+    {
+        $callable = $config['callable'];
+        return $callable($environment, $config);
+    }
+}

src/josegonzalez/Dotenv/Loader.php

@@ -4,6 +4,7 @@
 
 use InvalidArgumentException;
 use josegonzalez\Dotenv\Expect;
+use josegonzalez\Dotenv\Filter\CallableFilter;
 use josegonzalez\Dotenv\Parser;
 use LogicException;
 
@@ -114,26 +115,46 @@ public function filters()
 
     public function setFilters(array $filters)
     {
-        $this->filters = $filters;
-        foreach ($this->filters as $filterClass) {
-            if (is_string($filterClass)) {
-                if (is_callable($filterClass)) {
-                    continue;
-                }
-                if (!class_exists($filterClass)) {
-                    return $this->raise(
-                        'LogicException',
-                        sprintf('Invalid filter class %s', $filterClass)
+        $newList = array();
+        $keys = array_keys($filters);
+        $count = count($keys);
+        for ($i = 0; $i < $count; $i++) {
+            if (is_int($keys[$i])) {
+                $filter = $filters[$keys[$i]];
+                if (is_string($filter)) {
+                    $newList[$filter] = null;
+                } else {
+                    $newList['__callable__' . $i] = array(
+                        'callable' => $filter
                     );
                 }
-                continue;
+            } else {
+                $newList[$keys[$i]] = $filters[$keys[$i]];
             }
-            if (!is_callable($filterClass)) {
+        }
+
+        $this->filters = $newList;
+
+        foreach ($this->filters as $filterClass => $config) {
+            if (substr($filterClass, 0, 12) === '__callable__') {
+                if (is_callable($config['callable'])) {
+                    continue;
+                }
                 return $this->raise(
                     'LogicException',
                     sprintf('Invalid filter class')
                 );
             }
+            if (is_callable($filterClass)) {
+                continue;
+            }
+            if (!class_exists($filterClass)) {
+                return $this->raise(
+                    'LogicException',
+                    sprintf('Invalid filter class %s', $filterClass)
+                );
+            }
+            continue;
         }
         return $this;
     }
@@ -143,14 +164,17 @@ public function filter()
         $this->requireParse('filter');
 
         $environment = $this->environment;
-        foreach ($this->filters as $filterClass) {
+        foreach ($this->filters as $filterClass => $config) {
             $filter = $filterClass;
             if (is_string($filterClass)) {
+                if (substr($filterClass, 0, 12) === '__callable__') {
+                    $filter = new CallableFilter;
+                }
                 if (class_exists($filterClass)) {
                     $filter = new $filterClass;
                 }
             }
-            $environment = $filter($environment);
+            $environment = $filter($environment, $config);
         }
 
         $this->environment = $environment;

tests/josegonzalez/Dotenv/LoaderTest.php

@@ -221,6 +221,16 @@ public function testSetFilters()
         $this->assertEquals($this->Loader, $this->Loader->setFilters(array(
             'josegonzalez\Dotenv\doNothing',
         )));
+
+        $this->assertEquals($this->Loader, $this->Loader->setFilters(array(
+            'josegonzalez\Dotenv\doNothing' => array('key' => 'value'),
+        )));
+
+        $this->assertEquals($this->Loader, $this->Loader->setFilters(array(
+            function () {
+                return array();
+            }
+        )));
     }
 
     /**
@@ -269,17 +279,18 @@ public function testFilter()
 
     /**
      * @covers \josegonzalez\Dotenv\Loader::filter
+     * @covers \josegonzalez\Dotenv\Filter\CallableFilter::__invoke
      */
     public function testFilterCallable()
     {
         $this->assertEquals($this->Loader, $this->Loader->setFilters(array(
             function () {
-                return array();
+                return array('FOO' => 'BAR');
             }
         )));
         $this->Loader->parse();
         $this->Loader->filter();
-        $this->assertEquals(array(), $this->Loader->toArray());
+        $this->assertEquals(array('FOO' => 'BAR'), $this->Loader->toArray());
     }
 
     /**