Download the PHP package miladrahimi/phprouter without Composer

PhpRouter

PhpRouter is a full-featured yet very fast HTTP URL router for PHP projects.

Some of the provided features:

• Route parameters
• Predefined route parameter patterns
• Middleware
• Closure and class controllers/middleware
• Route groups (by prefix, middleware, and domain)
• Route naming (and generating route by name)
• PSR-7 requests and responses
• Views (simple PHP/HTML views)
• Multiple (sub)domains (using regex patterns)
• Custom HTTP methods
• Integrated with an IoC Container (PhpContainer)
• Method and constructor auto-injection of Request, Route, Url, etc

The current version requires PHP v7.4 or newer versions including v8.*.

Contents

• Versions
• Documentation
  • Installation
  • Configuration
  • Getting Started
  • HTTP Methods
  • Controllers
  • Route Parameters
  • Requests and Responses
  • Views
  • Route Groups
  • Middleware
  • Domains and Subdomains
  • Route Names
  • Current Route
  • Error Handling
• License

Versions

• v5.x.x (Current, Supported)
• v4.x.x
• v3.x.x
• v2.x.x
• v1.x.x

Documentation

Installation

Install Composer and run following command in your project's root directory:

Configuration

First of all, you need to configure your webserver to handle all the HTTP requests with a single PHP file like the index.php file. Here you can see sample configurations for NGINX and Apache HTTP Server.

• NGINX configuration sample:

• Apache .htaccess sample:

Getting Started

It's so easy to work with PhpRouter! Just take a look at the following example.

• JSON API Example:

• View Example:

HTTP Methods

The following example illustrates how to declare different routes for different HTTP methods.

You can use the define() method for other HTTP methods like this example:

If you don't care about HTTP verbs, you can use the any() method.

Controllers

Closure Controllers

Class Method Controllers

Route Parameters

A URL might have one or more variable parts like product IDs on a shopping website. We call it a route parameter. You can catch them by controller method arguments like the example below.

Route Parameter Patterns

In default, route parameters can have any value, but you can define regex patterns to limit them.

Requests and Responses

PhpRouter uses laminas-diactoros (formerly known as zend-diactoros) package (v2) to provide PSR-7 request and response objects to your controllers and middleware.

Requests

You can catch the request object in your controllers like this example:

Responses

The example below illustrates the built-in responses.

Views

You might need to create a classic-style website that uses views. PhpRouter has a simple feature for working with PHP/HTML views. Look at the following example.

There is also some points:

• View files must have the ".phtml" extension (e.g. profile.phtml).
• You can separate directories with . (e.g. blog.post for blog/post.phtml).

View files are pure PHP or mixed with HTML. You should use PHP language with template style in the view files. This is a sample view file:

Route Groups

You can categorize routes into groups. The groups can have common attributes like middleware, domain, or prefix. The following example shows how to group routes:

The group attributes will be explained later in this documentation.

You can use Attributes enum, as well.

Middleware

PhpRouter supports middleware. You can use it for different purposes, such as authentication, authorization, throttles, and so forth. Middleware runs before and after controllers, and it can check and manipulate requests and responses.

Here you can see the request lifecycle considering some middleware:

To declare a middleware, you can use closures and classes just like controllers. To use the middleware, you must group the routes and mention the middleware in the group attributes. Caution! The middleware attribute in groups takes an array of middleware, not a single one.

As you can see, the middleware catches the request and the $next closure. The closure calls the next middleware or the controller if no middleware is left. The middleware must return a response, as well. A middleware can break the lifecycle and return a response itself, or it can call the $next closure to continue the lifecycle.

Domains and Subdomains

Your application may serve different services on different domains or subdomains. In this case, you can specify the domain or subdomain for your routes. See this example:

Route Names

You can assign names to your routes and use them in your codes instead of the hard-coded URLs. See this example:

Current Route

You might need to get information about the current route in your controller or middleware. This example shows how to get this information.

IoC Container

PhpRouter uses PhpContainer to provide an IoC container for the package itself and your application's dependencies.

How does PhpRouter use the container?

PhpRouter binds route parameters, HTTP Request, Route (Current route), Url (URL generator), Container itself. The controller method or constructor can resolve these dependencies and catch them.

How can your app use the container?

Just look at the following example.

Check PhpContainer for more information about this powerful IoC container.

Error Handling

Your application runs through the Router::dispatch() method. You should put it in a try block and catch exceptions. It throws your application and PhpRouter exceptions.

PhpRouter throws the following exceptions:

• RouteNotFoundException if PhpRouter cannot find any route that matches the user request.
• InvalidCallableException if PhpRouter cannot invoke the controller or middleware.

The RouteNotFoundException should be considered 404 Not found error.

License

PhpRouter is initially created by Milad Rahimi and released under the MIT License.