| Package Data | |
|---|---|
| Maintainer Username: | sessingo |
| Maintainer Contact: | simon.sessingoe@gmail.com (Simon Sessingø) |
| Package Create Date: | 2015-09-18 |
| Package Last Update: | 2024-11-10 |
| Home Page: | |
| Language: | PHP |
| License: | MIT |
| Last Refreshed: | 2024-11-11 15:05:50 |
| Package Statistics | |
|---|---|
| Total Downloads: | 143,405 |
| Monthly Downloads: | 3,740 |
| Daily Downloads: | 127 |
| Total Stars: | 651 |
| Total Watchers: | 22 |
| Total Forks: | 122 |
| Total Open Issues: | 44 |
Simple, fast and yet powerful PHP router that is easy to get integrated and in any project. Heavily inspired by the way Laravel handles routing, with both simplicity and expand-ability in mind.
With simple-router you can create a new project fast, without depending on a framework.
It only takes a few lines of code to get started:
SimpleRouter::get('/', function() {
return 'Hello world';
});
If you like simple-router and wish to see the continued development and maintenance of the project, please consider showing your support by buying me a coffee. Supporters will be listed under the credits section of this documentation.
You can donate any amount of your choice by clicking here.
Add the latest version of the simple-router project running this command.
composer require pecee/simple-router
The goal of this project is to create a router that is more or less 100% compatible with the Laravel documentation, while remaining as simple as possible, and as easy to integrate and change without compromising either speed or complexity. Being lightweight is the #1 priority.
We've included a simple demo project for the router which can be found in the demo-project folder. This project should give you a basic understanding of how to setup and use simple-php-router project.
Please note that the demo-project only covers how to integrate the simple-php-router in a project without an existing framework. If you are using a framework in your project, the implementation might vary.
You can find the demo-project here: https://github.com/skipperbent/simple-router-demo
What we won't cover:
What we cover:
GET, POST, PUT, PATCH, UPDATE, DELETE) with support for custom multiple verbs.GET, POST and FILE values.composer require pecee/simple-router
If you are using Nginx please make sure that url-rewriting is enabled.
You can easily enable url-rewriting by adding the following configuration for the Nginx configuration-file for the demo-project.
location / {
try_files $uri $uri/ /index.php?$query_string;
}
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 the mod_rewrite module (htaccess support) is enabled in the Apache configuration.
Below is an example of an working .htaccess file used by simple-php-router.
Simply create a new .htaccess file in your projects public directory and paste the contents below in your newly created file. This will redirect all requests to your index.php file (see Configuration section below).
RewriteEngine on
RewriteCond %{SCRIPT_FILENAME} !-f
RewriteCond %{SCRIPT_FILENAME} !-d
RewriteCond %{SCRIPT_FILENAME} !-l
RewriteRule ^(.*)$ index.php/$1
On IIS you have to add some lines your web.config file in the public folder or create a new one. If rewriting is not working for you, please check that your IIS version have included the url rewrite module or download and install them from Microsoft web site.
Below is an example of an working web.config file used by simple-php-router.
Simply create a new web.config file in your projects public directory and paste the contents below in your newly created file. This will redirect all requests to your index.php file (see Configuration section below). If the web.config file already exists, add the <rewrite> section inside the <system.webServer> branch.
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<system.webServer>
<rewrite>
<rules>
<!-- Remove slash '/' from the en of the url -->
<rule name="RewriteRequestsToPublic">
<match url="^(.*)$" />
<conditions logicalGrouping="MatchAll" trackAllCaptures="false">
</conditions>
<action type="Rewrite" url="/{R:0}" />
</rule>
<!-- When requested file or folder don't exists, will request again through index.php -->
<rule name="Imported Rule 1" stopProcessing="true">
<match url="^(.*)$" ignoreCase="true" />
<conditions logicalGrouping="MatchAll">
<add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
<add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
</conditions>
<action type="Rewrite" url="/index.php/{R:1}" appendQueryString="true" />
</rule>
</rules>
</rewrite>
</system.webServer>
</configuration>
If you do not have a favicon.ico file in your project, you can get a NotFoundHttpException (404 - not found).
To add favicon.ico to the IIS ignore-list, add the following line to the <conditions> group:
<add input="{REQUEST_FILENAME}" negate="true" pattern="favicon.ico" ignoreCase="true" />
You can also make one exception for files with some extensions:
<add input="{REQUEST_FILENAME}" pattern="\.ico|\.png|\.css|\.jpg" negate="true" ignoreCase="true" />
If you are using $_SERVER['ORIG_PATH_INFO'], you will get \index.php\ as part of the returned value.
Example:
/index.php/test/mypage.php
Create a new file, name it routes.php and place it in your library folder. This will be the file where you define all the routes for your project.
WARNING: NEVER PLACE YOUR ROUTES.PHP IN YOUR PUBLIC FOLDER!
In your index.php require your newly-created routes.php and call the SimpleRouter::start() method. This will trigger and do the actual routing of the requests.
It's not required, but you can set SimpleRouter::setDefaultNamespace('\Demo\Controllers'); to prefix all routes with the namespace to your controllers. This will simplify things a bit, as you won't have to specify the namespace for your controllers on each route.
This is an example of a basic index.php file:
<?php
use Pecee\SimpleRouter\SimpleRouter;
/* Load external routes file */
require_once 'routes.php';
/**
* The default namespace for route-callbacks, so we don't have to specify it each time.
* Can be overwritten by using the namespace config option on your routes.
*/
SimpleRouter::setDefaultNamespace('\Demo\Controllers');
// Start the routing
SimpleRouter::start();
We recommend that you add these helper functions to your project. These will allow you to access functionality of the router more easily.
To implement the functions below, simply copy the code to a new file and require the file before initializing the router or copy the helpers.php we've included in this library.
<?php
use Pecee\SimpleRouter\SimpleRouter as Router;
use Pecee\Http\Url;
use Pecee\Http\Response;
use Pecee\Http\Request;
/**
* Get url for a route by using either name/alias, class or method name.
*
* The name parameter supports the following values:
* - Route name
* - Controller/resource name (with or without method)
* - Controller class name
*
* When searching for controller/resource by name, you can use this syntax "route.name@method".
* You can also use the same syntax when searching for a specific controller-class "MyController@home".
* If no arguments is specified, it will return the url for the current loaded route.
*
* @param string|null $name
* @param string|array|null $parameters
* @param array|null $getParams
* @return \Pecee\Http\Url
* @throws \InvalidArgumentException
*/
function url(?string $name = null, $parameters = null, ?array $getParams = null): Url
{
return Router::getUrl($name, $parameters, $getParams);
}
/**
* @return \Pecee\Http\Response
*/
function response(): Response
{
return Router::response();
}
/**
* @return \Pecee\Http\Request
*/
function request(): Request
{
return Router::request();
}
/**
* Get input class
* @param string|null $index Parameter index name
* @param string|null $defaultValue Default return value
* @param array ...$methods Default methods
* @return \Pecee\Http\Input\InputHandler|array|string|null
*/
function input($index = null, $defaultValue = null, ...$methods)
{
if ($index !== null) {
return request()->getInputHandler()->value($index, $defaultValue, ...$methods);
}
return request()->getInputHandler();
}
/**
* @param string $url
* @param int|null $code
*/
function redirect(string $url, ?int $code = null): void
{
if ($code !== null) {
response()->httpCode($code);
}
response()->redirect($url);
}
/**
* Get current csrf-token
* @return string|null
*/
function csrf_token(): ?string
{
$baseVerifier = Router::router()->getCsrfVerifier();
if ($baseVerifier !== null) {
return $baseVerifier->getTokenProvider()->getToken();
}
return null;
}
Remember the routes.php file you required in your index.php? This file be where you place all your custom rules for routing.
Below is a very basic example of setting up a route. First parameter is the url which the route should match - next parameter is a Closure or callback function that will be triggered once the route matches.
SimpleRouter::get('/', function() {
return 'Hello world';
});
Here you can see a list over all available routes:
SimpleRouter::get($url, $callback, $settings);
SimpleRouter::post($url, $callback, $settings);
SimpleRouter::put($url, $callback, $settings);
SimpleRouter::patch($url, $callback, $settings);
SimpleRouter::delete($url, $callback, $settings);
SimpleRouter::options($url, $callback, $settings);
Sometimes you might need to create a route that accepts multiple HTTP-verbs. If you need to match all HTTP-verbs you can use the any method.
SimpleRouter::match(['get', 'post'], '/', function() {
// ...
});
SimpleRouter::any('foo', function() {
// ...
});
We've created a simple method which matches GET and POST which is most commonly used:
SimpleRouter::form('foo', function() {
// ...
});
You'll properly wondering by know how you parse parameters from your urls. For example, you might want to capture the users id from an url. You can do so by defining route-parameters.
SimpleRouter::get('/user/{id}', function ($userId) {
return 'User with id: ' . $userId;
});
You may define as many route parameters as required by your route:
SimpleRouter::get('/posts/{post}/comments/{comment}', function ($postId, $commentId) {
// ...
});
Note: Route parameters are always encased within {} braces and should consist of alphabetic characters. Route parameters may not contain a - character. Use an underscore (_) instead.
Occasionally you may need to specify a route parameter, but make the presence of that route parameter optional. You may do so by placing a ? mark after the parameter name. Make sure to give the route's corresponding variable a default value:
SimpleRouter::get('/user/{name?}', function ($name = null) {
return $name;
});
SimpleRouter::get('/user/{name?}', function ($name = 'Simon') {
return $name;
});
You may constrain the format of your route parameters using the where method on a route instance. The where method accepts the name of the parameter and a regular expression defining how the parameter should be constrained:
SimpleRouter::get('/user/{name}', function ($name) {
// ... do stuff
})->where('name', '[A-Za-z]+');
SimpleRouter::get('/user/{id}', function ($id) {
// ... do stuff
})->where('id', '[0-9]+');
SimpleRouter::get('/user/{id}/{name}', function ($id, $name) {
// ... do stuff
})->where(['id' => '[0-9]+', 'name' => '[a-z]+']);
You can define a regular-expression match for the entire route if you wish.
This is useful if you for example are creating a model-box which loads urls from ajax.
The example below is using the following regular expression: /ajax/([\w]+)/?([0-9]+)?/? which basically just matches /ajax/ and exspects the next parameter to be a string - and the next to be a number (but optional).
Matches: /ajax/abc/, /ajax/abc/123/
Won't match: /ajax/
Match groups specified in the regex will be passed on as parameters:
SimpleRouter::all('/ajax/abc/123', function($param1, $param2) {
// param1 = abc
// param2 = 123
})->setMatch('/\/ajax\/([\w]+)\/?([0-9]+)?\/?/is');
By default simple-php-router uses the \w regular expression when matching parameters.
This decision was made with speed and reliability in mind, as this match will match both letters, number and most of the used symbols on the internet.
However, sometimes it can be necessary to add a custom regular expression to match more advanced characters like - etc.
Instead of adding a custom regular expression to all your parameters, you can simply add a global regular expression which will be used on all the parameters on the route.
Note: If you the regular expression to be available across, we recommend using the global parameter on a group as demonstrated in the examples below.
This example will ensure that all parameters use the [\w\-]+ regular expression when parsing.
SimpleRouter::get('/path/{parameter}', 'VideoController@home', ['defaultParameterRegex' => '[\w\-]+']);
You can also apply this setting to a group if you need multiple routes to use your custom regular expression when parsing parameters.
SimpleRouter::group(['defaultParameterRegex' => '[\w\-]+'], function() {
SimpleRouter::get('/path/{parameter}', 'VideoController@home');
});
Named routes allow the convenient generation of URLs or redirects for specific routes. You may specify a name for a route by chaining the name method onto the route definition:
SimpleRouter::get('/user/profile', function () {
// Your code here
})->name('profile');
You can also specify names for Controller-actions:
SimpleRouter::get('/user/profile', 'UserController@profile')->name('profile');
Once you have assigned a name to a given route, you may use the route's name when generating URLs or redirects via the global url helper-function (see helpers section):
// Generating URLs...
$url = url('profile');
If the named route defines parameters, you may pass the parameters as the second argument to the url function. The given parameters will automatically be inserted into the URL in their correct positions:
SimpleRouter::get('/user/{id}/profile', function ($id) {
//
})->name('profile');
$url = url('profile', ['id' => 1]);
For more information on urls, please see the Urls section.
Route groups allow you to share route attributes, such as middleware or namespaces, across a large number of routes without needing to define those attributes on each individual route. Shared attributes are specified in an array format as the first parameter to the SimpleRouter::group method.
To assign middleware to all routes within a group, you may use the middleware key in the group attribute array. Middleware are executed in the order they are listed in the array:
SimpleRouter::group(['middleware' => \Demo\Middleware\Auth::class], function () {
SimpleRouter::get('/', function () {
// Uses Auth Middleware
});
SimpleRouter::get('/user/profile', function () {
// Uses Auth Middleware
});
});
Another common use-case for route groups is assigning the same PHP namespace to a group of controllers using the namespace parameter in the group array:
Group namespaces will only be added to routes with relative callbacks.
For example if your route has an absolute callback like \Demo\Controller\DefaultController@home, the namespace from the route will not be prepended.
To fix this you can make the callback relative by removing the \ in the beginning of the callback.
SimpleRouter::group(['namespace' => 'Admin'], function () {
// Controllers Within The "App\Http\Controllers\Admin" Namespace
});
Route groups may also be used to handle sub-domain routing. Sub-domains may be assigned route parameters just like route urls, allowing you to capture a portion of the sub-domain for usage in your route or controller. The sub-domain may be specified using the domain key on the group attribute array:
SimpleRouter::group(['domain' => '{account}.myapp.com'], function () {
SimpleRouter::get('/user/{id}', function ($account, $id) {
//
});
});
The prefix group attribute may be used to prefix each route in the group with a given url. For example, you may want to prefix all route urls within the group with admin:
SimpleRouter::group(['prefix' => '/admin'], function () {
SimpleRouter::get('/users', function () {
// Matches The "/admin/users" URL
});
});
Partial router groups has the same benefits as a normal group, but supports parameters and are only rendered once the url has matched.
This can be extremely useful in situations, where you only want special routes to be added, when a certain criteria or logic has been met.
NOTE: Use partial groups with caution as routes added within are only rendered and available once the url of the partial-group has matched. This can cause url() not to find urls for the routes added within.
Example:
SimpleRouter::partialGroup('/admin/{applicationId}', function ($applicationId) {
SimpleRouter::get('/', function($applicationId) {
// Matches The "/admin/applicationId" URL
});
});
HTML forms do not support PUT, PATCH or DELETE actions. So, when defining PUT, PATCH or DELETE routes that are called from an HTML form, you will need to add a hidden _method field to the form. The value sent with the _method field will be used as the HTTP request method:
<input type="hidden" name="_method" value="PUT" />
You can access information about the current route loaded by using the following method:
SimpleRouter::request()->getLoadedRoute();
request()->getLoadedRoute();
simple-router supports dependency injection using the php-di library.
Dependency injection allows the framework to automatically "inject" (load) classes added as parameters. This can simplify your code, as you can avoid creating new instances of objects you are using often in your Controllers etc.
Here's a basic example of a controller class using dependency injection:
namespace Demo\Controllers;
class DefaultController {
public function login(User $user): string
{
// ...
}
}
The example above will automatically create a new instance of the User from the $user parameter. This means that the $user class contains a new instance of the User class and we won't need to create a new instance our self.
WARNING: dependency injection can have some negative impact in performance. If you experience any performance issues, we recommend disabling this functionality.
Dependency injection is disabled per default to avoid any performance issues.
Before enabling dependency injection, we recommend that you read the Container configuration section of the php-di documentation. This section covers how to configure php-di to different environments and speed-up the performance.
The example below should ONLY be used on a development environment.
// Create our new php-di container
$container = (new \DI\ContainerBuilder())
->useAutowiring(true)
->build();
// Add our container to simple-router and enable dependency injection
SimpleRouter::enableDependencyInjection($container);
Please check the More reading section of the documentation for useful php-di links and tutorials.
The example below compiles the injections, which can help speed up performance.
Note: You should change the $cacheDir to a cache-storage within your project.
// Cache directory
$cacheDir = sys_get_temp_dir('simple-router');
// Create our new php-di container
$container = (new \DI\ContainerBuilder())
->enableCompilation($cacheDir)
->writeProxiesToFile(true, $cacheDir . '/proxies')
->useAutowiring(true)
->build();
// Add our container to simple-router and enable dependency injection
SimpleRouter::enableDependencyInjection($container);
Please check the More reading section of the documentation for useful php-di links and tutorials.
For more information about dependency injection, configuration and settings - we recommend that you check the php-di documentation or some of the useful links we've gathered below.
You can find many more examples in the routes.php example-file below:
<?php
use Pecee\SimpleRouter\SimpleRouter;
/* Adding custom csrfVerifier here */
SimpleRouter::csrfVerifier(new \Demo\Middlewares\CsrfVerifier());
SimpleRouter::group(['middleware' => \Demo\Middlewares\Site::class, 'exceptionHandler' => \Demo\Handlers\CustomExceptionHandler::class], function() {
SimpleRouter::get('/answers/{id}', 'ControllerAnswers@show', ['where' => ['id' => '[0-9]+']]);
/**
* Restful resource (see IRestController interface for available methods)
*/
SimpleRouter::resource('/rest', ControllerRessource::class);
/**
* Load the entire controller (where url matches method names - getIndex(), postIndex(), putIndex()).
* The url paths will determine which method to render.
*
* For example:
*
* GET /animals => getIndex()
* GET /animals/view => getView()
* POST /animals/save => postSave()
*
* etc.
*/
SimpleRouter::controller('/animals', ControllerAnimals::class);
});
SimpleRouter::get('/page/404', 'ControllerPage@notFound', ['as' => 'page.notfound']);
Any forms posting to POST, PUT or DELETE routes should include the CSRF-token. We strongly recommend that you enable CSRF-verification on your site to maximize security.
You can use the BaseCsrfVerifier to enable CSRF-validation on all request. If you need to disable verification for specific urls, please refer to the "Custom CSRF-verifier" section below.
By default simple-php-router will use the CookieTokenProvider class. This provider will store the security-token in a cookie on the clients machine.
If you want to store the token elsewhere, please refer to the "Creating custom Token Provider" section below.
When you've created your CSRF-verifier you need to tell simple-php-router that it should use it. You can do this by adding the following line in your routes.php file:
Router::csrfVerifier(new \Demo\Middlewares\CsrfVerifier());
When posting to any of the urls that has CSRF-verification enabled, you need post your CSRF-token or else the request will get rejected.
You can get the CSRF-token by calling the helper method:
csrf_token();
You can also get the token directly:
return Router::router()->getCsrfVerifier()->getTokenProvider()->getToken();
The default name/key for the input-field is csrf_token and is defined in the POST_KEY constant in the BaseCsrfVerifier class.
You can change the key by overwriting the constant in your own CSRF-verifier class.
Example:
The example below will post to the current url with a hidden field "csrf_token".
<form method="post" action="<?= url(); ?>">
<input type="hidden" name="csrf_token" value="<?= csrf_token(); ?>">
<!-- other input elements here -->
</form>
Create a new class and extend the BaseCsrfVerifier middleware class provided by default with the simple-php-router library.
Add the property except with an array of the urls to the routes you want to exclude/whitelist from the CSRF validation.
Using * at the end for the url will match the entire url.
Here's a basic example on a CSRF-verifier class:
namespace Demo\Middlewares;
use Pecee\Http\Middleware\BaseCsrfVerifier;
class CsrfVerifier extends BaseCsrfVerifier
{
/**
* CSRF validation will be ignored on the following urls.
*/
protected $except = ['/api/*'];
}
By default the BaseCsrfVerifier will use the CookieTokenProvider to store the token in a cookie on the clients machine.
If you need to store the token elsewhere, you can do that by creating your own class and implementing the ITokenProvider class.
class SessionTokenProvider implements ITokenProvider
{
/**
* Refresh existing token
*/
public function refresh(): void
{
// Implement your own functionality here...
}
/**
* Validate valid CSRF token
*
* @param string $token
* @return bool
*/
public function validate($token): bool
{
// Implement your own functionality here...
}
/**
* Get token token
*
* @param string|null $defaultValue
* @return string|null
*/
public function getToken(?string $defaultValue = null): ?string
{
// Implement your own functionality here...
}
}
Next you need to set your custom ITokenProvider implementation on your BaseCsrfVerifier class in your routes file:
$verifier = new \dscuz\Middleware\CsrfVerifier();
$verifier->setTokenProvider(new SessionTokenProvider());
Router::csrfVerifier($verifier);
Middlewares are classes that loads before the route is rendered. A middleware can be used to verify that a user is logged in - or to set parameters specific for the current request/route. Middlewares must implement the IMiddleware interface.
namespace Demo\Middlewares;
use Pecee\Http\Middleware\IMiddleware;
use Pecee\Http\Request;
class CustomMiddleware implements IMiddleware {
public function handle(Request $request): void
{
// Authenticate user, will be available using request()->user
$request->user = User::authenticate();
// If authentication failed, redirect request to user-login page.
if($request->user === null) {
$request->setRewriteUrl(url('user.login'));
}
}
}
ExceptionHandler are classes that handles all exceptions. ExceptionsHandlers must implement the IExceptionHandler interface.
If you simply want to catch a 404 (page not found) etc. you can use the Router::error($callback) static helper method.
This will add a callback method which is fired whenever an error occurs on all routes.
The basic example below simply redirect the page to /not-found if an NotFoundHttpException (404) occurred.
The code should be placed in the file that contains your routes.
Router::get('/not-found', 'PageController@notFound');
Router::error(function(Request $request, \Exception $exception) {
if($exception instanceof NotFoundHttpException && $exception->getCode() === 404) {
response()->redirect('/not-found');
}
});
This is a basic example of an ExceptionHandler implementation (please see "Easily overwrite route about to be loaded" for examples on how to change callback).
namespace Demo\Handlers;
use Pecee\Http\Request;
use Pecee\SimpleRouter\Handlers\IExceptionHandler;
use Pecee\SimpleRouter\Exceptions\NotFoundHttpException;
class CustomExceptionHandler implements IExceptionHandler
{
public function handleError(Request $request, \Exception $error): void
{
/* You can use the exception handler to format errors depending on the request and type. */
if ($request->getUrl()->contains('/api')) {
response()->json([
'error' => $error->getMessage(),
'code' => $error->getCode(),
]);
}
/* The router will throw the NotFoundHttpException on 404 */
if($error instanceof NotFoundHttpException) {
// Render custom 404-page
$request->setRewriteCallback('Demo\Controllers\PageController@notFound');
return;
}
throw $error;
}
}
By default all controller and resource routes will use a simplified version of their url as name.
You easily use the url() shortcut helper function to retrieve urls for your routes or manipulate the current url.
url() will return a Url object which will return a string when rendered, so it can be used safely in templates etc. but
contains all the useful helpers methods in the Url class like contains, indexOf etc.
Check the Useful url tricks below.
It has never been easier to get and/or manipulate the current url.
The example below shows you how to get the current url:
# output: /current-url
url();
SimpleRouter::get('/product-view/{id}', 'ProductsController@show', ['as' => 'product']);
# output: /product-view/22/?category=shoes
url('product', ['id' => 22], ['category' => 'shoes']);
# output: /product-view/?category=shoes
url('product', null, ['category' => 'shoes']);
SimpleRouter::controller('/images', ImagesController::class, ['as' => 'picture']);
# output: /images/view/?category=shows
url('picture@getView', null, ['category' => 'shoes']);
# output: /images/view/?category=shows
url('picture', 'getView', ['category' => 'shoes']);
# output: /images/view/
url('picture', 'view');
SimpleRouter::get('/product-view/{id}', 'ProductsController@show', ['as' => 'product']);
SimpleRouter::controller('/images', 'ImagesController');
# output: /product-view/22/?category=shoes
url('ProductsController@show', ['id' => 22], ['category' => 'shoes']);
# output: /images/image/?id=22
url('ImagesController@getImage', null, ['id' => 22]);
SimpleRouter::controller('gadgets', GadgetsController::class, ['names' => ['getIphoneInfo' => 'iphone']]);
url('gadgets.iphone');
# output
# /gadgets/iphoneinfo/
SimpleRouter::resource('/phones', PhonesController::class);
# output: /phones/
url('phones');
# output: /phones/
url('phones.index');
# output: /phones/create/
url('phones.create');
# output: /phones/edit/
url('phones.edit');
You can easily manipulate the query-strings, by adding your get param arguments.
# output: /current-url?q=cars
url(null, null, ['q' => 'cars']);
You can remove a query-string parameter by setting the value to null.
The example below will remove any query-string parameter named q from the url but keep all others query-string parameters:
$url = url()->removeParam('q');
For more information please check the Useful url tricks section of the documentation.
Calling url will always return a Url object. Upon rendered it will return a string of the relative url, so it's safe to use in templates etc.
However this allow us to use the useful methods on the Url object like indexOf and contains or retrieve specific parts of the url like the path, querystring parameters, host etc. You can also manipulate the url like removing- or adding parameters, changing host and more.
In the example below, we check if the current url contains the /api part.
if(url()->contains('/api')) {
// ... do stuff
}
As mentioned earlier, you can also use the Url object to show specific parts of the url or control what part of the url you want.
# Grab the query-string parameter id from the current-url.
$id = url()->getParam('id');
# Get the absolute url for the current url.
$absoluteUrl = url()->getAbsoluteUrl();
For more available methods please check the Pecee\Http\Url class.
simple-router offers libraries and helpers that makes it easy to manage and manipulate input-parameters like $_POST, $_GET and $_FILE.
You can use the InputHandler class to easily access and manage parameters from your request. The InputHandler class offers extended features such as copying/moving uploaded files directly on the object, getting file-extension, mime-type etc.
input($index, $defaultValue, ...$methods);
To quickly get a value from a parameter, you can use the input helper function.
This will automatically trim the value and ensure that it's not empty. If it's empty the $defaultValue will be returned instead.
Note:
This function returns a string unless the parameters are grouped together, in that case it will return an array of values.
Example:
This example matches both POST and GET request-methods and if name is empty the default-value "Guest" will be returned.
$name = input('name', 'Guest', 'post', 'get');
When dealing with file-uploads it can be useful to retrieve the raw parameter object.
Search for object with default-value across multiple or specific request-methods:
The example below will return an InputItem object if the parameter was found or return the $defaultValue. If parameters are grouped, it will return an array of InputItem objects.
$object = input()->find($index, $defaultValue = null, ...$methods);
Getting specific $_GET parameter as InputItem object:
The example below will return an InputItem object if the parameter was found or return the $defaultValue. If parameters are grouped, it will return an array of InputItem objects.
$object = input()->get($index, $defaultValue = null);
Getting specific $_POST parameter as InputItem object:
The example below will return an InputItem object if the parameter was found or return the $defaultValue. If parameters are grouped, it will return an array of InputItem objects.
$object = input()->post($index, $defaultValue = null);
Getting specific $_FILE parameter as InputFile object:
The example below will return an InputFile object if the parameter was found or return the $defaultValue. If parameters are grouped, it will return an array of InputFile objects.
$object = input()->file($index, $defaultValue = null);
/**
* Loop through a collection of files uploaded from a form on the page like this
* <input type="file" name="images[]" />
*/
/* @var $image \Pecee\Http\Input\InputFile */
foreach(input()->file('images', []) as $image)
{
if($image->getMime() === 'image/jpeg')
{
$destinationFilname = sprintf('%s.%s', uniqid(), $image->getExtension());
$image->move(sprintf('/uploads/%s', $destinationFilename));
}
}
# Get all
$values = input()->all();
# Only match specific keys
$values = input()->all([
'company_name',
'user_id'
]);
All object implements the IInputItem interface and will always contain these methods:
getIndex() - returns the index/key of the input.getName() - returns a human friendly name for the input (company_name will be Company Name etc).getValue() - returns the value of the input.InputFile has the same methods as above along with some other file-specific methods like:
getFilename - get the filename.getTmpName() - get file temporary name.getSize() - get file size.move($destination) - move file to destination.getContents() - get file content.getType() - get mime-type for file.getError() - get file upload error.hasError() - returns bool if an error occurred while uploading (if getError is not 0).toArray() - returns raw arrayThis section will help you understand how to register your own callbacks to events in the router. It will also cover the basics of event-handlers; how to use the handlers provided with the router and how to create your own custom event-handlers.
This section contains all available events that can be registered using the EventHandler.
All event callbacks will retrieve a EventArgument object as parameter. This object contains easy access to event-name, router- and request instance and any special event-arguments related to the given event. You can see what special event arguments each event returns in the list below.
| Name | Special arguments | Description |
| ------------- |----------- | ---- |
| EVENT_ALL | - | Fires when a event is triggered. |
| EVENT_INIT | - | Fires when router is initializing and before routes are loaded. |
| EVENT_LOAD | loadedRoutes | Fires when all routes has been loaded and rendered, just before the output is returned. |
| EVENT_ADD_ROUTE | route | Fires when route is added to the router. |
| EVENT_REWRITE | rewriteUrlrewriteRoute | Fires when a url-rewrite is and just before the routes are re-initialized. |
| EVENT_BOOT | bootmanagers | Fires when the router is booting. This happens just before boot-managers are rendered and before any routes has been loaded. |
| EVENT_RENDER_BOOTMANAGER | bootmanagersbootmanager | Fires before a boot-manager is rendered. |
| EVENT_LOAD_ROUTES | routes | Fires when the router is about to load all routes. |
| EVENT_FIND_ROUTE | name | Fires whenever the findRoute method is called within the Router. This usually happens when the router tries to find routes that contains a certain url, usually after the EventHandler::EVENT_GET_URL event. |
| EVENT_GET_URL | nameparametersgetParams | Fires whenever the Router::getUrl method or url-helper function is called and the router tries to find the route. |
| EVENT_MATCH_ROUTE | route | Fires when a route is matched and valid (correct request-type etc). and before the route is rendered. |
| EVENT_RENDER_ROUTE | route | Fires before a route is rendered. |
| EVENT_LOAD_EXCEPTIONS | exceptionexceptionHandlers | Fires when the router is loading exception-handlers. |
| EVENT_RENDER_EXCEPTION | exceptionexceptionHandlerexceptionHandlers | Fires before the router is rendering a exception-handler. |
| EVENT_RENDER_MIDDLEWARES | routemiddlewares | Fires before middlewares for a route is rendered. |
| EVENT_RENDER_CSRF | csrfVerifier | Fires before the CSRF-verifier is rendered. |
To register a new event you need to create a new instance of the EventHandler object. On this object you can add as many callbacks as you like by calling the registerEvent method.
When you've registered events, make sure to add it to the router by calling
SimpleRouter::addEventHandler(). We recommend that you add your event-handlers within your routes.php.
Example:
use Pecee\SimpleRouter\Handlers\EventHandler;
use Pecee\SimpleRouter\Event\EventArgument;
// --- your routes goes here ---
$eventHandler = new EventHandler();
// Add event that fires when a route is rendered
$eventHandler->register(EventHandler::EVENT_RENDER_ROUTE, function(EventArgument $argument) {
// Get the route by using the special argument for this event.
$route = $argument->route;
// DO STUFF...
});
SimpleRouter::addEventHandler($eventHandler);
EventHandler is the class that manages events and must inherit from the IEventHandler interface. The handler knows how to handle events for the given handler-type.
Most of the time the basic \Pecee\SimpleRouter\Handler\EventHandler class will be more than enough for most people as you simply register an event which fires when triggered.
Let's go over how to create your very own event-handler class.
Below is a basic example of a custom event-handler called DatabaseDebugHandler. The idea of the sample below is to logs all events to the database when triggered. Hopefully it will be enough to give you an idea on how the event-handlers work.
namespace Demo\Handlers;
use Pecee\SimpleRouter\Event\EventArgument;
use Pecee\SimpleRouter\Router;
class DatabaseDebugHandler implements IEventHandler
{
/**
* Debug callback
* @var \Closure
*/
protected $callback;
public function __construct()
{
$this->callback = function (EventArgument $argument) {
// todo: store log in database
};
}
/**
* Get events.
*
* @param string|null $name Filter events by name.
* @return array
*/
public function getEvents(?string $name): array
{
return [
$name => [
$this->callback,
],
];
}
/**
* Fires any events registered with given event-name
*
* @param Router $router Router instance
* @param string $name Event name
* @param array ...$eventArgs Event arguments
*/
public function fireEvents(Router $router, string $name, ...$eventArgs): void
{
$callback = $this->callback;
$callback(new EventArgument($router, $eventArgs));
}
/**
* Set debug callback
*
* @param \Closure $event
*/
public function setCallback(\Closure $event): void
{
$this->callback = $event;
}
}
Sometimes it can be useful to manipulate the route about to be loaded.
simple-php-router allows you to easily manipulate and change the routes which are about to be rendered.
All information about the current route is stored in the \Pecee\SimpleRouter\Router instance's loadedRoute property.
For easy access you can use the shortcut helper function request() instead of calling the class directly \Pecee\SimpleRouter\SimpleRouter::router().
request()->setRewriteCallback('Example\MyCustomClass@hello');
// -- or you can rewrite by url --
request()->setRewriteUrl('/my-rewrite-url');
Sometimes it can be necessary to keep urls stored in the database, file or similar. In this example, we want the url /my-cat-is-beatiful to load the route /article/view/1 which the router knows, because it's defined in the routes.php file.
To interfere with the router, we create a class that implements the IRouterBootManager interface. This class will be loaded before any other rules in routes.php and allow us to "change" the current route, if any of our criteria are fulfilled (like coming from the url /my-cat-is-beatiful).
use Pecee\Http\Request;
use Pecee\SimpleRouter\IRouterBootManager;
use Pecee\SimpleRouter\Router;
class CustomRouterRules implement IRouterBootManager
{
/**
* Called when router is booting and before the routes is loaded.
*
* @param \Pecee\SimpleRouter\Router $router
* @param \Pecee\Http\Request $request
*/
public function boot(\Pecee\SimpleRouter\Router $router, \Pecee\Http\Request $request): void
{
$rewriteRules = [
'/my-cat-is-beatiful' => '/article/view/1',
'/horses-are-great' => '/article/view/2',
];
foreach($rewriteRules as $url => $rule) {
// If the current url matches the rewrite url, we use our custom route
if($request->getUrl()->getPath() === $url) {
$request->setRewriteUrl($rule);
}
}
}
}
The above should be pretty self-explanatory and can easily be changed to loop through urls store in the database, file or cache.
What happens is that if the current route matches the route defined in the index of our $rewriteRules array, we set the route to the array value instead.
By doing this the route will now load the url /article/view/1 instead of /my-cat-is-beatiful.
The last thing we need to do, is to add our custom boot-manager to the routes.php file. You can create as many bootmanagers as you like and easily add them in your routes.php file.
SimpleRouter::addBootManager(new CustomRouterRules());
The SimpleRouter class referenced in the previous example, is just a simple helper class that knows how to communicate with the Router class.
If you are up for a challenge, want the full control or simply just want to create your own Router helper class, this example is for you.
use \Pecee\SimpleRouter\Router;
use \Pecee\SimpleRouter\Route\RouteUrl;
/* Create new Router instance */
$router = new Router();
$route = new RouteUrl('/answer/1', function() {
die('this callback will match /answer/1');
});
$route->addMiddleware(\Demo\Middlewares\AuthMiddleware::class);
$route->setNamespace('\Demo\Controllers');
$route->setPrefix('v1');
/* Add the route to the router */
$router->addRoute($route);
This section contains advanced tips & tricks on extending the usage for parameters.
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 like loading a custom routes.php file or add debugging information etc.
namespace Demo;
use Pecee\SimpleRouter\SimpleRouter;
class Router extends SimpleRouter {
public static function start() {
// change this to whatever makes sense in your project
require_once 'routes.php';
// change default namespace for all routes
parent::setDefaultNamespace('\Demo\Controllers');
// Do initial stuff
parent::start();
}
}
This section will go into details on how to debug the router and answer some of the commonly asked questions- and issues.
This section will go over common issues and how to resolve them.
Often people experience this issue when one or more parameters contains special characters. The router uses a sparse regular-expression that matches letters from a-z along with numbers when matching parameters, to improve performance.
All other characters has to be defined via the defaultParameterRegex option on your route.
You can read more about adding your own custom regular expression for matching parameters by clicking here.
The router will match routes in the order they're added.
It's possible to render multiple routes.
If you want the router to stop when a route is matched, you simply return a value in your callback or stop the execution manually (using response()->json() etc.).
Any returned objects that implements the __toString() magic method will also prevent other routes from being rendered.
Using the library on a sub-path like localhost/project/ is not officially supported, however it is possible to get it working quite easily.
Add an event that appends your sub-path when a new loadable route is added.
Example:
// ... your routes.php file
if($isRunningLocally) {
$eventHandler = new EventHandler();
$eventHandler->register(EventHandler::EVENT_ADD_ROUTE, function (EventArgument $arg) use (&$status) {
if ($arg->route instanceof \Pecee\SimpleRouter\Route\LoadableRoute) {
$arg->route->prependUrl('/local-path');
}
});
TestRouter::addEventHandler($eventHandler);
}
This section will show you how to write unit-tests for the router, view useful debugging information and answer some of the frequently asked questions.
It will also covers how to report any issue you might encounter.
The easiest and fastest way to debug any issues with the router, is to create a unit-test that represents the issue you are experiencing.
Unit-tests use a special TestRouter class, which simulates a request-method and requested url of a browser.
The TestRouter class can return the output directly or render a route silently.
public function testUnicodeCharacters()
{
// Add route containing two optional paramters with special spanish characters like "í".
TestRouter::get('/cursos/listado/{listado?}/{category?}', 'DummyController@method1', ['defaultParameterRegex' => '[\w\p{L}\s-]+']);
// Start the routing and simulate the url "/cursos/listado/especialidad/cirugía local".
TestRouter::debugNoReset('/cursos/listado/especialidad/cirugía local', 'GET');
// Verify that the url for the loaded route matches the expected route.
$this->assertEquals('/cursos/listado/{listado?}/{category?}/', TestRouter::router()->getRequest()->getLoadedRoute()->getUrl());
// Start the routing and simulate the url "/test/Dermatología" using "GET" as request-method.
TestRouter::debugNoReset('/test/Dermatología', 'GET');
// Another route containing one parameter with special spanish characters like "í".
TestRouter::get('/test/{param}', 'DummyController@method1', ['defaultParameterRegex' => '[\w\p{L}\s-\í]+']);
// Get all parameters parsed by the loaded route.
$parameters = TestRouter::request()->getLoadedRoute()->getParameters();
// Check that the parameter named "param" matches the exspected value.
$this->assertEquals('Dermatología', $parameters['param']);
// Add route testing danish special characters like "ø".
TestRouter::get('/category/økse', 'DummyController@method1', ['defaultParameterRegex' => '[\w\ø]+']);
// Start the routing and simulate the url "/kategory/økse" using "GET" as request-method.
TestRouter::debugNoReset('/category/økse', 'GET');
// Validate that the URL of the loaded-route matches the expected url.
$this->assertEquals('/category/økse/', TestRouter::router()->getRequest()->getLoadedRoute()->getUrl());
// Reset the router, so other tests wont inherit settings or the routes we've added.
TestRouter::router()->reset();
}
Depending on your test, you can use the methods below when rendering routes in your unit-tests.
| Method | Description |
| ------------- |-------------|
| TestRouter::debug($url, $method) | Will render the route without returning anything. Exceptions will be thrown and the router will be reset automatically. |
| TestRouter::debugOutput($url, $method) | Will render the route and return any value that the route might output. Manual reset required by calling TestRouter::router()->reset(). |
| TestRouter::debugNoReset($url, $method); | Will render the route without resetting the router. Useful if you need to get loaded route, parameters etc. from the router. Manual reset required by calling TestRouter::router()->reset(). |
The library can output debug-information, which contains information like loaded routes, the parsed request-url etc. It also contains info which are important when reporting a new issue like PHP-version, library version, server-variables, router debug log etc.
You can activate the debug-information by calling the alternative start-method.
The example below will start the routing an return array with debugging-information
Example:
$debugInfo = SimpleRouter::startDebug();
echo sprintf('<pre>%s</pre>', var_export($debugInfo));
exit;
The example above will provide you with an output containing:
| Key | Description |
| ------------- |------------- |
| url | The parsed request-uri. This url should match the url in the browser.|
| method | The browsers request method (example: GET, POST, PUT, PATCH, DELETE etc).|
| host | The website host (example: domain.com).|
| loaded_routes | List of all the routes that matched the url and that has been rendered/loaded. |
| all_routes | All available routes |
| boot_managers | All available BootManagers |
| csrf_verifier | CsrfVerifier class |
| log | List of debug messages/log from the router. |
| router_output | The rendered callback output from the router. |
| library_version | The version of simple-php-router you are using. |
| php_version | The version of PHP you are using. |
| server_params | List of all $_SERVER variables/headers. |
You can activate benchmark debugging/logging by calling setDebugEnabled method on the Router instance.
You have to enable debugging BEFORE starting the routing.
Example:
SimpleRouter::router()->setDebugEnabled(true);
SimpleRouter::start();
When the routing is complete, you can get the debug-log by calling the getDebugLog() on the Router instance. This will return an array of log-messages each containing execution time, trace info and debug-message.
Example:
$messages = SimpleRouter::router()->getDebugLog();
Before reporting your issue, make sure that the issue you are experiencing aren't already answered in the Common errors section or by searching the closed issues page on GitHub.
To avoid confusion and to help you resolve your issue as quickly as possible, you should provide a detailed explanation of the problem you are experiencing.
Copy and paste the template below into the description of your new issue and replace it with your own information.
You can check the Debug information section to see how to generate the debug-info.
Remember that a more detailed issue- description and debug-info might suck to write, but it will help others understand- and resolve your issue without asking for the information.
Note: please be as detailed as possible in the description when creating a new issue. This will help others to more easily understand- and solve your issue. Providing the necessary steps to reproduce the error within your description, adding useful debugging info etc. will help others quickly resolve the issue you are reporting.
If the library is missing a feature that you need in your project or if you have feedback, we'd love to hear from you. Feel free to leave us feedback by creating a new issue.
Experiencing an issue?
Please refer to our Help and support section in the documentation before reporting a new issue.
Please try to follow the PSR-2 codestyle guidelines.
Please create your pull requests to the development base that matches the version number you want to change.
For example when pushing changes to version 3, the pull request should use the v3-development base/branch.
Create detailed descriptions for your commits, as these will be used in the changelog for new releases.
When changing existing functionality, please ensure that the unit-tests working.
When adding new stuff, please remember to add new unit-tests for the functionality.
This is some sites that uses the simple-router project in production.
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.