Routing

Author: smichaelsen

in-depth_documentation/configuration.md

@@ -98,4 +98,5 @@ Line 11 reads the `server_url` from the section `application` and assigns it to
 | plugins.*&lt;ARRAY&gt;* | | The keys are the PHP namespaces of the plugins that you are using in your installation and the value is `1`if you want to activate it. Example:<br>`plugins.MyVendor\MyPackage\FirstPlugin = 1`<br>`plugins.MyVendor\MyPackage\SecondPlugin = 0`<br>Will result in the first plugin being loaded and the second not. You can get the Plugin namespaces from the README files of the plugin packages you're using (hopefully). |
 | powered_by | true | Adds a HTML comment to the output with a hint to PHPFramework |
 | template_file_extension | `.twig` / `.html` | By default PHPFramwork uses the `TwigView` to render templates. Then `.twig` will be the default template file extension.<br>If you use your own view class based on `AbstractView` then `.html` will be the default template file extension. |
+| uri_path_prefix | | Provide this prefix if your application runs in a subfolder of your host. E.g. for `www.mydomain.tld/path/to/application` set `path/to/application` as `uri_path_prefix`. |
 | version | *version* | Is automatically set to the current 2-digit version of PHPFramework, e.g. `1.3`. |

in-depth_documentation/routing.md

@@ -1,39 +1,90 @@
 # Routing
 
-## `routes.php`
+## Basic Usage
+`myapp/routes.php`:
 
-Routing in PHPFramework is bloody easy. Inside your application folder you define your routes in `routes.php`. It has to return an array with your routes.
+    <?php
+      return [
+        'users/' => 'MyVendor\\MyApp\\Controller\\UserListController',
+        '.' => 'MyVendor\\MyApp\\Controller\\IndexController',
+    ];
+
+The controller for the matched route will be called. The method that is being called depends on the HTTP request type. E.g. a GET Request results in the `get()` method being called.
+
+If the request come from the command line `cli()` will be called.
+
+## Background
+
+The Router (`\AppZap\PHPFramework\Mvc\Router`) will check if the current url matches any of the regular expressions and calls the first matching Controller. For that it takes the URL and strips the hostname. If your application runs in a subfolder you should strip it with the following option:
+
+`settings.ini`:
 
-The routes array has regular expressions as keys and controller classnames as values.
+    [phpframework]
+    uri_path_prefix = "path/to/application"
 
-### example
+The remaining part is compared to the keys of the routes array. Notice that there must be no leading slashes in the route definitions.
+
+The first matching route will be followed.
+
+To configure the empty route (e.g. `http://mydomain.tld/`), use the dot placeholder `"."` (see in above example).
+
+## Advanced usage
+
+### parameters
+
+Urls may contain dynamic parts such as a username or an ID. You want to match those URLs in your routing and provide these values to your controller. Use the `?` placeholder for those parameters.
+
+`routes.php`:
 
     <?php
+
     return [
-    	'|/users/$|' => 'MyVendor\\MyApp\\Controller\\UserController',
-    	'|/$|' => 'MyVendor\\MyApp\\Controller\\IndexController',
+      'users/?/' => 'MyVendor\\MyApp\\Controller\\ProfileController',
     ];
 
-The Router (`\AppZap\PHPFramework\Mvc\Router`) will check if the current url matches any of the regular expressions and calls the first matching Controller.
+The `$params` array of your Controller method will be populated with the matched parameters.
 
-## method
+### Beginning, middle, end
 
-The controller method that is called depends on the HTTP Request method. e.g. a GET Request results in the `get()` method being called.
+You can also match routes that start with, end with or contain a certain expression. The syntax is similar to the MySQL `LIKE` statement:
 
-If the request come from the command line `cli()` will be called.
+`routes.php`:
 
-## parameters
+    <?php
 
-*todo..*
+    return [
+      'shop/%' => 'MyVendor\\MyApp\\Controller\\ShopController',
+    ];
 
-## callable routing
+Now every request that **starts** with `http://mydomain.tld/shop/` will be processed by the `ShopController` and it takes responsibility to check the url for further routing.
 
-Instead of providing a controller class name, you can also directly provide a [callable](http://de2.php.net/manual/de/function.is-callable.php), e.g. an anonymous function.
+Use `%/shop/` to route requests that **end** with "/shop/".<br>
+Use `%/shop/%` to route requests that **contain** "/shop/".<br>
+
+### Regular expressions
+
+If you need more flexibility you can use regular expressions for your route definitions. Example:
+
+`routes.php`:
+
+    <?php
+
+    return [
+      '|^trader/(.*)/$|' => 'MyVendor\\MyApp\\Controller\\TraderController',
+      '|^ajax/(.*)$|' => 'MyVendor\\MyApp\\Controller\\AjaxController',
+      '||' => 'MyVendor\\MyApp\\Controller\\IndexHandler',
+    ];
 
-### example
+The strings *matched* by the paranthesis of the regular expressions will be passed to the Controller as `$params`.
+
+
+### callable routing
+
+Instead of providing a controller class name, you can also directly provide a [callable](http://de2.php.net/manual/de/function.is-callable.php), e.g. an anonymous function.
 
+`routes.php`:
 
     <?php
     return [
-    	'|/is/phpframework/awesome/$|' => function() { return 'yes!' },
+      'is/phpframework/awesome/' => function() { return 'yes!' },
     ];