Download the PHP package agashe/sigmaphp-router without Composer

SigmaPHP-Router

A fast and simple router for PHP , you can use for your projects to provide user friendly URLs , you can build your app in a simple functional style , to write RESTfull API services or to build a fully functional MVC.

Features

• Support placeholder parameters e.g {name}
• Use optional parameters with the route
• Support all HTTP methods GET, POST, PUT ... etc
• Routes can accept multiple HTTP methods
• Support any method , so the route can accept all HTTP methods
• Routes Validation using regex expressions
• Actions can be implemented as regular functions or controller's method
• Support for Single Action Controllers
• Middlewares , that can be run before your route
• Route Groups which support middlewares and prefix
• URL generation using the route name
• Default page not found (404) handler and you can define custom handler
• Custom action runners , for advanced customization

Installation

Configurations

Depending on your server , you will need to use one of the provided server configs , including with the router config files for 4 types of servers : Apache , Nginx , Lighttpd and IIS.

To use the router with any of these servers , just copy the corresponding config file from the configs folder to the root folder of your project.

For example , in case you are using Apache server , copy the apache_htaccess file and rename it to the proper name .htaccess

Please note : all of the provided config files , assume that the main entry point to your application is index.php located in the root path of your project's directory. If you have different setup for your project , check please the config and make sure it's pointing to the correct path.

So if the index.php is located under the public folder. Then in the .htaccess file , change index.php to public/index.php , and the same goes for other servers.

Documentation

Table of Contents

• Basic Setup
• Base Path
• HTTP Methods
• Parameters
• Validation
• Actions
• Middlewares
• Route Groups
• Page not found handling
• URL Generation
• Action Runners

Basic Setup

In order to start using SigmaPHP-Router in your app , in the main entry point of your app (say for example index.php ), you first need define the routes array , then pass that array to the constructor and finally call the the run() method.

Alternatively you can save your routes in a separated file and load that file in your app. Even better you can have multiple route files each serves a different purpose.

web.php

api.php

and finally in index.php :

To define a new route , you simply append an route array to the routes array , a valid route should at least have a path and an action :

The route's name is optional , put it is recommended to give your routes a name , so it becomes easier to work with them , like generating URL using the route's name.

Base Path

In case your application exists in sub-folder of your domain for example http://localhost/my-app , you can set the root path in the router constructor , using the second parameter:

HTTP Methods

SigmaPHP-Router support all HTTP methods GET, POST, PUT, DELETE ... etc , a single route can support one or more HTTP methods :

Also SigmaPHP-Router provides a special method type any , which allows the route to accept all of the HTTP methods :

If no HTTP was provided , then the HTP method for the route will be automatically set to GET.

Parameters

Route parameters follow the placeholder style (like Laravel) :

Also optional parameters can be used by adding ? to the parameter , but this option can only be used with last parameter of your route :

So the id in this route can be omitted , so calling /products or /products/15 are fine.

and lastly don't forget to handle the optional parameter in your action , by adding a default value for the action:

Validation

A validation rules can be added to your routes , in form of regular expressions :

In the example above the router will match only order_id that only contains digits , so something like /orders/details/abcd won't be matched and the router will return 404 - page not found.

Actions

In SigmaPHP-Router an action is the handler which will be executed to process the route functionality.

Actions are divided into 2 categories , first controller based , which simply are classes that contain multiple methods , usually the controller responsible for handling tasks in which grouped by the same model or functionality like PostController or UserLoginController.

As we saw in the previous examples , we need to pass the controller name and the method name :

We use the special constant ::class in order to get the full name including the namespace of the controller. you can instead write the full path if you prefer , for example :

The second type of actions are functions based , and in this case you just add the function name without controller , and the router simply will call that function , so for example :

Finally SigmaPHP-Router also has support for Single Action Controllers , so no need to pass action name , and the router will automatically search for the PHP magic method __invoke() to run :

And in the SendEmailController :

Middlewares

Usually in any application you will need to run some checks before allowing the user to perform the action , like for example check if is he logged in , has the proper permissions , and so on.

So out of the box SigmaPHP-Router provides the ability to call middlewares before the execution of your route's action.

In case of class based middlewares , the router will require the middleware class name and the name of the method that will be executed.

In addition the middlewares could be written as regular functions , and in this case we pass an array of functions name :

Creating the middleware classes/functions is completely depending on your application , so in your middleware you could have something similar to :

Route Groups

Group routes is an essential feature for any router , so you can apply certain prefix or middleware to a group of routes.

To create a new route group , use the following schema :

The only items required for a group is the group name and the routes array. The name will be added to all of its routes , so in the example above , the final route name will be : api.users.profile and the route path : /api/v1/users/profile

Both prefix and middlewares are optional , a routes group could either has prefix , middlewares , both or non of them.

For the routes definition , nothing changed all features are implemented as regular routes.

Please Note : SigmaPHP-Router doesn't support sub-groups so you can't define a routes group inside another routes group !

Page not found handling

By default in case the requested URI didn't match , the router will return 404 HTTP status code , with simple message 404 , The Requested URL Was Not Found

You change this default behavior by passing a custom handler name as an argument to the method setPageNotFoundHandler

So now you can add your custom 404 message , page design or redirect the user another route.

And as usual you can instead of using function handler , you can use a class , so you pass class name and the method name :

URL Generation

In a lot of cases , you will need a way to create an URL for your models , for example a link to show order details , SigmaPHP-Router provides a method called url , which accept a route name and parameters array. and generate the URL , let's see an example :

So to generate an URL for the route above :

The router will automatically add the host and check if the https is enabled.

Also in case your route doesn't require parameters , or accept optional parameters , you can skip the second parameter.

Action Runners

Action runner is the execution unit inside SigmaPHP-Router , it's the last step in the route execution cycle , starting from matching to applying middlewares and other validations , we finally reach to the execution phase , in this phase the runner will take care of executing the action either by calling the action function or a method defined in class.

But in some cases , writing our custom runner might be a necessity , for example if we want to preform some logic before the execution start , for example add some logs before or after the execution or handle dependency injection.

By default SigmaPHP-Router ships with the DefaultRunner , to register your own runner , all what you have to do is to define and new class that implements the RunnerInterface :

A simple interface that only has one method execute which only accepts the route as a parameter.

Please note , that inside the execute method we have three main items defined in the route array , that we should use to execute the route :

Finally we can register our custom runner using the setActionRunner method :

The setActionRunner method also has one optional parameter called parameters which of type array and can be used to pass arguments to the runner constructor :

And in some cases depending on how complex our project , we can control the runners based some conditions like environment variables ... etc

Examples

License

(SigmaPHP-Router) released under the terms of the MIT license.