Added request bypassing section, updates configuration, request input data, routing, uploaded files section

Author: hollodotme

Contents/docs/icehawk/configuration.md

@@ -244,6 +244,70 @@ Please see our [routing section](@baseUrl@/docs/icehawk/routing.html) for more d
 
 <hr class="blockspace">
 
+## Configure request bypasses
+
+This example shows a simple request bypass:
+
+```php
+<?php declare(strict_types=1);
+
+namespace YourVendor\YourProject;
+
+use IceHawk\IceHawk\Interfaces\ConfiguresIceHawk;
+use IceHawk\IceHawk\Interfaces\RoutesToWriteHandler;
+use IceHawk\IceHawk\Routing\WriteRoute;
+use IceHawk\IceHawk\Routing\RequestBypass;
+use IceHawk\IceHawk\Constants\HttpMethod;
+use IceHawk\IceHawk\Routing\Patterns\Literal;
+use IceHawk\IceHawk\Routing\Patterns\RegExp;
+use IceHawk\IceHawk\Routing\Patterns\NamedRegExp;
+use IceHawk\IceHawk\Defaults;
+
+class IceHawkConfig implements ConfiguresIceHawk
+{
+	use Defaults\Traits\DefaultRequestProviding;
+	use Defaults\Traits\DefaultReadRouting;
+	use Defaults\Traits\DefaultEventSubscribing;
+	use Defaults\Traits\DefaultCookieProviding;
+	use Defaults\Traits\DefaultFinalReadResponding;
+	use Defaults\Traits\DefaultFinalWriteResponding;
+	
+	/**
+	 * @return array|\Traversable|BypassesRequest[]
+	 */
+	public function getRequestBypasses()
+	{
+		return [
+			new RequestBypass(
+				new Literal('/payment/success'), 
+				'/payment/mark-succeeded', 
+				HttpMethod::POST
+			),	
+		];
+	}
+	
+	/**
+	 * @return array|\Traversable|RoutesToWriteHandler[]
+	 */
+	public function getWriteRoutes()
+	{
+		return [
+			new WriteRoute( 
+				new Literal('/payment/mark-succeeded'), 
+				new MarkPaymentSucceededRequestHandler() 
+			),
+		];
+	}
+}
+```
+
+As you may noticed, we omitted the return type for this method, because we wanted to allow building a `\Generator` and `yield`ing the routes.
+In the next major release targeting PHP 7.1 we'll add the [iterable](https://github.com/php/php-src/pull/1941) return type.
+
+Please see our [request bypassing section](@baseUrl@/docs/icehawk/request-bypassing.html) for more details. 
+
+<hr class="blockspace">
+
 ## Configure event subscribers
 
 IceHawk publishes some events you can subscribe to. The following example shows how to register such event subscribers:

Contents/docs/icehawk/request-bypassing.md

@@ -0,0 +1,97 @@
+# Request bypassing
+ 
+One of IceHawk's main goals is to help you keep your application divided into a read and a write side. But when interacting with external systems, like e.g. 
+external payment providers, you probably be confronted with a situation where you receive a GET request that should trigger a write operation in your
+application. Since a GET request is bound to the read side this would go against the previous mentioned goal.
+ 
+In order to process such requests properly on the write side of your application the IceHawk component offers "request bypassing" to internally 
+re-route such a request (without HTTP redirection) to the write side of your application. 
+
+To make that behaviour a conscious decision a separate configuration is needed.
+   
+This section shows how to set up request bypassing.
+
+---
+
+## Configure a request bypass
+
+As you can see in the [configuration section](@baseUrl@/docs/icehawk/configuration.html) there is a method called `getRequestBypasses()`, which returns an empty array by default:
+
+```php
+/**
+ * @return array|\Traversable|BypassesRequest[]
+ */
+public function getRequestBypasses()
+{
+	return [];
+}
+```
+
+Assuming the following use-case:
+
+* Your application receives a 
+    ```http
+    HTTP/1.1 GET: /payment/success?token=12345
+    ```
+* Your application shall process this request like 
+    ```http
+    HTTP/1.1 POST: /payment/mark-succeeded
+    token=12345
+    ```
+
+The configuration could look like this:
+ 
+```php
+<?php declare(strict_types=1);
+
+namespace YourVendor\YourProject;
+
+use IceHawk\IceHawk\Interfaces\ConfiguresIceHawk;
+use IceHawk\IceHawk\Interfaces\RoutesToWriteHandler;
+use IceHawk\IceHawk\Interfaces\BypassesRequest;
+use IceHawk\IceHawk\Routing\WriteRoute;
+use IceHawk\IceHawk\Routing\RequestBypass;
+use IceHawk\IceHawk\Routing\Patterns\Literal;
+use IceHawk\IceHawk\Defaults;
+
+class IceHawkConfig implements ConfiguresIceHawk
+{
+    use Defaults\Traits\DefaultRequestProviding;
+    use Defaults\Traits\DefaultReadRouting;
+    use Defaults\Traits\DefaultEventSubscribing;
+    use Defaults\Traits\DefaultCookieProviding;
+    use Defaults\Traits\DefaultFinalReadResponding;
+    use Defaults\Traits\DefaultFinalWriteResponding;
+
+    /**
+     * @return array|\Traversable|BypassesRequest[]
+     */
+    public function getRequestBypasses()
+    {
+    	return [
+    	    new RequestBypass(
+    	    	new Literal('/payment/success'), 
+    	    	'/payment/mark-succeeded', 
+    	    	HttpMethod::POST
+    	    ),	
+		];
+    }
+
+    /**
+     * @return array|\Traversable|RoutesToWriteHandler[]
+     */
+    public function getWriteRoutes()
+    {
+        return [
+            new WriteRoute( 
+            	new Literal('/payment/mark-succeeded'), 
+            	new MarkPaymentSucceededRequestHandler() 
+            ),
+        ];
+    }
+}
+```
+
+**Please note:** The `MarkPaymentSucceededRequestHandler` has to implement the `IceHawk\IceHawk\Interfaces\HandlesPostRequest` interface.
+
+Of course you can use any of the [URI pattern classes](@baseUrl@/docs/icehawk/routing.html#uri-pattern-classes) for matching in the request bypass.

Contents/docs/icehawk/request-input-data.md

@@ -410,19 +410,28 @@ var_dump( $notUploadedFile );
 This prints:
 
 ```php
+# $uploadedFile0
 object(IceHawk\IceHawk\Requests\UploadedFile)[17]
   private 'name' => string '...' (length=24)
   private 'tmpName' => string '...' (length=66)
   private 'error' => int 0
   private 'size' => int 40506
   private 'type' => string 'image/png' (length=9)
 
+# $uploadedFile4
 object(IceHawk\IceHawk\Requests\UploadedFile)[19]
   private 'name' => string '...' (length=24)
   private 'tmpName' => string '...' (length=66)
   private 'error' => int 0
   private 'size' => int 40506
   private 'type' => string 'image/png' (length=9)
 
-NULL
+# $notUploadedFile
+# empty UploadedFile object with error UPLOAD_ERR_NO_FILE
+object(IceHawk\IceHawk\Requests\UploadedFile)[19]
+  private 'name' => string '' (length=0)
+  private 'tmpName' => string '' (length=0)
+  private 'error' => int 4 
+  private 'size' => int 0
+  private 'type' => string '' (length=0)
 ```

Contents/docs/icehawk/routing.md

@@ -207,7 +207,7 @@ The advantage of this approach is that not all routes, patterns and request hand
 
 <hr class="blockspace">
 
-## What patterns to use for matching?
+## What patterns to use for matching? <a name="uri-pattern-classes"></a>
 
 As already mentioned above, the IceHawk component provides 3 ready-to-use pattern classes. We'd like to show you examples for each of them.
 

Contents/docs/icehawk/uploaded-files.md

@@ -263,6 +263,7 @@ var_dump( $notUploadedFile );
 This prints:
 
 ```php
+# $uploadedFile0
 # file at default index 0
 object(IceHawk\IceHawk\Requests\UploadedFile)[17]
   private 'name' => string 'branding-circle.png' (length=19)
@@ -271,6 +272,7 @@ object(IceHawk\IceHawk\Requests\UploadedFile)[17]
   private 'size' => int 14273
   private 'type' => string 'image/png' (length=9)
 
+# $uploadedFile4
 # file at a string index "file4"
 object(IceHawk\IceHawk\Requests\UploadedFile)[19]
   private 'name' => string 'branding-circle.png' (length=19)
@@ -279,14 +281,16 @@ object(IceHawk\IceHawk\Requests\UploadedFile)[19]
   private 'size' => int 14273
   private 'type' => string 'image/png' (length=9)
 
-# not existing file
-NULL
+# $notUploadedFile
+# not existing file, empty UploadedFile object with error UPLOAD_ERR_NO_FILE
+object(IceHawk\IceHawk\Requests\UploadedFile)[19]
+  private 'name' => string '' (length=0)
+  private 'tmpName' => string '' (length=0)
+  private 'error' => int 4 
+  private 'size' => int 0
+  private 'type' => string '' (length=0)
 ```
 
-**Please note:** 
-[We will change the return value for not-existing files in `v2.1.0` to an empty `UploadedFile` object with the error code `UPLOAD_ERR_NO_FILE`.](https://github.com/icehawk/icehawk/issues/22)
-And will then add a return type declaration to the `getOneFile()` method.
-
 <hr class="blockspace">
 
 ## The UploadedFile object