Simple PHP Router
, (*1)
Updating from version 0.x or 1.x will break your code! read the documentation before upgrading!, (*2)
Getting started
Step 1 - .htaccess file
create an .htaccess file in the root of your project and fill it with the code below:, (*3)
<IfModule mod_rewrite.c>
<IfModule mod_negotiation.c>
Options -MultiViews
</IfModule>
RewriteEngine On
# Redirect Trailing Slashes...
RewriteRule ^(.*)/$ /$1 [L,R=301]
# Handle Front Controller...
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.php [L]
</IfModule>
Step 2 - require szenis/routingbr/
In your terminal execute: composer require szenis/routing, (*4)
Step 3 - create index.phpbr/
Create the file index.php in the root of your project, (*5)
Step 4 - require autoload.php and use the Routerbr/, (*6)
The following snippet shows how the router can be used., (*7)
<?php
require './vendor/autoload.php';
use Szenis\Routing\Router;
$router = new Router();
$router->get('/{n:date}-{w:item}', function($date, $item) {
return 'hello world';
});
$response = $router->resolve($_SERVER['REQUEST_URI'], $_SERVER['REQUEST_METHOD']);
switch ($response['code']) {
case \Szenis\Routing\Route::STATUS_NOT_FOUND:
// render your 404 page here...
break;
case \Szenis\Routing\Route::STATUS_FOUND:
// the router only resolves the route, here is an example how to execute the route.
if ($response['handler'] instanceof \Closure) {
echo call_user_func_array($response['handler'], $response['arguments']);
}
break;
}
to your index.php, (*8)
Optionalbr/
For debuging purpose add the following to your index.php, (*9)
error_reporting(E_ALL);
ini_set('display_errors', 1);
Usage
/**
* initialize the router class
*/
$router = new Router();
/**
* Route matches the url '/' for the GET method
*/
$router->add('/', 'GET', function() {
// the closure will be executed when route is triggerd and will return 'hello world'
return 'hello world!';
});
/**
* It is posible to add one or multiple wildcards in one route
*/
$router->add('/user/{id}', 'GET', function($id) {
return $id;
});
/**
* It is also posible to allow mulitple methods for one route (methods should be separated with a '|')
*/
$router->add('/user/{id}/edit', 'GET|POST', function($id) {
return 'user id: '.$id;
});
/**
* Or when u are using controllers in a namespace you could give the full path to a controller (controller::action)
*
* Since version 2.0 executing the handler is up to you.
*/
$router->add('/user/{id}/delete', 'DELETE', 'App\Controllers\UserController::delete');
/**
* Since version 1.1 there are shortcut methods for get, post, put, patch, delete and any.
* You can use them as follow
*/
$router->get('/example/get', function() {}); // Will match GET requests
$router->post('/example/post', function() {}); // Will match POST requests
$router->put('/example/put', function() {}); // Will match PUT requests
$router->patch('/example/patch', function() {}); // Will match PATCH requests
$router->delete('/example/delete', function() {}); // Will match DELETE requests
$router->any('/example/any', function() {}); // Will match GET, POST, PUT, PATCH, DELETE requests
/**
* resolve the route and receive the response
*
* The response is an array with the following keys
* - code (contains 200 if the route is found, else 404)
* - handler (contains the handler, often a \Closure or full path to your controller action)
* - arguments (contains the route arguments if any)
*/
$response = $router->resolve($_SERVER['REQUEST_URI'], $_SERVER['REQUEST_METHOD']);
/**
* To execute your route you have to do the following
*/
switch ($response['code']) {
case \Szenis\Routing\Route::STATUS_NOT_FOUND:
// render your 404 page here...
break;
case \Szenis\Routing\Route::STATUS_FOUND:
// the router only resolves the route, here is an example how to execute the route.
if ($response['handler'] instanceof \Closure) {
echo call_user_func_array($response['handler'], $response['arguments']);
}
// if your handler is a full path to your function you could execute it with this:
$className = substr($response['handler'], 0, strpos($response['handler'], '::'));
$functionName = substr($response['handler'], strpos($response['handler'], '::') + 2);
echo call_user_func_array(array((new $className), $functionName), $response['arguments']);
break;
}
Wildcard options
The following options exist, (*10)
- a: (alfabetic chars only)
- n: (numbers only)
- an: (alfanumeric chars only)
- w: (alfanumeric, dash and underscore only)
- ?: (optional parameters) - must be last part of the url
- *: (lazy loading) - must be last part of the url
How to use
, (*11)
// The id must be a number
$router->add('/user/{n:id}', 'GET', 'App\Controllers\UserController::show');
// The id must contain either alfabetic chars or numbers
$router->add('/user/{an:id}', 'GET', 'App\Controllers\UserController::show');
// Now we want everything behind docs/ in the page variable
// For example when we go to the url /docs/user/edit we will receive user/edit in the page variable
$router->add('/docs/{*:page}', 'GET', function($page) {
// do something with $page
});
// Optional parameter example
$router->add('/hello/{a:name}/{?:lastname}', 'GET', function($name, $lastname = null) {
// check if lastname is provided
// if ($lastname) {...}
})
Upgrading from v0.x/v1.x to v2.x
- Namespace has changed from
\Szenis to \Szenis\Routing
-
$router->setNamespace() has been removed!
- RouteResolver shouldnt be used to resolve routes, use the following instead
$router->resolve($uri, $method);
- Router does not execute the route anymore. From now one it is your responsibility to execute the handler. At the bottom of the section 'Usage' there is an example how to execute the handler.
Changelog
v2.0.0
- Removed 'default' namespace
- Changed namespace from \Szenis to \Szenis\Routing
- Router does not execute the callable itself, this gives you more control over parameter injection
- RouteResolver is callable trough the router
- Bugfix: it is now possible to have more then one parameter in one segment (/{parameter1}-{parameter2}/), (*12)
v1.1.0
- Shortcut functions for get, post, put, patch, delete and any, (*13)
v1.0.0
- Updated readme
- Posible to add default namespace, (*14)
v0.9.0
- 100% test coverage
- minimum php version reduced from 5.4 to 5.3, (*15)
v0.8.0
- Added optional parameter
- Added lazy url loading
- Improved code, (*16)
v0.7.0
- Improved code, (*17)
v0.6.0
- Changed usages of router check out the Usages section for more detail
- Posible to add closure to a route
- Routes with query string will be found now (bugfix: v0.6.1), (*18)
v0.5.0
- Removed unnecessary code, (*19)
v0.4.0
- Added interfaces and created an url factory, (*20)
v0.3.0
- Its now posible to add options to url wildcards for more information see wildcard options, (*21)
v0.2.0
- RouteResolver uses regex to match routes quicker, (*22)
Wallogit.com
