Merge pull request #110 from skipperbent/development

Updated documentation and added demo-project.

.gitignore

@@ -1,3 +1,4 @@
 .idea
 composer.lock
-vendor/
+vendor/
+demo-project/vendor

README.md

@@ -32,6 +32,14 @@ The goal of this project is to create a router that is 100% compatible with the
 - Custom boot managers to redirect urls to other routes
 - Input manager; to manage `GET`, `POST` params.
 
+## Installation and demo
+
+We've included a simple demo project for the router which can be found in the `demo-project` folder.
+
+Please refer to the demo-project documentation for further reading on how to setup and install simple-php-router:
+
+[Link to demo documentation](demo-project/README.md)
+
 ## Initialising the router
 
 In your ```index.php``` require your ```routes.php``` and call the ```routeRequest()``` method when all your custom routes has been loaded. This will trigger and do the actual routing of the requests.
@@ -176,8 +184,6 @@ This is a simple example of an integration into a framework.
 The framework has it's own ```Router``` class which inherits from the ```SimpleRouter``` class. This allows the framework to add custom functionality.
 
 ```php
-<?php
-<?php
 namespace Pecee;
 
 use Pecee\Exception\RouterException;
@@ -481,6 +487,7 @@ This is some sites that uses the simple-router project in production.
 
 - [holla.dk](http://www.holla.dk)
 - [ninjaimg.com](http://ninjaimg.com)
+- [bookandbegin.com](https://bookandbegin.com)
 
 ## Documentation
 While I work on a better documentation, please refer to the Laravel 5 routing documentation here:

demo-project/README.md

@@ -0,0 +1,104 @@
+# Simple PHP router demo project
+
+This project is here to give you a basic understanding of how to setup and using simple-php-router.
+
+Please note that this demo-project only covers how to integrate simple-php-project in a project without a framework. If you are using some sort of PHP framework in your project 
+the implementation might vary.
+
+**What we won't cover:**
+
+- How to setup a solution that fits your need. This is a basic demo to help you get started.
+- How to add Controllers, Middlewares or ExceptionHandlers with cool functionality.
+- How to integrate into third party frameworks.
+
+**What we cover:**
+
+- How to get up and running fast - from scratch.
+- How to set ExceptionHandlers, Middlewares and Controllers working.
+- How to setup your webservers.
+
+## Installation
+
+- Navigate to the `demo-project` folder and run `composer install`.
+- Point your webserver to `demo-project/public`.
+
+### Setting up Nginx
+
+If you are using Nginx remember to enable url-rewriting.
+
+You can easily do this by adding the following configuration for the Nginx configuration for the demo-project.
+
+```
+location / {
+    try_files $uri $uri/ /index.php?$query_string;
+}
+```
+
+### Setting up Apache
+
+Nothing special is required for Apache to work. We've include the `.htaccess` file in the `public` folder. If rewriting is not working for you, please 
+check that `.htaccess` support is enabled in the Apache configuration - or add the rules manually.
+
+## Folder structure
+
+| Folder        | Description |
+| ------------- |-------------|
+| app            |Contains projects-specific PHP classes|
+| public         |Public folder which are accessible through the web.|
+
+## Notes
+
+The demo project has it's own `Router` class implemented which extends the `SimpleRouter` class with further functionality such as 
+default exceptionhandlers and middlewares. This class can be useful adding functionality that are required before and after routing 
+occurs or add extra functionality to the router. 
+
+In this project we also use our custom router-class to autoload the `routes.php` file.
+
+Please check the `routes.php` file in `demo-project/app` for all the urls/rules in the project.
+
+### CSRF-verifier
+
+We've added a custom CSRF-verifier middleware called `CsrfVerifier` and disabled CSRF checks for all calls to `/api/*`.
+
+### Exception handlers
+
+The included `CustomExceptionHandler` class returns a json response for errors received on calls to `/api/*` or otherwise just forms a simple formatted error response.
+
+### Middlewares
+
+`ApiVerification` class is added to all calls to `/api/*`. This simple class just adds some data to the `Request` object, which is returned in one of the methods in the 
+`ApiController` class.
+
+### Urls
+
+Please see `routes.php` for all routes and rules.
+
+| URL        |
+| ------------- |
+| /             |
+| /api/demo       |
+| /companies       |
+| /companies/[id]  |
+| /contact         |
+
+## The MIT License (MIT)
+
+Copyright (c) 2016 Simon Sessingø / simple-php-router
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

demo-project/app/Controllers/ApiController.php

@@ -0,0 +1,22 @@
+<?php
+namespace Demo\Controllers;
+
+use Pecee\Http\Request;
+
+class ApiController {
+
+    public function index() {
+
+        // The variable authenticated is set to true in the ApiVerification middleware class.
+
+        $request = Request::getInstance();
+
+        header('content-type: application/json');
+
+        echo json_encode([
+            'authenticated' => $request->authenticated
+        ]);
+
+    }
+
+}

demo-project/app/Controllers/DefaultController.php

@@ -0,0 +1,25 @@
+<?php
+namespace Demo\Controllers;
+
+class DefaultController {
+
+    public function index() {
+
+        // implement
+        echo 'DefaultController -> index';
+
+    }
+
+    public function contact() {
+
+        echo 'DefaultController -> contact';
+
+    }
+
+    public function companies($id = null) {
+
+        echo 'DefaultController -> companies -> id: ' . $id;
+
+    }
+
+}

demo-project/app/Handlers/CustomExceptionHandler.php

@@ -0,0 +1,28 @@
+<?php
+namespace Demo\Handlers;
+
+use Pecee\Handler\IExceptionHandler;
+use Pecee\Http\Request;
+use Pecee\SimpleRouter\RouterEntry;
+
+class CustomExceptionHandler implements IExceptionHandler {
+
+    public function handleError( Request $request, RouterEntry $router = null, \Exception $error) {
+
+        // Return json errors if we encounter an error on /api.
+        if(stripos($request->getUri(), '/api') !== false) {
+            header('content-type: application/json');
+            echo json_encode([
+                'error' => $error->getMessage(),
+                'code' => $error->getCode()
+            ]);
+            die();
+        }
+
+        // else we just throw the error
+        if($error->getCode() == 404) {
+            die(sprintf('An error occurred (%s):<br/>%s', $error->getCode(), $error->getMessage()));
+        }
+    }
+
+}

demo-project/app/Middlewares/ApiVerification.php

@@ -0,0 +1,16 @@
+<?php
+namespace Demo\Middlewares;
+
+use Pecee\Http\Middleware\IMiddleware;
+use Pecee\Http\Request;
+
+class ApiVerification implements IMiddleware {
+
+    public function handle(Request $request) {
+
+        // Do authentication
+        $request->authenticated = true;
+
+    }
+
+}

demo-project/app/Middlewares/CsrfVerifier.php

@@ -0,0 +1,13 @@
+<?php
+namespace Demo\Middlewares;
+
+use Pecee\Http\Middleware\BaseCsrfVerifier;
+
+class CsrfVerifier extends BaseCsrfVerifier {
+
+    /**
+     * CSRF validation will be ignored on the following urls.
+     */
+    protected $except = ['/api/*'];
+
+}

demo-project/app/Router.php

@@ -0,0 +1,84 @@
+<?php
+
+/**
+ * Custom router which handles default middlewares, default exceptions and things
+ * that should be happen before and after the router is initialised.
+ */
+
+namespace Demo;
+
+use Pecee\Exception\RouterException;
+use Pecee\Handler\IExceptionHandler;
+use Pecee\Http\Middleware\IMiddleware;
+use Pecee\SimpleRouter\RouterBase;
+use Pecee\SimpleRouter\SimpleRouter;
+
+class Router extends SimpleRouter {
+
+    protected static $defaultExceptionHandler;
+    protected static $defaultMiddlewares = array();
+
+    public static function start($defaultNamespace = null) {
+
+        // change this to whatever makes sense in your project
+        require_once 'routes.php';
+
+        // Handle exceptions
+        try {
+
+            if(count(static::$defaultMiddlewares)) {
+                /* @var $middleware \Pecee\Http\Middleware\IMiddleware */
+                foreach(static::$defaultMiddlewares as $middleware) {
+                    $middleware = new $middleware();
+                    if(!($middleware instanceof IMiddleware)) {
+                        throw new RouterException('Middleware must be implement the IMiddleware interface.');
+                    }
+                    $middleware->handle(RouterBase::getInstance()->getRequest());
+                }
+            }
+
+            // Set default namespace
+            $defaultNamespace = '\\Demo\\Controllers';
+
+            parent::start($defaultNamespace);
+        } catch(\Exception $e) {
+
+            $route = RouterBase::getInstance()->getLoadedRoute();
+
+            // Otherwise use the fallback default exceptions handler
+            if(static::$defaultExceptionHandler !== null) {
+                static::loadExceptionHandler(static::$defaultExceptionHandler, $route, $e);
+            }
+
+            throw $e;
+        }
+
+    }
+
+    protected static function loadExceptionHandler($class, $route, $e) {
+        $class = new $class();
+
+        if(!($class instanceof IExceptionHandler)) {
+            throw new \ErrorException('Exception handler must be an instance of \Pecee\Handler\IExceptionHandler');
+        }
+
+        $class->handleError(RouterBase::getInstance()->getRequest(), $route, $e);
+    }
+
+    public static function defaultExceptionHandler($handler) {
+        static::$defaultExceptionHandler = $handler;
+    }
+
+    /**
+     * Add default middleware that will be loaded before any route
+     * @param string|array $middlewares
+     */
+    public static function defaultMiddleware($middlewares) {
+        if(is_array($middlewares)) {
+            static::$defaultMiddlewares = $middlewares;
+        } else {
+            static::$defaultMiddlewares[] = $middlewares;
+        }
+    }
+
+}

demo-project/app/routes.php

@@ -0,0 +1,19 @@
+<?php
+/**
+ * This file contains all the routes for the project
+ */
+
+use Demo\Router;
+
+Router::csrfVerifier(new \Demo\Middlewares\CsrfVerifier());
+Router::defaultExceptionHandler('\Demo\Handlers\CustomExceptionHandler');
+
+Router::get('/', 'DefaultController@index')->setAlias('home');
+Router::get('/contact', 'DefaultController@contact')->setAlias('contact');
+Router::basic('/companies', 'DefaultController@companies')->setAlias('companies');
+Router::basic('/companies/{id}', 'DefaultController@companies')->setAlias('companies');
+
+// Api
+Router::group(['prefix' => '/api', 'middleware' => 'Demo\Middlewares\ApiVerification'], function() {
+    Router::resource('/demo', 'ApiController');
+});

demo-project/composer.json

@@ -0,0 +1,26 @@
+{
+ 	"name": "pecee/simple-router-demo",
+ 	"description": "Simple router demo project",
+ 	"keywords": [
+		"simple-router",
+		"php",
+		"php-simple-router"
+	],
+	"license": "MIT",
+	"type": "project",
+	"require": {
+		"php": ">=5.4.0",
+		"pecee/simple-router": "1.*"
+	},
+	"require-dev": {
+
+	},
+	"config": {
+		"preferred-install": "dist"
+	},
+    "autoload": {
+      "psr-4": {
+        "Demo\\": "app/"
+      }
+    }
+}

demo-project/public/.htaccess

@@ -0,0 +1,5 @@
+RewriteEngine on
+RewriteCond %{SCRIPT_FILENAME} !-f
+RewriteCond %{SCRIPT_FILENAME} !-d
+RewriteCond %{SCRIPT_FILENAME} !-l
+RewriteRule ^(.*)$ index.php/$1

demo-project/public/index.php

@@ -0,0 +1,7 @@
+<?php
+
+// load composer dependencies
+require '../vendor/autoload.php';
+
+// Start the routing
+\Demo\Router::start();

src/Pecee/Http/Input/Input.php

@@ -97,6 +97,10 @@ class Input {
         return $default;
     }
 
+    public function exists($index) {
+        return ($this->getObject($index) !== null);
+    }
+
     public function setGet() {
         $this->get = new InputCollection();
 
@@ -123,7 +127,7 @@ class Input {
 
         $postVars = array();
 
-        if(in_array($_SERVER['REQUEST_METHOD'], ['PUT', 'PATCH', 'DELETE'])) {
+        if(isset($_SERVER['REQUEST_METHOD']) && in_array($_SERVER['REQUEST_METHOD'], ['PUT', 'PATCH', 'DELETE'])) {
             parse_str(file_get_contents('php://input'), $postVars);
         } else {
             $postVars = $_POST;

src/Pecee/Http/Input/InputItem.php

@@ -46,6 +46,16 @@ class InputItem {
         return $this;
     }
 
+    /**
+     * Set input value
+     * @param string $value
+     * @return static $this
+     */
+    public function setValue($value) {
+        $this->value = $value;
+        return $this;
+    }
+
     public function __toString() {
         return (string)$this->getValue();
     }

src/Pecee/Http/Request.php

@@ -22,9 +22,9 @@ class Request {
 
     public function __construct() {
         $this->data = array();
-        $this->host = $_SERVER['HTTP_HOST'];
-        $this->uri = $_SERVER['REQUEST_URI'];
-        $this->method = (isset($_POST['_method'])) ? strtolower($_POST['_method']) : strtolower($_SERVER['REQUEST_METHOD']);
+        $this->host = isset($_SERVER['HTTP_HOST']) ? $_SERVER['HTTP_HOST'] : array();
+        $this->uri = isset($_SERVER['REQUEST_URI']) ? $_SERVER['REQUEST_URI'] : array();
+        $this->method = (isset($_POST['_method'])) ? strtolower($_POST['_method']) : (isset($_SERVER['REQUEST_METHOD']) ? strtolower($_SERVER['REQUEST_METHOD']) : array());
         $this->headers = $this->getAllHeaders();
         $this->input = new Input();
     }

src/Pecee/SimpleRouter/RouterBase.php

@@ -72,12 +72,14 @@ class RouterBase {
                 array_push($newPrefixes, trim($route->getPrefix(), '/'));
             }
 
+            /* @var $group RouterGroup */
+            $group = null;
+
             if(!($route instanceof RouterGroup)) {
                 if(is_array($newPrefixes) && count($newPrefixes) && $backStack) {
                     $route->setUrl( '/' . join('/', $newPrefixes) . $route->getUrl() );
                 }
 
-                $group = null;
                 $this->controllerUrlMap[] = $route;
             }
 
@@ -86,12 +88,12 @@ class RouterBase {
             if($route instanceof RouterGroup && is_callable($route->getCallback())) {
                 $group = $route;
 
-                $route->renderRoute($this->request);
-                $mergedSettings = array_merge($settings, $route->getMergeableSettings());
+                $group->renderRoute($this->request);
+                $mergedSettings = array_merge($settings, $group->getMergeableSettings());
 
-                // Add exceptionhandler
-                if($route->matchRoute($this->request) && $route->getExceptionHandler() !== null) {
-                    $this->exceptionHandlers[] = $route->getExceptionHandler();
+                // Add ExceptionHandler
+                if($group->matchRoute($this->request) && $group->getExceptionHandler() !== null) {
+                    $this->exceptionHandlers[] = $route;
                 }
             }
 
@@ -178,8 +180,12 @@ class RouterBase {
 
     protected function handleException(\Exception $e) {
 
-        foreach ($this->exceptionHandlers as $handler) {
-            $handler = new $handler($this->request);
+        /* @var $route RouterGroup */
+        foreach ($this->exceptionHandlers as $route) {
+            $route->loadMiddleware($this->request);
+            $handler = $route->getExceptionHandler();
+            $handler = new $handler();
+
             if (!($handler instanceof IExceptionHandler)) {
                 throw new RouterException('Exception handler must implement the IExceptionHandler interface.');
             }
@@ -288,9 +294,7 @@ class RouterBase {
         if(is_array($getParams)) {
             if ($includeEmpty === false) {
                 $getParams = array_filter($getParams, function ($item) {
-                    if (!empty($item)) {
-                        return $item;
-                    }
+                    return (!empty($item));
                 });
             }
 

src/Pecee/SimpleRouter/RouterEntry.php

@@ -232,7 +232,7 @@ abstract class RouterEntry {
     }
 
     /**
-     * Dynamicially set settings value
+     * Dynamically set settings value
      *
      * @param string $name
      * @param mixed|null $value
@@ -249,7 +249,7 @@ abstract class RouterEntry {
         return new $name();
     }
 
-    protected function parseParameters($route, $url, $parameterRegex = '[a-z0-9]+') {
+    protected function parseParameters($route, $url, $parameterRegex = '[\w]+') {
         $parameterNames = array();
         $regex = '';
         $lastCharacter = '';
@@ -261,12 +261,6 @@ abstract class RouterEntry {
 
             $character = $route[$i];
 
-            // Skip "/" if we are at the end of a parameter
-            if($lastCharacter === '}' && $character === '/') {
-                $lastCharacter = $character;
-                continue;
-            }
-
             if($character === '{') {
                 // Remove "/" and "\" from regex
                 if(substr($regex, strlen($regex)-1) === '/') {
@@ -285,10 +279,10 @@ abstract class RouterEntry {
 
                 if($lastCharacter === '?') {
                     $parameter = substr($parameter, 0, strlen($parameter)-1);
-                    $regex .= '(?:\\/?(?P<'.$parameter.'>[^\/]+)?\\/?)';
+                    $regex .= '(?:\/?(?P<' . $parameter . '>'. $parameterRegex .')[^\/]?)?';
                     $required = false;
                 } else {
-                    $regex .= '\\/(?P<' . $parameter . '>'. $parameterRegex .')\\/';
+                    $regex .= '\/?(?P<' . $parameter . '>'. $parameterRegex .')[^\/]?';
                 }
                 $parameterNames[] = array('name' => $parameter, 'required' => $required);
                 $parameter = '';
@@ -307,7 +301,8 @@ abstract class RouterEntry {
 
         $parameterValues = array();
 
-        if(preg_match('/^'.$regex.'$/is', $url, $parameterValues)) {
+        if(preg_match('/^'.$regex.'\/?$/is', $url, $parameterValues)) {
+
             $parameters = array();
 
             $max = count($parameterNames);
@@ -399,7 +394,7 @@ abstract class RouterEntry {
     }
 
     /**
-     * Get allowed requeset methods
+     * Get allowed request methods
      *
      * @return array
      */

src/Pecee/SimpleRouter/RouterResource.php

@@ -52,7 +52,7 @@ class RouterResource extends RouterEntry {
 
         $route = rtrim($this->url, '/') . '/{id?}/{action?}';
 
-        $parameters = $this->parseParameters($route, $url, '[0-9]+?');
+        $parameters = $this->parseParameters($route, $url);
 
         if($parameters !== null) {
 

src/Pecee/SimpleRouter/RouterRoute.php

@@ -105,7 +105,7 @@ class RouterRoute extends RouterEntry {
         } else {
             return strtolower($this->getAlias()) === strtolower($name);
         }
-        
+
         return false;
     }
 

test/Dummy/DummyController.php

@@ -6,4 +6,9 @@ class DummyController {
         echo static::class . '@' .'start() OK';
     }
 
+    public function param($params = null) {
+        $params = func_get_args();
+        echo 'Params: ' . join(', ', $params);
+    }
+
 }

test/MiddlewareTest.php

@@ -20,17 +20,16 @@ class MiddlewareTest extends PHPUnit_Framework_TestCase  {
 
         \Pecee\SimpleRouter\SimpleRouter::get('/my/test/url', 'DummyController@start', ['middleware' => 'DummyMiddleware']);
 
+        $found = false;
+
         try {
             \Pecee\SimpleRouter\SimpleRouter::start();
         }catch(Exception $e) {
-            $this->assertTrue(($e instanceof MiddlewareLoadedException));
-            return;
+            $found = ($e instanceof MiddlewareLoadedException);
         }
 
-        throw new Exception('Middleware not loaded');
+        $this->assertTrue($found);
 
     }
 
-
-
 }

test/RouterRouteTest.php

@@ -66,4 +66,40 @@ class RouterRouteTest extends PHPUnit_Framework_TestCase  {
 
     }
 
+    public function testSimpleParam() {
+
+        \Pecee\SimpleRouter\RouterBase::reset();
+
+        \Pecee\Http\Request::getInstance()->setMethod('get');
+        \Pecee\Http\Request::getInstance()->setUri('/test-param1');
+
+        \Pecee\SimpleRouter\SimpleRouter::get('/test-{param1}', 'DummyController@param');
+        \Pecee\SimpleRouter\SimpleRouter::start();
+
+    }
+
+    public function testMultiParam() {
+
+        \Pecee\SimpleRouter\RouterBase::reset();
+
+        \Pecee\Http\Request::getInstance()->setMethod('get');
+        \Pecee\Http\Request::getInstance()->setUri('/test-param1-param2');
+
+        \Pecee\SimpleRouter\SimpleRouter::get('/test-{param1}-{param2}', 'DummyController@param');
+        \Pecee\SimpleRouter\SimpleRouter::start();
+
+    }
+
+    public function testPathParam() {
+
+        \Pecee\SimpleRouter\RouterBase::reset();
+
+        \Pecee\Http\Request::getInstance()->setMethod('get');
+        \Pecee\Http\Request::getInstance()->setUri('/test/path/param1');
+
+        \Pecee\SimpleRouter\SimpleRouter::get('/test/path/{param}', 'DummyController@param');
+        \Pecee\SimpleRouter\SimpleRouter::start();
+
+    }
+
 }