Download the PHP package pixelkarma/pkrouter without Composer

PkRouter

PkRouter is a fast and robust modern PHP router intended to be used for API creation. It has no dependencies, and encourages an object oriented approach.

Please see the Example to see in in action.

Features

• Supports all HTTP methods, including custom ones.
• Flexible middleware for pre- and post-route execution.
• Extensible request and response classes for handling custom payloads.
• Supports both function and class method callbacks, ideal for MVC projects.
• Efficient, robust regex-based routing.
• Extensible parameter pattern validation.
• Dynamic properties enable seamless data storage throughout the request lifecycle.
• Custom exceptions enhance error handling and clarity.

Installation

Usage

Functions

Controller Methods

See Controller Method Callbacks

Router (PkRouter)

If no options are passed when creating the router, the default classes are used and an empty Route Config is created. You will then need to add routes individually.

Finding a match

There are two ways to find a match and execute its callback.

or

Responding

This is a shortcut to $router->response->sendJson();

Dynamic Properties

In PkRouter, you have the ability to set dynamic properties on the $router instance. These properties can be used to store data that needs to be accessed or modified at different stages of the request lifecycle, such as during the before middleware, the route callback, and the after middleware.

Route Creation

Route Callback

The callback is executed when a matching route is found. This value can either be a function, or a string representing your own controller method. Both should accept one parameter, an instance of PkRouter

Functional Callbacks

Controller Method Callbacks

Your Contoller will need to accept the $router on construct, not the method.

Route Meta

Meta is an array of values used to provide additional data on a route level. This information is accessible from Middleware and Callbacks

Before and After Middleware

See Middleware

URL Parameters

Path: /user/[s:username]/

In this example s, is the type and username is the param name accessible with:

See PkRoute Methods for more information about getParam()

Add additional match patterns

By calling the static function addMatchPattern, you can add additional param types. This can be used at any point prior to matching a route.

A common place to put this is in a Route Config file, as shown below

Route Methods

Methods that allow the $key parameter will return $default (default: null) if the key is not found. This is useful when validating a payload when you might want a value other than null.

Route Config

PkRoutesConfig is an extensible class for setting up multiple Routes, and adding Middleware.

Request (PkRequest)

PkRequest contains all of the information about the request being made.

Request Methods

Methods that allow the $key parameter will return $default (default: null) if there is no data. This is useful when validating a payload when you might want a value other than null.

Response (PkResponse)

Headers and response code do not send until the payload sends.

Extending PkResponse

PkRouter only supports JSON out of the box, but you can extend it to do more.

Middleware

Middleware are instances of PkMiddlewareInterface that can be run before your route code and after the payload has sent.

Note: Middleware is executed in the order you place it in the array.

Creating your own Middleware

Note: If your handle() function returns false, it will not continue to the next middleware. The routing will end and run() will return false. If you need to pass data between middleware, consider returning an array or an object.

Passing information between Middleware

Note: Middleware returns are not passed to the callback. See Dynamic Properties.

License

MIT License, see LICENSE.md

Copyright (c) 2024 Pixel Karma, LLC [email protected]