README

README.md

@@ -3,8 +3,8 @@
 [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/krzysztof-magosa/saffron-php/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/krzysztof-magosa/saffron-php/?branch=master)
 [![Coverage Status](https://img.shields.io/coveralls/krzysztof-magosa/saffron-php.svg)](https://coveralls.io/r/krzysztof-magosa/saffron-php?branch=master)
 
-Router made with high performance in mind.  
-Free for personal and commercial usage.
+Router made with high performance in mind.
+Apache 2.0 licensed.
 
 ## Features
 * No dependencies
@@ -19,27 +19,88 @@ You can easily install Saffron by adding below requirement to your composer.json
 ```json
 {
     "require": {
-        "krzysztof-magosa/saffron": "4.*"
+        "krzysztof-magosa/saffron": "5.*"
     }
 }
 ```
 
-## Performance
-<pre>
-  Saffron (c)  4.23 k/s ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
-Saffron (e+c)  3.53 k/s ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
-      Saffron  2.04 k/s ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
-  Saffron (e)  1.80 k/s ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
-</pre>
+## Usage
+Please follow to [example](https://github.com/krzysztof-magosa/saffron-php/tree/master/example)
+to see how simply you can use the Saffron in your project :-)
 
-* c - router uses "precompilation" (var_export) of objects to speed up start
-* e - router executes Controller or provided Closure
-* no letter - router just returns matched route
+## Setting routes
 
-Benchmark performed on OS X Yosemite, CPU i5 2.6GHz, PHP 5.6.1, in CLI.  
-There were 10 regex routes, last one was triggered.  
-Performed on Saffron 4.2.0.
+### Matching request against uri (path)
+#### Static uri
+```php
+$route->setUri('/');
+$route->setUri('/contact-us');
+```
 
-## Usage
-Please follow to [example](https://github.com/krzysztof-magosa/saffron-php/tree/master/example) 
-to see how simply you can use the Saffron in your project :-)
+#### Dynamic uri
+```php
+$route->setUri('/contact-with/{name}');
+$route->setUri('/contact-with/{name}/by/{method}');
+```
+
+### Matching request against domain
+#### Static domain
+```php
+$route->setDomain('www.example.com');
+```
+
+#### Dynamic domain
+```php
+$route->setDomain('www.example.{tld}');
+```
+
+### Matching request against http method
+```php
+$route->setMethod('GET');
+$route->setMethod(['GET', 'POST']);
+```
+
+### Matching request against https
+
+```php
+// Allow only https traffic
+$route->setHttps(true);
+
+// Allow only non-https traffic
+$route->setHttps(false);
+
+// Https doesn't matter (default setting)
+$route->setHttps(null);
+```
+
+### Setting possible values for placeholders
+If you want to allow only some values to be passed to placeholders, you can restrict their values using regular expressions.
+Saffron uses PERL compatible expressions (like in preg_match). All requirements are enclosed by ^ and $ internally by Saffron.
+```php
+$route->setRequirements(
+    [
+        'name' => '\w+',
+        'method' => 'phone|email',
+        'tld' => 'com|org',
+    ]
+);
+```
+
+### Setting default values for placeholders
+If you want some placeholder to be optional, you can set default value for it.
+It makes sense only for one or more placeholders on the end of uri, or one of more on the beggining of domain.
+```php
+$route->setDefaults(
+    [
+        'placeholder1' => 'value1',
+    ]
+);
+```
+
+### Setting controller to be fired by Executor
+To run controller (using Executor) when route is matched you can set class and method in it.
+When you omit method it takes default value 'indexAction'
+```php
+$route->setTarget('HomeController');
+$route->setTarget('ContactController', 'emailAction');
+```