Merge pull request #28 from RickvdStaaij/feature/multibyte-support

Feature: Add Multibyte support
particle-php · Jun 26, 2015 · 93f089b · 93f089b
2 parents df11066 + 483d133
commit 93f089b
Show file tree

Hide file tree

Showing 29 changed files with 313 additions and 61 deletions.
diff --git a/docs/filter-rules.md b/docs/filter-rules.md
@@ -7,6 +7,7 @@ filters, take a look at the callback filter-rule, or check out "Extending the Fi
 * [append](#append)
 * [bool](#bool)
 * [callback](#callback)
+* [encode](#encode)
 * [float](#float)
 * [int](#int)
 * [letters](#letters)
@@ -68,6 +69,20 @@ $result = $f->filter(['name' => 'John']);
 // array(1) { ["name"]=> string(21) "<strong>John</strong>"
 ```
 
+## Encode
+
+Makes sure that the given value is in a specific encoding format.
+
+```php
+$f = new Filter;
+$f->value('text')->encode('Base64', 'UTF-8');
+$result = $f->filter(['text' => 'hello']);
+// array(1) { ["text"]=> string(8) "aGVsbG8="
+```
+
+if `$f->setEncodingFormat()` is set, you don't need to provide any parameters as the value encoding format will
+be set to that.
+
 ## Float
 
 Make sure the value is a float.

diff --git a/docs/multibyte-encoding.md b/docs/multibyte-encoding.md
@@ -0,0 +1,35 @@
+# Multibyte encoding
+
+To make sure your values get filtered correctly, we have to use the multi-byte (`mb_`) functionality from PHP. With
+this feature comes the ability to set the encoding format on the filter.
+
+```php
+$filter = new Particle\Filter\Filter;
+
+$filter->setEncodingFormat('utf-8'); // or another format if you like
+```
+
+If you don't use the function above, the string adaptive functions from php will use the default value from your
+php.ini, which is most likely UTF-8.
+
+**Note:** Make sure that you set the encoding format on before you add any filter rules to the filter, otherwise the
+default encoding format will be used on the filter rules defined before that setEncodingFormat.
+
+### Converting values to a specific encoding format
+
+If you know data is coming in in a different encoding format than what you want to be working with, you can use the
+encode filter rule to convert the value.
+
+```php
+$filter->value('first_name')->encode('UTF-8')->upper();
+```
+
+### Using multibyte a regex
+
+If you want to use multi-byte encoded regex, the following php functions should be used:
+
+```php
+mb_regex_encoding('UTF-8');
+```
+
+These functions are not included in Particle\Filter as it might lead to unexpected behaviour.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -6,3 +6,4 @@ pages:
 - [basic-usage.md, Basic usage]
 - [filter-rules.md, Filter-rules]
 - [extending.md, Extending the Filter]
+- [multibyte-encoding.md, Multibyte encoding]
diff --git a/src/Chain.php b/src/Chain.php
@@ -40,10 +40,13 @@ public function filter($value)
      * Add a new rule to the chain
      *
      * @param FilterRule $rule
+     * @param string|null $encodingFormat
      * @return $this
      */
-    public function addRule(FilterRule $rule)
+    public function addRule(FilterRule $rule, $encodingFormat)
     {
+        $rule->setEncodingFormat($encodingFormat);
+
         $this->rules[] = $rule;
 
         return $this;

diff --git a/src/Filter.php b/src/Filter.php
@@ -18,14 +18,19 @@
 class Filter
 {
     /**
-     * @var Chain[]
+     * @var array<string, Chain>
      */
     protected $chains = [];
 
     /**
      * @var Container
      */
-    protected $data = [];
+    protected $data;
+
+    /**
+     * @var string|null
+     */
+    protected $encodingFormat = null;
 
     /**
      * @var Chain
@@ -80,6 +85,18 @@ public function getFilterResource($keys = null)
         return new FilterResource($this, $keys);
     }
 
+    /**
+     * Set the encoding format for all string manipulating filter-rules.
+     * Note: You should set the encoding format before you add filter-rules to your filter, otherwise the
+     * encoding format would not be set on the values added before the encoding format was set.
+     *
+     * @param string $encodingFormat
+     */
+    public function setEncodingFormat($encodingFormat)
+    {
+        $this->encodingFormat = $encodingFormat;
+    }
+
     /**
      * Set a filter rule on a chain
      *
@@ -88,7 +105,7 @@ public function getFilterResource($keys = null)
      */
     public function addFilterRule(FilterRule $rule, $key = null)
     {
-        $this->getChain($key)->addRule($rule);
+        $this->getChain($key)->addRule($rule, $this->encodingFormat);
     }
 
     /**
@@ -121,7 +138,12 @@ protected function filterChains()
     {
         foreach ($this->chains as $key => $chain) {
             if ($this->data->has($key)) {
-                $this->data->set($key, $chain->filter($this->data->get($key)));
+                $this->data->set(
+                    $key,
+                    $chain->filter(
+                        $this->data->get($key)
+                    )
+                );
             }
         }
     }

diff --git a/src/FilterResource.php b/src/FilterResource.php
@@ -35,7 +35,7 @@ public function __construct(Filter $filter, $keys = null)
     }
 
     /**
-     * Add the alphabetic numeric rule to the chain
+     * Results rule that returns alphabetic numeric characters from the value
      *
      * @return $this
      */
@@ -45,7 +45,7 @@ public function alnum()
     }
 
     /**
-     * Add append filter-rule to the chain
+     * Results rule that returns the value appended with a given value
      *
      * @param string $append
      * @return Chain
@@ -56,7 +56,7 @@ public function append($append)
     }
 
     /**
-     * Add bool filter-rule to the chain
+     * Results rule that returns a casted boolean
      *
      * @return $this
      */
@@ -66,8 +66,9 @@ public function bool()
     }
 
     /**
-     * Add callback filter-rule to the chain
+     * Returns rule that returns a value modified by a callable closure
      *
+     * @param callable $callable
      * @return $this
      */
     public function callback(callable $callable)
@@ -76,7 +77,19 @@ public function callback(callable $callable)
     }
 
     /**
-     * Add float filter-rule to the chain
+     * Returns rule that returns an value in a specific encoding format
+     *
+     * @param string|null $toEncodingFormat
+     * @param string|null $fromEncodingFormat
+     * @return FilterResource
+     */
+    public function encode($toEncodingFormat = null, $fromEncodingFormat = null)
+    {
+        return $this->addRule(new FilterRule\Encode($toEncodingFormat, $fromEncodingFormat));
+    }
+
+    /**
+     * Returns rule that results a casted float
      *
      * @return $this
      */
@@ -86,7 +99,7 @@ public function float()
     }
 
     /**
-     * Add int filter-rule to the chain
+     * Returns rule that results a casted int
      *
      * @return $this
      */
@@ -96,7 +109,7 @@ public function int()
     }
 
     /**
-     * Add the letters-rule to the chain
+     * Returns rule that results all letters of a value
      *
      * @return $this
      */
@@ -106,7 +119,7 @@ public function letters()
     }
 
     /**
-     * Add lower filter-rule to the chain
+     * Returns rule that results a lower-cased value
      *
      * @return $this
      */
@@ -116,7 +129,7 @@ public function lower()
     }
 
     /**
-     * Add the numbers-rule to the chain
+     * Returns rule that results all numbers of a value
      *
      * @return $this
      */
@@ -126,7 +139,7 @@ public function numbers()
     }
 
     /**
-     * Add prepend filter-rule to the chain
+     * Results rule that returns the value prepended with a given value
      *
      * @param string $prepend
      * @return Chain
@@ -137,7 +150,7 @@ public function prepend($prepend)
     }
 
     /**
-     * Add replace filter-rule to the chain
+     * Results rule that returns a value with replacements by a regex
      *
      * @param string $searchRegex
      * @param string $replace
@@ -149,7 +162,7 @@ public function regexReplace($searchRegex, $replace)
     }
 
     /**
-     * Add replace filter-rule to the chain
+     * Results rule that returns a value with replacements
      *
      * @param mixed $search
      * @param mixed $replace
@@ -161,7 +174,7 @@ public function replace($search, $replace)
     }
 
     /**
-     * Add string filter-rule to the chain
+     * Returns rule that results a casted string
      *
      * @return $this
      */
@@ -171,7 +184,7 @@ public function string()
     }
 
     /**
-     * Add stripHtml filter-rule to the chain
+     * Results rule that results a html-stripped value
      *
      * @param null|string $excludeTags
      * @return $this
@@ -182,7 +195,7 @@ public function stripHtml($excludeTags = null)
     }
 
     /**
-     * Add trim filter-rule to the chain
+     * Returns rule that results a trimmed value
      *
      * @param string|null $characters
      * @return $this
@@ -193,7 +206,7 @@ public function trim($characters = null)
     }
 
     /**
-     * Add upper filter-rule to the chain
+     * Results rule that returns an upper-cased value
      *
      * @return $this
      */
@@ -203,7 +216,7 @@ public function upper()
     }
 
     /**
-     * Add upper-first filter-rule to the chain
+     * Returns rule that results a value starting with a upper-cased character
      *
      * @return $this
      */

diff --git a/src/FilterRule.php b/src/FilterRule.php
@@ -13,6 +13,19 @@
  */
 abstract class FilterRule
 {
+    /**
+     * @var string|null
+     */
+    protected $encodingFormat;
+
+    /**
+     * @param string|null $encodingFormat
+     */
+    public function setEncodingFormat($encodingFormat)
+    {
+        $this->encodingFormat = $encodingFormat;
+    }
+
     /**
      * @param mixed $value
      * @return mixed

diff --git a/src/FilterRule/Encode.php b/src/FilterRule/Encode.php
@@ -0,0 +1,62 @@
+<?php
+/**
+ * Particle.
+ *
+ * @link      http://github.com/particle-php for the canonical source repository
+ * @copyright Copyright (c) 2005-2015 Particle (http://particle-php.com)
+ * @license   https://github.com/particle-php/Filter/blob/master/LICENSE New BSD License
+ */
+namespace Particle\Filter\FilterRule;
+
+use Particle\Filter\FilterRule;
+
+/**
+ * Class Encode
+ *
+ * @package Particle\Filter\FilterRule
+ */
+class Encode extends FilterRule
+{
+    /**
+     * @var string
+     */
+    protected $toEncoding;
+
+    /**
+     * @var string|null
+     */
+    protected $fromEncoding;
+
+    /**
+     * @param string|null $toEncoding
+     * @param string|null $fromEncoding
+     */
+    public function __construct($toEncoding = null, $fromEncoding = null)
+    {
+        if ($toEncoding === null) {
+            $toEncoding = $this->encodingFormat;
+        }
+
+        $this->toEncoding = $toEncoding;
+        $this->fromEncoding = $fromEncoding;
+    }
+
+    /**
+     * Changes encoding of the value
+     *
+     * @param mixed $value
+     * @return string
+     */
+    public function filter($value)
+    {
+        if ($this->toEncoding === null) {
+            return $value;
+        }
+
+        if ($this->fromEncoding === null) {
+            return mb_convert_encoding($value, $this->toEncoding);
+        }
+
+        return mb_convert_encoding($value, $this->toEncoding, $this->fromEncoding);
+    }
+}