PHPackages sn01615/bramus-router - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Framework](/categories/framework) 4. / 5. sn01615/bramus-router ActiveLibrary[Framework](/categories/framework) sn01615/bramus-router ===================== A lightweight and simple object oriented PHP Router v1.6.3(6y ago)027MITPHPPHP >=5.3.0 Since Jun 7Pushed 6y agoCompare [ Source](https://github.com/sn01615/router)[ Packagist](https://packagist.org/packages/sn01615/bramus-router)[ Docs](https://github.com/bramus/router)[ RSS](/packages/sn01615-bramus-router/feed)WikiDiscussions master Synced 2mo ago READMEChangelog (2)Dependencies (3)Versions (3)Used By (0) bramus/router ============= [](#bramusrouter) [![Build Status](https://camo.githubusercontent.com/4700d3503f92f6b186e7d277be2684ce1a36836ef9c4d68e246ba525e67ce995/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f6272616d75732f726f757465722e7376673f7374796c653d666c61742d737175617265)](http://travis-ci.org/bramus/router) [![Source](https://camo.githubusercontent.com/edaf1ef1602a5c57018e5356232994591b148253caabf243ed7d60625ab91e14/687474703a2f2f696d672e736869656c64732e696f2f62616467652f736f757263652d6272616d75732f726f757465722d626c75652e7376673f7374796c653d666c61742d737175617265)](https://github.com/bramus/router) [![Version](https://camo.githubusercontent.com/80ff90ce89f5454e872a2040a632ea0853e37283cf52c0cdbea2ca9637c1bd38/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6272616d75732f726f757465722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/bramus/router) [![Downloads](https://camo.githubusercontent.com/cf4f808df013571eb95c502944bbc6b548e14e1558d81d6992caf953b62e92a2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6272616d75732f726f757465722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/bramus/router/stats) [![License](https://camo.githubusercontent.com/b421b89049dad6b712e371d443cd25269c661f36171b998aa8d492f041b1a138/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6272616d75732f726f757465722e7376673f7374796c653d666c61742d737175617265)](https://github.com/bramus/router/blob/master/LICENSE) A lightweight and simple object oriented PHP Router. Built by Bram(us) Van Damme *()* and [Contributors](https://github.com/bramus/router/graphs/contributors) Features -------- [](#features) - Supports `GET`, `POST`, `PUT`, `DELETE`, `OPTIONS`, `PATCH` and `HEAD` request methods - [Routing shorthands such as `get()`, `post()`, `put()`, …](#routing-shorthands) - [Static Route Patterns](#route-patterns) - Dynamic Route Patterns: [Dynamic PCRE-based Route Patterns](#dynamic-pcre-based-route-patterns) or [Dynamic Placeholder-based Route Patterns](#dynamic-placeholder-based-route-patterns) - [Optional Route Subpatterns](#optional-route-subpatterns) - [Supports `X-HTTP-Method-Override` header](#overriding-the-request-method) - [Subrouting / Mounting Routes](#subrouting--mounting-routes) - [Allowance of `Class@Method` calls](#classmethod-calls) - [Custom 404 handling](#custom-404) - [Before Route Middlewares](#before-route-middlewares) - [Before Router Middlewares / Before App Middlewares](#before-router-middlewares) - [After Router Middleware / After App Middleware (Finish Callback)](#after-router-middleware--run-callback) - [Works fine in subfolders](#subfolder-support) Prerequisites/Requirements -------------------------- [](#prerequisitesrequirements) - PHP 5.3 or greater - [URL Rewriting](https://gist.github.com/bramus/5332525) Installation ------------ [](#installation) Installation is possible using Composer ``` composer require bramus/router ~1.6 ``` Demo ---- [](#demo) A demo is included in the `demo` subfolder. Serve it using your favorite web server, or using PHP 5.4+'s built-in server by executing `php -S localhost:8080` on the shell. A `.htaccess` for use with Apache is included. Additionally a demo of a mutilingual router is also included. This can be found in the `demo-multilang` subfolder and can be ran in the same manner as the normal demo. Usage ----- [](#usage) Create an instance of `\Bramus\Router\Router`, define some routes onto it, and run it. ``` // Require composer autoloader require __DIR__ . '/vendor/autoload.php'; // Create Router instance $router = new \Bramus\Router\Router(); // Define routes // ... // Run it! $router->run(); ``` ### Routing [](#routing) Hook **routes** (a combination of one or more HTTP methods and a pattern) using `$router->match(method(s), pattern, function)`: ``` $router->match('GET|POST', 'pattern', function() { … }); ``` `bramus/router` supports `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD` *(see [note](#a-note-on-making-head-requests))*, and `OPTIONS` HTTP request methods. Pass in a single request method, or multiple request methods separated by `|`. When a route matches against the current URL (e.g. `$_SERVER['REQUEST_URI']`), the attached **route handling function** will be executed. The route handling function must be a [callable](http://php.net/manual/en/language.types.callable.php). Only the first route matched will be handled. When no matching route is found, a 404 handler will be executed. ### Routing Shorthands [](#routing-shorthands) Shorthands for single request methods are provided: ``` $router->get('pattern', function() { /* ... */ }); $router->post('pattern', function() { /* ... */ }); $router->put('pattern', function() { /* ... */ }); $router->delete('pattern', function() { /* ... */ }); $router->options('pattern', function() { /* ... */ }); $router->patch('pattern', function() { /* ... */ }); ``` You can use this shorthand for a route that can be accessed using any method: ``` $router->all('pattern', function() { … }); ``` Note: Routes must be hooked before `$router->run();` is being called. Note: There is no shorthand for `match()` as `bramus/router` will internally re-route such requrests to their equivalent `GET` request, in order to comply with RFC2616 *(see [note](#a-note-on-making-head-requests))*. ### Route Patterns [](#route-patterns) Route Patterns can be static or dynamic: - **Static Route Patterns** contain no dynamic parts and must match exactly against the `path` part of the current URL. - **Dynamic Route Patterns** contain dynamic parts that can vary per request. The varying parts are named **subpatterns** and are defined using either Perl-compatible regular expressions (PCRE) or by using **placeholders** #### Static Route Patterns [](#static-route-patterns) A static route pattern is a regular string representing a URI. It will be compared directly against the `path` part of the current URL. Examples: - `/about` - `/contact` Usage Examples: ``` // This route handling function will only be executed when visiting http(s)://www.example.org/about $router->get('/about', function($name) { echo 'About Page Contents'; }); ``` #### Dynamic PCRE-based Route Patterns [](#dynamic-pcre-based-route-patterns) This type of Route Patterns contain dynamic parts which can vary per request. The varying parts are named **subpatterns** and are defined using regular expressions. Examples: - `/movies/(\d+)` - `/profile/(\w+)` Commonly used PCRE-based subpatterns within Dynamic Route Patterns are: - `\d+` = One or more digits (0-9) - `\w+` = One or more word characters (a-z 0-9 \_) - `[a-z0-9_-]+` = One or more word characters (a-z 0-9 \_) and the dash (-) - `.*` = Any character (including `/`), zero or more - `[^/]+` = Any character but `/`, one or more Note: The [PHP PCRE Cheat Sheet](https://www.cs.washington.edu/education/courses/190m/12sp/cheat-sheets/php-regex-cheat-sheet.pdf) might come in handy. The **subpatterns** defined in Dynamic PCRE-based Route Patterns are converted to parameters which are passed into the route handling function. Prerequisite is that these subpatterns need to be defined as **parenthesized subpatterns**, which means that they should be wrapped between parens: ``` // Bad $router->get('/hello/\w+', function($name) { echo 'Hello ' . htmlentities($name); }); // Good $router->get('/hello/(\w+)', function($name) { echo 'Hello ' . htmlentities($name); }); ``` Note: The leading `/` at the very beginning of a route pattern is not mandatory, but is recommended. When multiple subpatterns are defined, the resulting **route handling parameters** are passed into the route handling function in the order they are defined in: ``` $router->get('/movies/(\d+)/photos/(\d+)', function($movieId, $photoId) { echo 'Movie #' . $movieId . ', photo #' . $photoId); }); ``` #### Dynamic Placeholder-based Route Patterns [](#dynamic-placeholder-based-route-patterns) This type of Route Patterns are the same as **Dynamic PCRE-based Route Patterns**, but with one difference: they don't use regexes to do the pattern matching but they use the more easy **placeholders** instead. Placeholders are strings surrounded by curly braces, e.g. `{name}`. You don't need to add parens around placeholders. Examples: - `/movies/{id}` - `/profile/{username}` Placeholders are easier to use than PRCEs, but offer you less control as they internally get translated to a PRCE that matches any character (`.*`). ``` $router->get('/movies/{movieId}/photos/{photoId}', function($movieId, $photoId) { echo 'Movie #' . $movieId . ', photo #' . $photoId); }); ``` Note: the name of the placeholder does not need to match with the name of the parameter that is passed into the route handling function: ``` $router->get('/movies/{foo}/photos/{bar}', function($movieId, $photoId) { echo 'Movie #' . $movieId . ', photo #' . $photoId); }); ``` ### Optional Route Subpatterns [](#optional-route-subpatterns) Route subpatterns can be made optional by making the subpatterns optional by adding a `?` after them. Think of blog URLs in the form of `/blog(/year)(/month)(/day)(/slug)`: ``` $router->get( '/blog(/\d+)?(/\d+)?(/\d+)?(/[a-z0-9_-]+)?', function($year = null, $month = null, $day = null, $slug = null) { if (!$year) { echo 'Blog overview'; return; } if (!$month) { echo 'Blog year overview'; return; } if (!$day) { echo 'Blog month overview'; return; } if (!$slug) { echo 'Blog day overview'; return; } echo 'Blogpost ' . htmlentities($slug) . ' detail'; } ); ``` The code snippet above responds to the URLs `/blog`, `/blog/year`, `/blog/year/month`, `/blog/year/month/day`, and `/blog/year/month/day/slug`. Note: With optional parameters it is important that the leading `/` of the subpatterns is put inside the subpattern itself. Don't forget to set default values for the optional parameters. The code snipped above unfortunately also responds to URLs like `/blog/foo` and states that the overview needs to be shown - which is incorrect. Optional subpatterns can be made successive by extending the parenthesized subpatterns so that they contain the other optional subpatterns: The pattern should resemble `/blog(/year(/month(/day(/slug))))` instead of the previous `/blog(/year)(/month)(/day)(/slug)`: ``` $router->get('/blog(/\d+(/\d+(/\d+(/[a-z0-9_-]+)?)?)?)?', function($year = null, $month = null, $day = null, $slug = null) { // ... }); ``` Note: It is highly recommended to **always** define successive optional parameters. To make things complete use [quantifiers](http://www.php.net/manual/en/regexp.reference.repetition.php) to require the correct amount of numbers in the URL: ``` $router->get('/blog(/\d{4}(/\d{2}(/\d{2}(/[a-z0-9_-]+)?)?)?)?', function($year = null, $month = null, $day = null, $slug = null) { // ... }); ``` ### Subrouting / Mounting Routes [](#subrouting--mounting-routes) Use `$router->mount($baseroute, $fn)` to mount a collection of routes onto a subroute pattern. The subroute pattern is prefixed onto all following routes defined in the scope. e.g. Mounting a callback `$fn` onto `/movies` will prefix `/movies` onto all following routes. ``` $router->mount('/movies', function() use ($router) { // will result in '/movies/' $router->get('/', function() { echo 'movies overview'; }); // will result in '/movies/id' $router->get('/(\d+)', function($id) { echo 'movie id ' . htmlentities($id); }); }); ``` or ``` $router->ns('Admin')->prefix('/admin')->group(function (\Bramus\Router\Router $router) { $router->get('login', 'LoginController@login'); }); $router->prefix('/novel')->get('/nothing', function () { echo 'yes'; }); $router->ns('Admin')->prefix('/admin')->get('/login', 'LoginController@login1'); $router->get('/login', 'LoginController@login2'); $router->ns('Admin')->prefix('/admin')->group(function (\Bramus\Router\Router $router) { $router->get('login', 'LoginController@login3'); $router->ns('Novel')->prefix('/novel')->group(function (\Bramus\Router\Router $router) { $router->get('info', 'NovelController@getNovelInfo'); }); }); ``` Nesting of subroutes is possible, just define a second `$router->mount()` in the callable that's already contained within a preceding `$router->mount()`. ### `Class@Method` calls [](#classmethod-calls) We can route to the class action like so: ``` $router->get('/(\d+)', '\App\Controllers\User@showProfile'); ``` When a request matches the specified route URI, the `showProfile` method on the `User` class will be executed. The defined route parameters will be passed to the class method. The method can be static or non-static. In case of a non-static method, a new instance of the class will be created. If most/all of your handling classes are in one and the same namespace, you can set the default namespace to use on your router instance via `setNamespace()` ``` $router->setNamespace('\App\Controllers'); $router->get('/users/(\d+)', 'User@showProfile'); $router->get('/cars/(\d+)', 'Car@showProfile'); ``` ### `Class::Method` calls [](#classmethod-calls-1) We can route to the class static method like so: ``` $router->get('/(\d+)', '\App\Controllers\User::showProfile'); ``` ### Sub-Domain [](#sub-domain) ``` $router->domain('admin.router.com')->group(function (\Bramus\Router\Router $router) { $router->get('login', 'LoginController@login'); }); ``` ### Custom 404 [](#custom-404) The default 404 handler sets a 404 status code and exits. You can override this default 404 handler by using `$router->set404(callable);` ``` $router->set404(function() { header('HTTP/1.1 404 Not Found'); // ... do something special here }); ``` Also supported are `Class@Method` callables: ``` $router->set404('\App\Controllers\Error@notFound'); ``` The 404 handler will be executed when no route pattern was matched to the current URL. ### Before Route Middlewares [](#before-route-middlewares) `bramus/router` supports **Before Route Middlewares**, which are executed before the route handling is processed. Like route handling functions, you hook a handling function to a combination of one or more HTTP request methods and a specific route pattern. ``` $router->before('GET|POST', '/admin/.*', function() { if (!isset($_SESSION['user'])) { header('location: /auth/login'); exit(); } }); ``` Unlike route handling functions, more than one before route middleware is executed when more than one route match is found. ### Before Router Middlewares [](#before-router-middlewares) Before route middlewares are route specific. Using a general route pattern (viz. *all URLs*), they can become **Before Router Middlewares** *(in other projects sometimes referred to as before app middlewares)* which are always executed, no matter what the requested URL is. ``` $router->before('GET', '/.*', function() { // ... this will always be executed }); ``` ### After Router Middleware / Run Callback [](#after-router-middleware--run-callback) Run one (1) middleware function, name the **After Router Middleware** *(in other projects sometimes referred to as after app middlewares)* after the routing was processed. Just pass it along the `$router->run()` function. The run callback is route independent. ``` $router->run(function() { … }); ``` Note: If the route handling function has `exit()`ed the run callback won't be run. ### Overriding the request method [](#overriding-the-request-method) Use `X-HTTP-Method-Override` to override the HTTP Request Method. Only works when the original Request Method is `POST`. Allowed values for `X-HTTP-Method-Override` are `PUT`, `DELETE`, or `PATCH`. ### Subfolder support [](#subfolder-support) Out-of-the box `bramus/router` will run in any (sub)folder you place it into … no adjustments to your code are needed. You can freely move your *entry script* `index.php` around, and the router will automatically adapt itself to work relatively from the current folder's path by mounting all routes onto that **basePath**. Say you have a server hosting the domain `www.example.org` using `public_html/` as its document root, with this little *entry script* `index.php`: ``` $router->get('/', function() { echo 'Index'; }); $router->get('/hello', function() { echo 'Hello!'; }); ``` - If your were to place this file *(along with its accompanying `.htaccess` file or the like)* at the document root level (e.g. `public_html/index.php`), `bramus/router` will mount all routes onto the domain root (e.g. `/`) and thus respond to `https://www.example.org/` and `https://www.example.org/hello`. - If you were to move this file *(along with its accompanying `.htaccess` file or the like)* into a subfolder (e.g. `public_html/demo/index.php`), `bramus/router` will mount all routes onto the current path (e.g. `/demo`) and thus repsond to `https://www.example.org/demo` and `https://www.example.org/demo/hello`. There's **no** need for `$router->mount(…)` in this case. #### Disabling subfolder support [](#disabling-subfolder-support) In case you **don't** want `bramus/router` to automatically adapt itself to the folder its being placed in, it's possible to manually override the *basePath* by calling `setBasePath()`. This is necessary in the *(uncommon)* situation where your *entry script* and your *entry URLs* are not tightly coupled *(e.g. when the entry script is placed into a subfolder that does not need be part of the URLs it responds to)*. ``` // Override auto base path detection $router->setBasePath('/'); $router->get('/', function() { echo 'Index'; }); $router->get('/hello', function() { echo 'Hello!'; }); $router->run(); ``` If you were to place this file into a subfolder (e.g. `public_html/some/sub/folder/index.php`), it will still mount the routes onto the domain root (e.g. `/`) and thus respond to `https://www.example.org/` and `https://www.example.org/hello` *(given that your `.htaccess` file – placed at the document root level – rewrites requests to it)* Integration with other libraries -------------------------------- [](#integration-with-other-libraries) Integrate other libraries with `bramus/router` by making good use of the `use` keyword to pass dependencies into the handling functions. ``` $tpl = new \Acme\Template\Template(); $router->get('/', function() use ($tpl) { $tpl->load('home.tpl'); $tpl->setdata(array( 'name' => 'Bramus!' )); }); $router->run(function() use ($tpl) { $tpl->display(); }); ``` Given this structure it is still possible to manipulate the output from within the After Router Middleware A note on working with PUT -------------------------- [](#a-note-on-working-with-put) There's no such thing as `$_PUT` in PHP. One must fake it: ``` $router->put('/movies/(\d+)', function($id) { // Fake $_PUT $_PUT = array(); parse_str(file_get_contents('php://input'), $_PUT); // ... }); ``` A note on making HEAD requests ------------------------------ [](#a-note-on-making-head-requests) When making `HEAD` requests all output will be buffered to prevent any content trickling into the response body, as defined in [RFC2616 (Hypertext Transfer Protocol -- HTTP/1.1)](http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.4): > The HEAD method is identical to GET except that the server MUST NOT return a message-body in the response. The metainformation contained in the HTTP headers in response to a HEAD request SHOULD be identical to the information sent in response to a GET request. This method can be used for obtaining metainformation about the entity implied by the request without transferring the entity-body itself. This method is often used for testing hypertext links for validity, accessibility, and recent modification. To achieve this, `bramus/router` but will internally re-route `HEAD` requests to their equivalent `GET` request and automatically suppress all output. Unit Testing & Code Coverage -------------------------------- [](#unit-testing--code-coverage) `bramus/router` ships with unit tests using [PHPUnit](https://github.com/sebastianbergmann/phpunit/). - If PHPUnit is installed globally run `phpunit` to run the tests. - If PHPUnit is not installed globally, install it locally throuh composer by running `composer install --dev`. Run the tests themselves by calling `vendor/bin/phpunit`. The included `composer.json` will also install `php-code-coverage` which allows one to generate a **Code Coverage Report**. Run `phpunit --coverage-html ./tests-report` (XDebug required), a report will be placed into the `tests-report` subfolder. Acknowledgements ---------------- [](#acknowledgements) `bramus/router` is inspired upon [Klein](https://github.com/chriso/klein.php), [Ham](https://github.com/radiosilence/Ham), and [JREAM/route](https://bitbucket.org/JREAM/route) . Whilst Klein provides lots of features it is not object oriented. Whilst Ham is Object Oriented, it's bad at *separation of concerns* as it also provides templating within the routing class. Whilst JREAM/route is a good starting point it is limited in what it does (only GET routes for example). License ------- [](#license) `bramus/router` is released under the MIT public license. See the enclosed `LICENSE` for details. ### Health Score 25 — LowBetter than 37% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity7 Limited adoption so far Community12 Small or concentrated contributor base Maturity55 Maturing project, gaining track record Bus Factor1 Top contributor holds 75.9% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 2 Last Release 2528d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/6fd6cb8950d77fdebcef7c1cd1eac849e5610deddf19aa539f76b371ccaee152?d=identicon)[sn01615](/maintainers/sn01615) --- Top Contributors [![bramus](https://avatars.githubusercontent.com/u/213073?v=4)](https://github.com/bramus "bramus (104 commits)")[![tleb](https://avatars.githubusercontent.com/u/7550889?v=4)](https://github.com/tleb "tleb (15 commits)")[![ovflowd](https://avatars.githubusercontent.com/u/12037269?v=4)](https://github.com/ovflowd "ovflowd (7 commits)")[![sn01615](https://avatars.githubusercontent.com/u/7794149?v=4)](https://github.com/sn01615 "sn01615 (6 commits)")[![artyuum](https://avatars.githubusercontent.com/u/17199757?v=4)](https://github.com/artyuum "artyuum (3 commits)")[![terah](https://avatars.githubusercontent.com/u/2120322?v=4)](https://github.com/terah "terah (1 commits)")[![jbleuzen](https://avatars.githubusercontent.com/u/280681?v=4)](https://github.com/jbleuzen "jbleuzen (1 commits)") --- Tags routerrouting ### Code Quality TestsPHPUnit Code StylePHP CS Fixer ### Embed Badge ![Health badge](/badges/sn01615-bramus-router/health.svg) ``` [![Health](https://phpackages.com/badges/sn01615-bramus-router/health.svg)](https://phpackages.com/packages/sn01615-bramus-router) ``` ### Alternatives [klein/klein A lightning fast router for PHP 2.7k1.1M30](/packages/klein-klein)[pecee/simple-router Simple, fast PHP router that is easy to get integrated and in almost any project. Heavily inspired by the Laravel router. 696214.6k17](/packages/pecee-simple-router)[vlucas/bulletphp A heierarchical resource-oriented micro-framework built on nested closures instead of route-based callbacks 41949.9k1](/packages/vlucas-bulletphp)[izniburak/router simple router class for php 23522.6k7](/packages/izniburak-router)[vectorface/snappy-router A quick and snappy routing framework. 4614.7k](/packages/vectorface-snappy-router)[thewunder/croute Convention based routing for PHP 1317.4k](/packages/thewunder-croute) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)