bright-webb / easy-router
Easy Router is a lightweight PHP routing library designed to simplify url management and request handling for web applications
Requires
- php: >=7.4
- psr/log: ^3.0
README
Easy Router is a lightweight PHP library designed to simplify routing in web applications. It provides a simple and intuitive way to define routes and handle requests, making it easy to build scalable and maintainable web applications.
Features
- Route Management: Supports multiple HTTP methods (GET, POST, PUT, DELETE, PATCH) and route grouping.
- Middleware Support: Global and route specific middleware for flexible request handling.
- View Rendering: Simple and efficient templating with support for passing dynamic data.
- Session Utilities: Built in helper and flash messaging system for better user feedback.
- Error Handling: Customizable error handlers for different HTTP status codes.
- Lightweight: Minimal dependencies with a focus on performance.
Installation
To use Easy Router in your project, you can install it via Composer:
composer composer require bright-webb/easy-router
Alternatively, download the source files and include them manually in your project.
Getting Started
Setup Autoloading
Ensure your project supports PSR-4 autoloading or include the files manually. If using Composer, include the autoloader:
require_once __DIR__ . '/vendor/autoload.php';
Components
Router
The Router
class handles defining and executing routes.
View
The View
class simplifies rendering templates
render($view, $data = [])
: Renders the specified view with optional data.
View::render('about', ['company' => 'EasyRouter.']);
Helper
Utility methods for simplifying common tasks, such as URL generation or string manipulation.
Flash
The Flash
class provides a simple interface for temporary session messages:
set($key, $message)
: Sets a flash message.get($key)
: Retrieves and clears a flash message.
Error Handling
Custom error handlers for HTTP status codes can be defined:
$router->setErrorHandler(404, function() { echo 'Page not found.'; });
Router Class
The Router
class is the core of the Easy Router library. It manages route definitions, middleware, and request handling.
Features
- Supports multiple HTTP methods (
GET
,POST
,PUT
,DELETE
,PATCH
). - Named routes with URL generation.
- Middleware support for both global and route specific middleware.
- Route grouping with prefixes and middleware.
- Customizable error handling for HTTP status codes.
- Event hooks for pre and post route matching.
Usage Example
Basic Routing
use EasyRouter\Router; $router = Router::getInstance(); // Define routes $router->get('/', function() { echo 'Welcome to Easy Router!'; }); $router->post('/submit', function() { echo 'Form submitted!'; }); $router->run();
Route with Parameters
$router->get('/user/{id}', function($id) { echo "User ID: $id"; });
Named Routes
$router->get('/profile/{username}', function($username) { echo "Profile of $username"; })->name('profile'); // Generate URL $url = $router->url('profile', ['username' => 'bright']); echo $url; // Output: /profile/bright
Grouped Routes
$router->group(['prefix' => 'admin', 'middleware' => ['auth']], function($router) { $router->get('/dashboard', function() { echo 'Admin Dashboard'; }); });
You can use a method in place of the callback function if only the method name is provided.
Example
$router->get('/user/{id}',[ UserController::class, 'getUser']);
Methods
Constructor and Singleton
public static function getInstance(): Router
Creates and returns a singleton instance of the Router class.
Adding Routes
get($path, $callback)
: Defines a route forGET
requests.post($path, $callback)
: Defines a route forPOST
requests.put($path, $callback)
: Defines a route forPUT
requests.delete($path, $callback)
: Defines a route forDELETE
requests.patch($path, $callback)
: Defines a route forPATCH
requests.any($path, $callback)
: Accepts all HTTP methods for a route.add($method, $path, $callback)
: Adds a route for a specific HTTP method.
Example:
$router->get('/example', function() { echo 'Example route'; });
Middleware
middleware($middleware, $callback = null)
: Attaches middleware to a route or globally.use(...$args)
: Adds global middleware, route prefixes, or event hooks.
Example
$router->middleware('auth', function() { echo 'Authentication required!'; });
Route Groups
group(array $attributes, callable $callback)
: Groups routes with shared attributes like prefixes or middleware.
Example
$router->group(['prefix' => 'api', 'middleware' => ['api_auth']], function($router) { $router->get('/users', function() { echo 'API Users'; }); });
Named Routes and URL Generation
name($name)
: Names a route.url($name, $parameters = [])
: Generates a URL for a named route.
Example
$router->get('/home', function() { echo 'Home Page'; })->name('home'); echo $router->url('home');
Error Handling
error($code, callable $handler)
: Registers a custom handler for an HTTP error code.
Example
$router->error(404, function() { echo 'Page not found!'; });
Running the Router
run()
: Starts the router and handles the incoming request.
Example:
$router->run();
Advanced Features
Pattern Matching
pattern($name, $pattern)
: Defines custom patterns for route parameters.
Example:
$router->pattern('id', '[0-9]+'); $router->get('/product/{id}', function($id) { echo "Product ID: $id"; });
Event Hooks
triggerEvent($event, $params = [])
: Attaches hooks forbefore
orafter
route matching.
Example:
$router->use('before', function() { echo 'Before route matching'; });
Middleware Redirection
middlewareRedirect($redirectTo)
: Sets a redirection path for unauthorized access.
Example:
$router->middlewareRedirect('/login');
Contributing
Contributions are welcome! Please fork the repository and submit a pull request with your changes.
License
Easy Router is open-source software licensed under the MIT License.