Improved the documentation and moved it to coucous.io

.gitattributes

@@ -0,0 +1,8 @@
+/docs               export-ignore
+/tests              export-ignore
+/.gitattributes     export-ignore
+/.gitignore         export-ignore
+/.scrutinizer.yml   export-ignore
+/.travis.yml        export-ignore
+/couscous.yml       export-ignore
+/index.md           export-ignore

.gitignore

@@ -1,9 +1,7 @@
-INSTALL.txt
-LICENSE.txt
-README.txt
-tests/report
 build
 /.settings
 /.buildpath
 /.project
 .idea/
+docs/.couscous
+docs/couscous.phar

README.md

@@ -1,10 +1,11 @@
 #Sirius\Filtration
 
-[![Build Status](https://travis-ci.org/siriusphp/filtration.png?branch=master)](https://travis-ci.org/siriusphp/filtration)
-[![Coverage Status](https://coveralls.io/repos/siriusphp/filtration/badge.png)](https://coveralls.io/r/siriusphp/filtration)
-[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/siriusphp/filtration/badges/quality-score.png?s=1897aacdd8313df10089c5307b336c0fde8624db)](https://scrutinizer-ci.com/g/siriusphp/filtration/)
-[![Latest Stable Version](https://poser.pugx.org/siriusphp/filtration/version.png)](https://packagist.org/packages/siriusphp/filtration)
-[![License](https://poser.pugx.org/siriusphp/filtration/license.png)](https://packagist.org/packages/siriusphp/filtration)
+[![Source Code](http://img.shields.io/badge/source-siriusphp/filtration-blue.svg?style=flat-square)](https://github.com/siriusphp/filtration)
+[![Latest Version](https://img.shields.io/packagist/v/siriusphp/filtration.svg?style=flat-square)](https://github.com/siriusphp/filtration/releases)
+[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](https://github.com/siriusphp/filtration/blob/master/LICENSE)
+[![Build Status](https://img.shields.io/travis/siriusphp/filtration/master.svg?style=flat-square)](https://travis-ci.org/siriusphp/filtration)
+[![Coverage Status](https://img.shields.io/scrutinizer/coverage/g/siriusphp/filtration.svg?style=flat-square)](https://scrutinizer-ci.com/g/siriusphp/filtration/code-structure)
+[![Quality Score](https://img.shields.io/scrutinizer/g/siriusphp/filtration.svg?style=flat-square)](https://scrutinizer-ci.com/g/siriusphp/filtration)
 
 PHP library for array filtering/sanitization
 
@@ -55,13 +56,8 @@ array(
 */
 ```
 
-##Why (just) arrays?
 
-Arrays are easily exchangeable between components. User input (POST or GET) is an array, an object may be populated from an array, database query row can be an array, JSON data is passed from the client and gets to the server as an array. 
+##Links
 
-##Documentation
-
-- [general usage of the library](docs/index.md)
-- [built-in filters](docs/filters.md)
-- [using SiriusFiltration with models](docs/modeling.md)
-- [other usages for SiriusFiltration](docs/other.md)
+- [documentation](http://www.sirius.ro/php/sirius/validation/)
+- [changelog](CHANGELOG.md)

docs/couscous.yml

@@ -0,0 +1,71 @@
+template:
+    url: https://github.com/siriusphp/Template-ReadTheDocs
+
+# List of directories to exclude from the processing (default contains "vendor" and "website")
+# Paths are relative to the repository root
+exclude:
+    - website
+    - vendor
+    - test
+    - src
+    - build
+
+# Base URL of the published website (no "/" at the end!)
+# You are advised to set and use this variable to write your links in the HTML layouts
+baseUrl: http://www.sirius.ro/php/sirius/filtration
+
+projectName: Sirius\Filtration
+title: Sirius\Filtration
+subTitle: Framework agnostic data filtering library
+
+# The left menu bar
+menu:
+    sections:
+#        versions:
+#            name: Versions
+#            items:
+#                two:
+#                    text: "2.0"
+#                    relativeUrl:
+#                one:
+#                    text: "1.0"
+#                    relativeUrl: 1_0/
+        guide:
+            name: Getting started
+            items:
+                getting_started:
+                    text: Introduction
+                    relativeUrl:
+                installation:
+                    text: Installation
+                    relativeUrl: installation.html
+                simple_example:
+                    text: Simple example
+                    relativeUrl: simple_example.html
+                filters:
+                    text: Built-in filters
+                    relativeUrl: filters.html
+                syntactic_sugar:
+                    text: Syntactic sugar
+                    relativeUrl: syntactic_sugar.html
+        advanced:
+            name: Advanced topics
+            items:
+                special_selectors:
+                    text: Special selectors
+                    relativeUrl: special_selectors.html
+                custom_filter:
+                    text: Custom filters
+                    relativeUrl: custom_filters.html
+                filter_factory:
+                    text: The filter factory
+                    relativeUrl: filter_factory.html
+        cookbook:
+            name: Cookbook
+            items:
+                modeling:
+                    text: Filtration for models
+                    relativeUrl: model_filtration.html
+                outputing:
+                    text: Filtration for output
+                    relativeUrl: output_filtration.html

docs/custom_filters.md

@@ -0,0 +1,43 @@
+---
+title: Custom filters
+---
+
+# Custom filters
+
+Hopefully your app is complex enough to require you to build custom filters. Or you will find many uses for this library that you will have to build custom filters.
+
+Below is the code for a filter that adds a sequence of underscores in front of every item that is passed to it **if** the 'append_underscores' element from the context is true
+
+```php
+namespace MyApp\Filtration\Filter;
+
+class AppendUnderscores extends Sirius\Filtration\Filter\AbstractFilter {
+
+    function filterSingle($value, $valueIdentifier = null) {
+        // the context is passed to each filter and represents the entire dataset 
+        // that was sent to be filtered 
+        $no_of_underscores = (int) $this->context['append_underscores']
+        return str_repeat('_', $no_of_underscores) . $value;
+    }
+
+}
+```
+
+And it is used like so
+
+```php
+use Sirius\Filtration\Filtrator;
+$filtrator = new Filtrator();
+$filtrator->add('content', 'MyApp\Filtration\Filter\AppendUnderscores');
+
+$result = $filtrator->filter(array(
+    'append_underscores' => 10,
+    'content' => 'Pretty stupid, right?'
+));
+
+// $result will be
+// array(
+//    'append_underscores' => 10,
+//    'content' => '_________Pretty stupid, right?'
+// )
+```

docs/filter_factory.md

@@ -0,0 +1,55 @@
+---
+title: The filter factory
+---
+
+# The filter factory
+
+Each filtrator object uses individuals filters which are constructed by a `FilterFactory`. The filtrator depends on the filter factory but if you don't provide it, one will be constructed for your
+
+```php
+use Sirius\Filtration\Filtrator;
+use Sirius\Filtration\FilterFactory;
+
+$filterFactory = new FilterFactory();
+$filtrator = new Filtrator($filterFactory);
+```
+
+You can register your custom filters within the `FilterFactory` like so:
+
+```php
+$filterFactory->register('my_filter', 'MyApp\Filtration\Filter\MyFilter');
+```
+
+If you use dependency injection (and you should) you can have a single filter factory for your entire application and register all the filters you need at the beginning of the app.
+
+If you don't want to do that you can always pass the class to the filtrator:
+
+```php
+$filtrator->add('content', 'MyApp\Filtration\Filter\MyFilter');
+```
+
+Also, if your filters are very complex, that is they have dependencies) you need to extend the filter factory.
+
+```php
+namespace MyApp\Filtration;
+
+class FilterFactory extends Sirius\Filtration\FilterFactory {
+
+    $protected $container = $container;
+
+    function __construct(Container $container) {
+        $this->container = $container;
+    }
+
+    function createFilter($callbackOrFilterName, $options = null, $resursive = false) {
+        $filter = $this->container->get($callbackOrFilterName, [$options, $recursive]);
+        if (!$filter) {
+            $filter = parent::createFilter($callbackOrFilterName, $options, $resursive)
+        }
+        return $filter;
+    }
+
+}
+```
+
+Or something to that extent.

docs/filters.md

@@ -6,35 +6,35 @@ Allows using any function, closure or callback for filtering data. The callback
 
 Options:
 
-- callback: the function/closure/callback that will be used as filter
-- arguments: additional arguments for the callback
+- `callback`: the function/closure/callback that will be used as filter
+- `arguments`: additional arguments for the callback
 
 ## Censor
 
 Obfuscates certain words from a string
 
 Options:
 
-- start_characters: leaves untouched this number of characters from the begining of the filtered string. Default: 1
-- start_characters: leaves untouched this number of characters from the end of the filtered string. Default: 1
-- replacement_char: the character that will be used to replace the hidden chars. Default: *
-- word: list of words that are censored. Default: look in the source file
+- `start_characters`: leaves untouched this number of characters from the begining of the filtered string. Default: 1
+- `start_characters`: leaves untouched this number of characters from the end of the filtered string. Default: 1
+- `replacement_char`: the character that will be used to replace the hidden chars. Default: *
+- `word`: list of words that are censored. Default: look in the source file
 
 ## CleanArray
 
 Removes null elements from an array. If the array is associative it preserves the keys.
 
 Options:
 
-- nullify: whether to use the Nullify filter to convert certain values into NULLs. Default: TRUE
+- `nullify`: whether to use the Nullify filter to convert certain values into NULLs. Default: TRUE
 
 ## Double
 
 Convert numbers to `double` using a specified precision
 
 Options:
 
-- precision: number of digits that the filtered value will have. Default: 2
+- `precision`: number of digits that the filtered value will have. Default: 2
 
 ## Integer
 
@@ -47,8 +47,8 @@ Example: `12/10/2012` to `2012-12-10`
 
 Options:
 
-- input_format: the date format in which the value should have been provided. Default: `d/m/Y`
-- output_format: the format in which the value is returned. Default: `Y-m-d`
+- `input_format`: the date format in which the value should have been provided. Default: `d/m/Y`
+- `output_format`: the format in which the value is returned. Default: `Y-m-d`
 
 ## NormalizeNumber
 
@@ -57,43 +57,43 @@ Example: `1 234,5` to `1234.5`
 
 Options:
 
-- thousands_separator. Default: `.`
-- decimal_point. Default: `,`
+- `thousands_separator`. Default: `.`
+- `decimal_point`. Default: `,`
 
 ## Nullify
 
 Converts certain values to NULL
 
 Options:
 
-- empty_string: converts empty strings to NULL. Default: TRUE
-- zero: converts zero numbers to NULL. Default: TRUE
+- `empty_string`: converts empty strings to NULL. Default: TRUE
+- `zero`: converts zero numbers to NULL. Default: TRUE
 
 ## Obfuscate
 
 Hides certain characters from a string
 
 Options:
 
-- start_characters: leaves untouched this number of characters from the begining of the filtered string. Default: 0
-- start_characters: leaves untouched this number of characters from the end of the filtered string. Default: 0
-- replacement_char: the character that will be used to replace the hidden chars. Default: *
+- `start_characters`: leaves untouched this number of characters from the begining of the filtered string. Default: 0
+- `start_characters`: leaves untouched this number of characters from the end of the filtered string. Default: 0
+- `replacement_char`: the character that will be used to replace the hidden chars. Default: *
 
 ## StringTrim
 
-Removes whitespace at the begining and/or end of strings:
+Removes whitespace at the beginning and/or end of strings:
 
 Options:
 
-- side: where the string will be trimmed. Possible values: `left`|`right`|`both`. Default: `both`.
-- characters: list of characters that will be trimmed. Default: `\t\n\r `
+- `side`: where the string will be trimmed. Possible values: `left`|`right`|`both`. Default: `both`.
+- `characters`: list of characters that will be trimmed. Default: `\t\n\r `
 
 ## Truncate
 
 Truncates a string to a maximum number of characters
 
 Options:
 
-- limit: max limit of the returned string. Default: FALSE.
-- break_words: whether or not breaking a word is a allowed: Default: TRUE
-- ellipsis: character added at the end when the string is truncated. Default: ...
+- `limit`: max limit of the returned string. Default: FALSE.
+- `break_words`: whether or not breaking a word is a allowed: Default: TRUE
+- `ellipsis`: character added at the end when the string is truncated. Default: ...