Add documentation on multibyte encoding

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.

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.

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]