Routing library for PHP
This library allows you to create static or dynamic routes. This library was inspired by PHP Slim framework
Install via composer
composer require gac/routing
Manual install
Download the latest release from the Releases page.
Don't forget to add these include_once
statements to your php files:
include_once "./Exceptions/CallbackNotFound.php";
include_once "./Exceptions/RouteNotFoundException.php";
include_once "./Request.php";
include_once "./Routes.php";
Post install
To use this library properly you will need to create a .htaccess
file at the root of the project.
Example of the .htaccess
file would look like this:
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.+)$ index.php [QSA,L]
Note
If you've named your main file differently, replace index.php
in the .htaccess
file with whatever your main
application file is.
Quick start
Sample code to allow you to quickly start with your development.
use Gac\Routing\Exceptions\CallbackNotFound;
use Gac\Routing\Exceptions\RouteNotFoundException;
use Gac\Routing\Request;
use Gac\Routing\Response;
use Gac\Routing\Routes;
include_once "vendor/autoload.php"; # IF YOU'RE USING composer
$routes = new Routes();
try {
$routes->add('/', function (Request $request) {
// Old way of doing it, still supported until v4
$request
->status(200, "OK")
->send(["message" => "Welcome"]);
// New way of doing it
Response::
withHeader("Content-Type", "application/json")::
withStatus(200, 'OK')::
withBody([ "message" => "Welcome" ])::
send();
});
$routes->route('/', function (Request $request) {
// Old way of doing it, still supported until v4
$request
->status(200, "OK")
->send(["message" => "Welcome"]);
// New way of doing it
Response::
withHeader("Content-Type", "application/json")::
withStatus(200, 'OK')::
withBody([ "message" => "Welcome" ])::
send();
}, [Routes::POST])->save();
$routes->route();
} catch (RouteNotFoundException $ex) {
// Old way of doing it, still supported until v4
$routes->request->status(404, "Route not found")->send(["error" => ["message" => $ex->getMessage()]]);
// New way of doing it
Response::withStatus(404, 'Route not found')::send(["error" => [ "message" => $ex->getMessage() ]]);
} catch (CallbackNotFound $ex) {
// Old way of doing it, still supported until v4
$routes->request->status(404, "Callback not found")->send(["error" => ["message" => $ex->getMessage()]]);
// New way of doing it
Response::withStatus(404, 'Callback not found')::send(["error" => [ "message" => $ex->getMessage() ]]);
} catch (Exception $ex) {
$code = $ex->getCode() ?? 500;
// Old way of doing it, still supported until v4
$routes->request->status($code)->send(["error" => ["message" => $ex->getMessage()]]);
// New way of doing it
Response::withStatus($code)::send(["error" => [ "message" => $ex->getMessage() ]]);
}
Examples
Dynamic routes example
$routes->add('/test/{int:userID}-{username}/{float:amount}/{bool:valid}', function (
Request $request,
int $userID,
string $username,
float $amount,
bool $valid
) {
echo 'Dynamic route content here';
});
Chained routes
When using chained methods either use ->save()
or ->add()
as the last method to indicate the end of a chain
NOTE
->save(true|false)
method can still be chained onto if needed- Passing
false
(the default value istrue
) to the->save()
method will preserve all the previous prefixes and middlewares in that chain
- Passing
->add()
CAN NOT be chained onto and should be the last call in chain
$routes
->prefix('/user') // all the routes added will have the /user prefix
->middleware([ 'verify_token' ]) // all the routes added will have the verify_token middleware applied
->route('/', [ HomeController::class, 'getUsers' ], Routes::GET)
->route('/', [ HomeController::class, 'addUser' ], Routes::POST)
->route('/', [ HomeController::class, 'updateUser' ], Routes::PATCH)
->route('/', [ HomeController::class, 'replaceUser' ], Routes::PUT)
->add('/test', [ HomeController::class, 'deleteUser' ], Routes::DELETE);
Chained routes with save at the end
$routes
->prefix("/test")
->middleware(['decode_token'])
->route("/t0", function(Request $request){})
->get("/t1", function (){})
->post("/t2", function (){})
->put("/t3", function (){})
->patch("/t4", function (){})
->delete("/t5", function (){})
->save();
Chained routes with multiple chains in one call
$routes
->prefix("/test")
->middleware([ 'decode_token' ])
->get("/t1", function () { }) // route would be: /test/t1
->get("/t2", function () { }) // route would be: /test/t2
->get("/t3", function () { }) // route would be: /test/t3
->save(false) // by passing the false argument here, we keep all the previous shared data from the chain (previous prefix(es) and middlewares)
->prefix("/test2")
->middleware([ "verify_token" ])
->get("/t4", function () { }) // route would be: /test/test2/t4
->get("/t5", function () { }) // route would be: /test/test2/t5
->get("/t6", function () { }) // route would be: /test/test2/t6
->save() // by not passing the false argument here, we are removing all shared data from the previous chains (previous prefix(es) and middlewares)
->prefix("/test3")
->middleware([ "verify_token" ])
->get("/t7", function () { }) // route would be: /test3/t7
->get("/t8", function () { }) // route would be: /test3/t8
->get("/t9", function () { }) // route would be: /test3/t9
->add(); //using save or add at the end makes the chaining stop and allows for other independent routes to be added
Passing arguments to middleware methods
When working with middlewares you can also pass them arguments if you need to
use Gac\Routing\Response;
$routes
->middleware([
'test_middleware',
'has_roles' => 'admin,user',
[ Middleware::class, 'test_method' ],
[ Middleware::class, 'has_role', 'Admin', 'Moderator', [ 'User', 'Bot' ] ],
])
->add('/test', function (Request $request) {
// Old way of doing it, still supported until v4
$request->send([ 'msg' => 'testing' ]);
//New way of doing it
Response::send([ "msg" => "testing" ]);
});
Every middleware function can also accept an argument of type Gac\Routing\Request
at any position as long as it has
the proper type specified.
Dependency injection on route classes
When using classes to handle your route callback, and those classes have some dependencies that need to be injected through a constructor, you can specify them as an array of arguments to be injected or let the library try to auto-inject classes.
$routes->add(
'/demo',
[
HomeController::class,
'dependency_injection_test',
[ new InjectedClass() ]
],
Routes::GET
);
You can also use named arguments or mix and match them
$routes->add(
'/demo',
[
HomeController::class,
'dependency_injection_test',
[ "injected_var" => new InjectedClass(), new Middleware ]
],
Routes::GET
);
Letting the library auto-inject classes into the constructor
$routes->add(
'/demo',
[ InjectController::class ],
Routes::GET
);
NOTE
The library will always try to auto-inject classes (will skip ones with null as default value) if non are provided, and you're using a class for callbacks.
__invoke
instead for single method classes
Use $routes->add(
'/invoke',
[ HomeController::class ],
Routes::GET
);
You can also use __invoke
with dependency injection as well:
$routes->add(
'/invoke',
[
HomeController::class,
[ new InjectedClass() ]
],
Routes::GET
);
For more examples look in the sample folder index.php
file
Documentation
Source code documentation can be found at PHP Routing documentation page
Features
- Static routes
- Dynamic routes
- Middlewares
- Pass arguments to middlewares
- Route prefixes
- Method chaining
- Dependency injection on classes
- Manual injection
- Auto-injection