devamirul/p-router

Simple, lightweight, and powerful PHP Router with rich features like Middlewares and Controllers is a simple and useful router class. Heavily inspired by the way Laravel handles routing.

v1.0.11 2023-11-11 05:41 UTC

Requires

• php: >=8.00
• ext-json: *

MIT

• Amirul islam

• router
• php-router
• request-handler
• url-handling
• input-handler
• routing-engine

README

  _____            _____             _
 |  __ \          |  __ \           | |
 | |__)   ______  | |__) |___  _   _| |_ ___ _ __
 |  ___/ |______| |  _  // _ \| | | | __/ _ \ '__|
 | |              | | \ \ (_) | |_| | ||  __/ |
 |_|              |_|  \_\___/ \__,_|\__\___|_|

A simple, lightweight, and powerful PHP Router with rich features like Middleware and Controllers. Heavily inspired by the way Laravel handles routing.

Features:

• Supports GET POST PUT PATCH and DELETE HTTPS verbs
• The methods that the router supports are :- get() post() put() patch() delete() match() any()
• Named Routes
• Regular expression constraints for parameters
• Fallback method
• Middleware
• CSRF protection
• Controller
• Easy way to manage request
• Helper methods
• Command line interface(CLI)

Table of Contents:

• Installation
• Examples
• Directories
• Routes
• Middlewares
• CSRF Protection
• Controllers
• Request
• Handle Html View Content File
• Handle Form
• Helpers

Installation:

Installation is possible using Composer.

composer require devamirul/p-router

Add the following script to composer.json file:

"autoload": {
    "psr-4": {
        "App\\": "app/"
    }
},
"scripts": {
    "start": [
        "php -S 127.0.0.1:8000"
    ],
    "middleware": "cd vendor/devamirul/p-router/src/CLI && php createMiddleware.php && cd -",
    "controller": "cd vendor/devamirul/p-router/src/CLI && php createController.php && cd -",
    "app": "cd vendor/devamirul/p-router/src/CLI && php createApp.php && cd -"
}

Run the following command:

composer dump-autoload

Create app folder.

composer app

Start PHP server.

composer start

Examples:

Basic route:

$router->get('/', function () {
    echo 'welcome to p-route';
})->name('home');

or

$router->get('/', [WelcomeController::class, 'index'])->name('home');

Dynamic Route:

$router->get('/users/:id', function(){
    //
})->where(['id' => '^\d+$'])->name('user');

Middleware:

$router->get('/users/:id', function(){
    //
})->middleware('auth')->where(['id' => '^\d+$'])->name('user');

You can do method chaining if you want.

Directories:

app/config: This folder contains system config files. Make your changes only in the config file.

app/Middlewares: Create your custom middlewares in this folder.

app/Controllers: Create your custom controllers in this folder.

Routes:

Available Router Methods:

The router allows you to register routes that respond to any HTTP verb:

$router->get($uri, $callback);
$router->post($uri, $callback);
$router->put($uri, $callback);
$router->patch($uri, $callback);
$router->delete($uri, $callback);
$router->match($uri, $callback);
$router->any($uri, $callback);

Basic Routes:

Routes accept a URI and a closure or a array, providing a very simple and expressive method of defining routes and behavior without complicated routing configuration files.

1. First create index.php file.
2. Define Application root path.
3. Require vendor autoload file.
4. Create router singleton instance.
5. Define routes.
6. Run the application via the run() method.

<?php
/**
 * Define root directory.
 */
define('APP_ROOT', dirname(__FILE__));

/**
 * Require composer autoloader.
 */
require __DIR__ . '/vendor/autoload.php';

// Get singleton route instance.
$router = Devamirul\PRouter\Router::singleton();

// Define routes.
$router->get('/greeting', function () {
    return 'Hello World';
});

// Resolve and run application.
$router->run();
?>

Or create a separate route.php file and include that file in the index.php file.

First create route.php or name the file according to your choice:

<?php

// Define routes
$router->get('/greeting', function () {
    return 'Hello World';
});

$router->fallback(function () {
    return 'Fallback route';
});

?>

Include route.php in the index.php file:

/**
 * Require composer autoloader.
 */
require __DIR__ . '/vendor/autoload.php';

// Get singleton route instance.
$router = Devamirul\PRouter\Router::singleton();

// Require route.php
require_once './route.php';

// Resolve and run application.
$router->run();

Let's discuss the second parameter. The second parameter accepts a closure or an array of key value pairs. The 'key' of the array will be a class and the value will be a method of the class, the method will be invoked by the class.

use App\Controllers\WelcomeController;

$router->get('/', [WelcomeController::class, 'index'])->name('home');

Use return instead of echo.

// Right way.
$router->get('/greeting', function () {
    return 'Hello World';
});

// wrong way.
$router->get('/greeting', function () {
    echo 'Hello World';
});

Named Routes:

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:

Route names should always be unique.

$router->get('/user/profile', function () {
    // ...
})->name('profile');

Generating URLs To Named Routes

Once you assign a name to a given route, you can redirect via toRoute():

return toRoute('profile');

If the named route defines parameters, you may pass the parameters as the second argument to the toRoute function. The given parameters will automatically be inserted into the generated URL in their correct positions:

$router->get('/user/:id/profile', function () {
    // ...
})->name('profile');

return toRoute('profile', ['id' => 1]);

If you pass additional parameters in the array, those key / value pairs will automatically be added to the generated URL's query string:

$router->get('/user/:id/profile', function () {
    // ...
})->name('profile');

return toRoute('profile', ['id' => 1, 'photos' => 'yes']);

If you use an asterisk (*) in the route, you cannot call it via toRoute().

Route Parameters:

Required Parameters:

Sometimes you will need to capture segments of the URI within your route. For example, you may need to capture a user's ID from the URL. You can get it through $request->getParam() method.

$router->get('/user/:id', function (Request $request) {
    return 'User ' . $request->getParam('id');
});

You may define as many route parameters as required by your route:

$router->get('/posts/:post/comments/:comment', function (Request $request) {
    //Get all parameters array.
    return 'User ' . $request->getParam();

    //Get specific parameter.
    return 'User ' . $request->getParam('post');
});

Route parameters will always start with Colon ':' and should contain alphanumeric characters.

Parameters:

Automatically get 'Request' instances in your route callback or controller.

In callback:

$router->get('/user/:id', function (Request $request) {
    return 'User ' . $request->getParam('id');
});

In controller:

$router->get('/user/:id', [UserController::class, 'index']);

namespace App\Http\Controllers;

use Devamirul\PhpMicro\core\Foundation\Application\Request\Request;
use Devamirul\PhpMicro\core\Foundation\Controller\BaseController;

class UserController extends BaseController {
    public function index(Request $request) {
        return 'User ' . $request->getParam('id');
    }
}

Optional Parameters:

Occasionally you may need to specify a route parameter that may not always be present in the URI. You may do so by placing a question sign ? mark after the parameter:

It is important to note that optional parameter are always placed at the end of the URLs.

$router->get('/user/:name?', function () {
    //
});

Regular Expression Constraints:

You can restrict the format of your route parameter by using the where method on a route instance. The where() method takes a regular expression as parameter which determines how the parameter should be delimited. The "where()" method will accept the serialized parameters of the router's dynamic parameters:

$router->get('/user/:id', function () {
    // ...
})->where(['id' => '^\d+$']);

Regular expression constraints for optional parameter:

$router->get('/user/:name?', function () {
    //
})->where(['name' => '^[a-zA-Z ]*$']);

Regular expression constraints for multiple optional parameters:

$router->get('/profile/:id/user/:name?', function () {
    //
})->where(['id' => '^\d+$', 'name' => '^[a-zA-Z ]*$']);

match and any method

Sometimes you may need to register a route that responds to multiple HTTP verbs. You may do so using the match method. Or, you may even register a route that responds to all HTTP verbs using the any method:

$router->match(['get', 'post'], '/', function () {
    // ...
});

$router->any('/', function () {
    // ...
});

Route wildcard:

You can use dynamic routes using asterisks:

$router->get('admin/*', function () {
    // ...
});

In the example above, you can dynamically use any path after admin/. The asterisk is used as a wildcard and matches any combination of characters.

Middlewares:

app/Middlewares: Middleware provides a convenient mechanism for inspecting and filtering HTTP requests entering your application.

The predefined middleware files are:- AuthMiddleware.php CsrfMiddleware.php

By default you will get a request instance in the handle method.

Make middleware:

To create a new middleware, use the composer middleware command:

composer middleware

The command line interface will ask you for a middleware name, you enter a name. It will automatically add "Middleware" to the name you provided. For example, you want to create a middleware named "example". Then your middleware class will be ExampleMiddleware.php

namespace App\Middlewares;

use Devamirul\PRouter\Interfaces\Middleware;
use Devamirul\PRouter\Request\Request;

class AuthMiddleware implements Middleware {
    /**
     * Handle an incoming request.
     */
    public function handle(Request $request): void {
        //
    }
}

For example, This framework includes a middleware that verifies the user of your application is authenticated. If the user is not authenticated, the middleware will redirect the user to your application's login screen. However, if the user is authenticated, the middleware will allow the request to proceed further into the application.

public function handle(Request $request): void {
    if (!isset($_SESSION['user'])) {
        redirect('/login');
    }
    return;
}

Add middleware

After creating the middleware add it to the middleware array in the 'app/config/middleware.php' file. Add your own middleware to this list and assign it an alias of your choice:

'middleware' => [
    'csrf' => Devamirul\PRouter\Middleware\Middlewares\CsrfMiddleware::class,
    'auth' => App\Middlewares\AuthMiddleware::class
],

If you would like to assign middleware to specific routes, you may invoke the middleware method when defining the route. Once the middleware alias is defined, you use the alias when assigning middleware to routes:

Router::get('/users/:id', function(){
    //
})->middleware('auth');

You can assign multiple middleware at once if you want:

Router::put('/users/:id', function(){
    //
})->middleware(['auth','csrf']);

Set default middlewares:

If you want to set some middleware to Https verbs by default, you can do that very easily, The defined middleware will run when that https method request is handled:

Open app/config/middleware.php

'get'        => [],
'post'       => [ 'csrf' ],
'put'        => [ 'csrf' ],
'patch'      => [ 'csrf' ],
'delete'     => [ 'csrf', 'auth' ],

CSRF Protection:

Anytime you define a "POST", "PUT", "PATCH", or "DELETE" HTML form in your application, you should include a hidden CSRF _token field in the form so that the CSRF protection middleware can validate the request, Otherwise, the request will be rejected. For convenience, you may use the setCsrf() function to generate the hidden token input field:

<form method="POST" action="/profile">
    <?=setCsrf()?>
    ...
</form>

Controllers:

app/Controllers: Controllers respond to user actions (submitting forms, show users, view data, and any action etc.). Controllers are classes that extend the BaseController class.

By default you will get request instance in each method.

Make controller

To create a new controller, use the composer controller command:

composer controller

The command line interface will ask you for a controller name, you enter a name. It will automatically add "Controller" to the name you provided. For example you want to create a controller named "example". Then your controller class will be ExampleController.php

namespace App\Controllers;

use Devamirul\PRouter\Request\Request;
use Devamirul\PRouter\Controller\BaseController;

class UserController extends BaseController {
    /**
     * Show user.
     */
    public function show(Request $request) {
        return 'user name -' . $request->input('name');
    }
}

Request:

Framework's Request class provides an object-oriented way to interact with the current HTTP request being handled by your application as well as retrieve the input that were submitted with the request.

Accessing The Request:

You can get request instance through the request helper function:

// Get all input data.
request()->all();

// Get all input data.
request()->input();

// Get input data specified by key, return default data if key not found.
request()->input('name', 'default');

// Get input data specified by key.
request()->only('name', 'email');

// Get path.
request()->path();

// Get all query.
request()->query();

// Get query data specified by key.
request()->query('name');

// Get current method.
request()->method();

// Get all input data.
request()->all();

// Get dynamic params.
request()->getParam();

// Get specific param.
request()->getParam('id');

Also you will get methods.

isGet() isPost() isPut() isPatch() isDelete()

Handle Html View Content File:

You can easily view html content from a controller or callback function.

Simply `require' the file you want to view:

$router->get('/', function () {
    require_once './home.php';
});

In Content file:

<body>
    <h1>Home Page</h1>
</body>

You can easily view the data in the content file:

$router->get('/', function (Request $request) {
    $name = 'Amirul islam';

    require_once './home.php';
});

In Content file:

<body>
    <h1>Welcome Mr <?= $name ?> </h1>

    <?php
        foreach ($request->input() as $value) {
            echo $value;
        }
    ?>
</body>

Handle Form:

<form action="/login" method="POST" class="mt-5">

    <?=setCsrf()?>

    <div class="mb-3">
        <label for="exampleInputEmail" class="form-label">Email address</label>
        <input type="email" name="email" class="form-control" id="exampleInputEmail" aria-describedby="emailHelp">
        <div id="emailHelp" class="form-text"> <?= errors('email')?> </div>
    </div>

    <div class="mb-3">
        <label for="exampleInputPassword" class="form-label">Password</label>
        <input type="password" name="password" class="form-control" id="exampleInputPassword">
        <div id="emailHelp" class="form-text"> <?= errors('password')?> </div>
    </div>

    <button type="submit" class="btn btn-primary">Login</button>
</form>

Method Field:

Since HTML forms can't make PUT, PATCH, or DELETE requests, you will need to add a hidden _method field to spoof these HTTP verbs. The setMethod() Blade directive can create this field for you:

<form>
    <?=setMethod('delete')?>
    ...
</form>

Helpers:

Table of Contents

• General Helpers
• Form Helpers
• Request Helpers
• Response Helpers

General Helpers:

Get config data:

config('app', 'timezone');

View the data in details then exit the code:

dd([1,2,3]);

View the data in details:

dump();

Form Helpers:

Set new CSRF value:

setCsrf();

Example:

<form>
    <?=setCsrf()?>
</form>

Check CSRF is valid or not, return bool:

isCsrfValid();

Set form method, like put/patch/delete:

setMethod();

Example:

<form>
    <?=setMethod('delete')?>
</form>

Request Helpers:

Get request instance

request();

Example:

request()->input();

Response Helpers:

Redirect link:

return redirect('/redirect-link');

Finds route by route name and redirect this route:

return toRoute('users');