PHPackages                             gp/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. gp/router

ActiveLibrary

gp/router
=========

A router library for php

1.0.3(11mo ago)0107[1 issues](https://github.com/periyandavar/gp_router/issues)1MITPHPPHP ^8.1CI passing

Since Mar 20Pushed 11mo agoCompare

[ Source](https://github.com/periyandavar/gp_router)[ Packagist](https://packagist.org/packages/gp/router)[ RSS](/packages/gp-router/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (5)Dependencies (5)Versions (12)Used By (1)

GP Router
=========

[](#gp-router)

The GP Router is a lightweight and flexible routing solution for PHP applications. It simplifies the process of mapping HTTP requests to specific controllers or callbacks, enabling developers to build clean, organized, and scalable web applications. With its modular design, the library supports dynamic route parameters, middleware (filters) for pre- and post-processing, and API-specific routes. It is suitable for a wide range of applications, from simple websites to complex RESTful APIs.

This library focuses on:

- **Ease of use**: Define routes with minimal setup.
- **Flexibility**: Handle dynamic URL parameters and custom middleware.
- **Extensibility**: Support for API-specific routes and customizable request/response handling.

Whether you are building a small project or a large-scale application, the GP Router library provides the tools you need to manage your application's routing efficiently.

---

Table of Contents
-----------------

[](#table-of-contents)

- [Requirements](#requirements)
- [Installation](#installation)
- [Getting Started](#getting-started)
- [Features](#features)
- [Classes](#classes)
    - [Router](#router)
    - [Route](#route)
    - [APIRoute](#apiroute)
    - [Wrapper](#wrapper)
    - [Request](#request)
    - [Response](#response)
    - [Filter](#filter)
- [Usage](#usage)
    - [Basic Route Definition](#basic-route-definition)
    - [Using Route Class](#using-route-class)
    - [Dynamic Parameters in Routes](#dynamic-parameters-in-routes)
    - [Using Filters (Middleware)](#using-filters-middleware)
    - [Auto Resolve params](#auto-resolve-params)
        - [Resolving the Request & Response class](#resolving-the-request--response-class)
        - [Resolving the url params](#resolving-the-url-params)
        - [Resolving the Modal class](#resolving-the-modal-class)
        - [Resolving the other service/model](#resolving-the-other-servicemodel)
- [Example](#example)
    - [Initializing the Router](#initializing-the-router)
    - [Using Request object](#using-request-object)
    - [Using Response object](#using-response-object)
- [Contributing](#contributing)
- [License](#license)
- [Contact](#contact)
- [Author](#author)

---

Requirements
------------

[](#requirements)

- PHP 7.4 or higher.
- Composer (optional but recommended for autoloading).

---

Installation
------------

[](#installation)

You can install `gp_router` using Composer. Run the following command in your terminal:

```
composer require gp/router

```

---

Getting Started
---------------

[](#getting-started)

After installation, you can start using the package by including the autoloader:

```
require 'vendor/autoload.php';

```

---

Features
--------

[](#features)

The GP Router library provides a comprehensive set of features to handle routing efficiently in PHP applications:

- **Flexible Route Definitions**:

    - Define static and dynamic routes with ease.
    - Support for URL parameters (e.g., `/user/{(\d+):id}`).
- **HTTP Method Handling**:

    - Supports all major HTTP methods: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, etc.
    - Route-specific method restrictions.
- **Middleware Support (Filters)**:

    - Add pre- or post-processing logic to routes using filters.
    - Useful for authentication, logging, and request validation.
- **API-Specific Routing**:

    - Use the `APIRoute` class to define API endpoints.
    - Designed for building RESTful services.
- **Supports Dependency Injection and Auto Param Resolve**

    - Automatically resolve the controller class constructor and action method params with query params, request and response instance, service instances and also model class with post data
- **Error Handling**:

    - Customizable error handlers for unmatched routes or invalid requests.
- **Request and Response Abstraction**:

    - Simplifies access to HTTP request data (GET, POST, headers, etc.).
    - Facilitates response construction, including status codes and headers.
- **Route Groups and Prefixes**:

    - Group multiple routes with a shared prefix.
    - Useful for organizing application modules (e.g., `/api/v1/`).
- **Named Routes**:

    - Assign names to routes for easier URL generation.
- **Dynamic URL Matching**:

    - Match routes using regular expressions or placeholders.
- **Extensibility**:

    - Easily extend core classes to add custom functionality.
    - Seamlessly integrate with other libraries or frameworks.
- **Lightweight and Fast**:

    - Designed with performance in mind, making it ideal for high-traffic applications.
- **Error-Free Execution**:

    - Built-in validation and error handling ensure smooth routing logic.

These features make the GP Router library a powerful and versatile choice for managing routing in your PHP projects.

---

Classes
-------

[](#classes)

### `Router`

[](#router)

Handles routing functionality.

#### Key Methods:

[](#key-methods)

- `add($route, $expression, $method, $filter, $name)`: Adds a route.
- `run($caseSensitive, $url, $method)`: Executes the router.
- `error($data, $code)`: Handles errors which call the configured controller for errors.

---

### `Route`

[](#route)

Represents a single route.

#### Key Properties:

[](#key-properties)

- `$path`/`$rule` : Route path (eg: `user/{(\d+):id}`).
- `$expression`: Controller and action method or callback
    - home/index - invokes HomeController::index()
    - home - invokes HomeController::invoke()
    - callback function - call the callback function
- `$method`: HTTP method.
- `$filter`: Array of callback or Filter instances to be executed as middleware.
- `$name`: Route name.

---

### `APIRoute`

[](#apiroute)

Handles API-specific routes.

MethodDescriptionParameters\_\_construct()Create a necessary REST API route for the entity$rule, $apiClass, $filters =\[\], $name---

### `Wrapper`

[](#wrapper)

Wraps multiple routes together.

MethodDescriptionParametersgetRoutes()Retrieves the list of routes within the wrapper.None---

### `Request`

[](#request)

Handles HTTP request details.

MethodDescriptionParametersget()Retrieves all GET parameters from the request.$key - the key name (if empty fetch all), $default - default value to be returned null by defaulturlParam()Retrieves all url parameters from the request.$key - the key name (if empty fetch all), $default - default value to be returned null by defaultNonepost()Retrieves all POST parameters from the request.$key - the key name (if empty fetch all), $default - default value to be returned null by defaultNonedata()Retrieves JSON request body for REST API$key - the key name (if empty fetch all), $default - default value to be returned null by defaultNonesession()Retrieves all SESSION parameters from the request.$key - the key name, $default - default value to be returned null by defaultcookies()Retrieves all COOKIES parameters from the request.$key - the key name, $default - default value to be returned null by defaultheaders()Retrieves all header values$key - the key name (if empty fetch all), $default - default value to be returned null by defaultserver()Retrieves all server values$key - the key name, $default - default value to be returned null by default---

### `Response`

[](#response)

Handles HTTP response generation.

MethodDescriptionParameterssetStatusCode()Sets the HTTP status code for the response.$code (int)setBody()Sets the body content of the response.$body (string)---

### `Filter`

[](#filter)

Represents middleware for routes.

MethodDescriptionParametersapply()Applies the filter logic to the given request and response.$request (Request), $response (Response)---

Usage
-----

[](#usage)

### Basic Route Definition

[](#basic-route-definition)

```
use Router\Router;

Router::add('/about', 'AboutController/show', $router::METHOD_GET);
Router::run();

```

### Using Route Class

[](#using-route-class)

```
use Router\Router;
use Router\Route;

$route = new Route('/about', 'AboutController/show', $router::METHOD_GET);
Router::addRoute($route);
Router::run();

```

### Dynamic Parameters in Routes

[](#dynamic-parameters-in-routes)

```

Router::add('/user/{(\d+):id}', 'UserController/show', $router::METHOD_GET); Router::run();

```

In this example, `{id}` is a dynamic parameter. You can access it in your controller using the `Request` object.

### Using Filters (Middleware)

[](#using-filters-middleware)

```
use Router\Route;
use Router\Filter\Filter;

class AuthFilter implements Filter
{
    public function filter(Request $request, Response $response): void
    {
        if (!$request->get('token')) {
          return false;
        }
    }
}

$route = new Route('/secure', 'SecureController/index', Router::METHOD_GET, [new AuthFilter()]); $router = new Router();
Router::addRoute($route);
Router::run();

```

### Auto Resolve params

[](#auto-resolve-params)

#### Resolving the Request & Response class

[](#resolving-the-request--response-class)

The request & response class object will be resolved and passed automatically to the controller consturctor or action method without any additional config, you can use them by adding them as param in the constructor or method, please ensure that you have added exact type for the params.

##### In constructor Param

[](#in-constructor-param)

```
use Router\Request;
use Router\Response;

class APIController
{
   private $req;
   private $res;

   public function __construct(Request $request, Response $res)
   {
     $this->req = $request;
     $this->res = $response;
   }

   .....
}

```

##### In Method Param

[](#in-method-param)

```
use Router\Request;
use Router\Response;

class APIController
{
   public function getPage(Request $req, Response $res)
   {
      .....
   }

   .....
}

```

#### Resolving the url params

[](#resolving-the-url-params)

You can also add the url param values as the part of the param in the constructor or in class method.

- config the url param name in the route as follow. note: path or rule should have the url name and its regex as `{(regex):key}`

```
Router::add('/user/{(\d+):id}', 'UserController/show', $router::METHOD_GET);

```

- Add this url param name as parameter name as follows

```
use Router\Request;
use Router\Response;

class APIController
{
   public function getPage(Request $req, Response $res, int $id)
   {
      .....
   }

   .....
}

```

#### Resolving the Modal class

[](#resolving-the-modal-class)

You can configure the modal class to capture the request data and it's instance will be passed as the param

- Create a base modal class
- Create derived modal class from this base modal class which needs to be passed as parameter.
- set the base modal class to the Router using setUpModalClass
- Add a derived modal class as a parameter to the method.

```

  class Modal {

  }

  class User extends Modal {
    public $name;
    public $age;
  }

  class UserController
  {
    public function process(User $user) {
      print_r([
        'name' => $user->name,
        'age' => $user->age,
      ]);
    }
  }

  Router::setUpModalClass(Modal::class); // add a base type of the modal class
  Router::run();

```

#### Resolving the other service/model

[](#resolving-the-other-servicemodel)

In the same way we can resolve other service modal class instances.

Example
-------

[](#example)

### Initializing the Router

[](#initializing-the-router)

You can initialize the router and define routes in your application:

```
use Router\Router;

// Create a router instance
$router = new Router();

// Define routes
Router::add('/home', 'HomeController/index', $router::METHOD_GET);
Router::add('user/{(\d+):id}', 'UserController/show', $router::METHOD_GET);
Router::add('/api/data', 'APIController/getData', $router::METHOD_POST);

// Run the router
Router::run();

```

### Using Request object

[](#using-request-object)

once the request object is passed as the param to the action method, we can use this method to get all the required details of the request using available methods in the request class.

```
function process(Request $req)
{
  $data = [
    'get' => $req->get(),
    'post' => $req->post(),
    'data' => $req->data(),
    'urlParam' => $req->urlParam(),
    'session' => $req->session('name),
    'cookie' => $req->cookie('name'),
    'server' => $req->server('name'),
    'header' => $req->header('name')
  ];

  print_r($data);
}

```

### Using Response object

[](#using-response-object)

once the response object is passed as the param to the action method, we can use this to handle the response.

The response content will be captured by

- The return values of the method (or)
- The content set in Response object

```
function process(Request $req, Response $res)
{
  $data = [
    'get' => $req->get(),
    'post' => $req->post(),
    'data' => $req->data(),
    'urlParam' => $req->urlParam(),
    'session' => $req->session('name),
    'cookie' => $req->cookie('name'),
    'server' => $req->server('name'),
    'header' => $req->header('name')
  ];

  // way 1
  return $data; // Automatically Router will set this content to Response class

  // way 2
  $res->setBody($data); // The Router automatically fetch the response content and process it.

  //way3
  $res->setBody($data);
  return $res;

}

```

we can also change the response type by using the setType method in response class as follows

```
$response->setStatusCode(200)
  ->setContent('welcome')
  ->setType(Response::TYPE_HTML);

```

Available response types are as follows

- JSON
- HTML
- XML
- text
- csv
- yaml
- binary
- image
- audio
- video
- stream

---

Contributing
------------

[](#contributing)

Contributions are welcome! If you would like to contribute to gp\_validator, please follow these steps:

- Fork the repository.
- Create a new branch (git checkout -b feature/- YourFeature).
- Make your changes and commit them (git commit -m 'Add some feature').
- Push to the branch (git push origin feature/YourFeature).
- Open a pull request.
- Please ensure that your code adheres to the coding standards and includes appropriate tests.

---

License
-------

[](#license)

This package is licensed under the MIT License. See the [LICENSE](https://github.com/periyandavar/gp_router/blob/main/LICENSE) file for more information.

---

Contact
-------

[](#contact)

For questions or issues, please reach out to the development team or open a ticket.

---

Author
------

[](#author)

- Periyandavar [Github](https://github.com/periyandavar) ()

---

###  Health Score

33

—

LowBetter than 74% of packages

Maintenance54

Moderate activity, may be stable

Popularity9

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~18 days

Total

5

Last Release

343d ago

Major Versions

v0.0.1 → v1.0.02025-03-22

PHP version history (2 changes)v1.0.0PHP ^8.0

1.0.1PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/b9f29960ccfedb3111fb3b6869ff5449da9cd7d027b19edfdef9d17a0915cb7c?d=identicon)[periyandavar](/maintainers/periyandavar)

---

Top Contributors

[![periyandavar](https://avatars.githubusercontent.com/u/209335631?v=4)](https://github.com/periyandavar "periyandavar (30 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/gp-router/health.svg)

```
[![Health](https://phpackages.com/badges/gp-router/health.svg)](https://phpackages.com/packages/gp-router)
```

###  Alternatives

[getkirby/cms

The Kirby core

1.5k535.5k350](/packages/getkirby-cms)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

595.2M385](/packages/shopware-core)[neos/flow

Flow Application Framework

862.0M448](/packages/neos-flow)[rock-symphony/rock-symphony

Fork of symfony 1.4 with dic, form enhancements, latest swiftmailer and better performance

19164.1k3](/packages/rock-symphony-rock-symphony)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)