457 lines
14 KiB
Markdown
457 lines
14 KiB
Markdown
# InforRoutes
|
|
|
|
A simple and dependency free routing system providing:
|
|
|
|
- Non blocking dispatch of system `WEB` and `CLI` functionalities
|
|
- Parameters detection on the URL segments
|
|
- Route grouping based on namespaces
|
|
- Error handling and 404 detection
|
|
- Attachable and global middlewares
|
|
|
|
## Usage
|
|
|
|
### Installation
|
|
First install the package with `composer require inforsistemas/routes`. You might need to add a custom repository on the composer.json
|
|
|
|
```json
|
|
"repositories": [{
|
|
"type": "composer",
|
|
"url": "https://satis.domain.com"
|
|
}],
|
|
```
|
|
|
|
|
|
#### Hello World
|
|
|
|
With the dependencies and the server with the correct configuration, create a index.php with the content
|
|
|
|
```php
|
|
<?php
|
|
|
|
include_once 'vendor/autoload.php';
|
|
use Routes\RouteCollection as RouteCollection;
|
|
|
|
// Add a route to the collection
|
|
RouteCollection::get ("/", function(){
|
|
return "Hello World";
|
|
});
|
|
|
|
// Dispatch the router
|
|
RouteCollection::getInstance()->submit();
|
|
```
|
|
|
|
### Registering routes
|
|
|
|
#### The simple API to register routes
|
|
|
|
```php
|
|
<?php
|
|
use Routes\RouteCollection as RouteCollection;
|
|
|
|
RouteCollection::get("/", function(){ });
|
|
RouteCollection::get("/form", function(){ });
|
|
RouteCollection::post("/", function(){ });
|
|
RouteCollection::get("/[i:id]", function($id){ });
|
|
RouteCollection::put("/[i:id]", function($id){ });
|
|
RouteCollection::patch("/[i:id]", function($id){ });
|
|
RouteCollection::delete("/[i:id]", function($id){ });
|
|
```
|
|
|
|
#### Passing a ClassPath string as argument.
|
|
|
|
Based on the defined autoloader, the library will instanciate the controller and execute the method.
|
|
|
|
The library will also try to infer the controller method signature and parse the URL parameters to the required type
|
|
|
|
```php
|
|
<?php
|
|
use Routes\RouteCollection as RouteCollection;
|
|
|
|
RouteCollection::get("/", "\App\SubPlugin\Plugin\PluginController@index");
|
|
RouteCollection::get("/form", "\App\SubPlugin\Plugin\PluginController@create");
|
|
RouteCollection::post("/", "\App\SubPlugin\Plugin\PluginController@store");
|
|
RouteCollection::get("/[i:id]", "\App\SubPlugin\Plugin\PluginController@show");
|
|
RouteCollection::put("/[i:id]", "\App\SubPlugin\Plugin\PluginController@update");
|
|
RouteCollection::patch("/[i:id]", "\App\SubPlugin\Plugin\PluginController@update");
|
|
RouteCollection::delete("/[i:id]", "\App\SubPlugin\Plugin\PluginController@destroy");
|
|
```
|
|
|
|
#### Laravel Compatibility (#ToDo)
|
|
|
|
It would be nice to add routes similar to how Laravel Does, avoiding the usage of the whole ClassPath
|
|
|
|
```php
|
|
<?php
|
|
use Routes\RouteCollection as RouteCollection;
|
|
|
|
RouteCollection::get("/", [PluginController:class, "index"]);
|
|
RouteCollection::get("/form", [PluginController:class, "create"]);
|
|
RouteCollection::post("/", [PluginController:class, "store"]);
|
|
RouteCollection::get("/[i:id]", [PluginController:class, "show"]);
|
|
RouteCollection::put("/[i:id]", [PluginController:class, "update"]);
|
|
RouteCollection::patch("/[i:id]", [PluginController:class, "update"]);
|
|
RouteCollection::delete("/[i:id]", [PluginController:class, "destroy"]);
|
|
```
|
|
|
|
#### RouteGroup
|
|
|
|
The library allows to nest routes on a `namespace`, applying the prefix on each route defined
|
|
|
|
```php
|
|
<?php
|
|
use Routes\RouteCollection as RouteCollection;
|
|
|
|
RouteCollection::group("/subplugin/plugin", function(){
|
|
RouteCollection::get("/", "\App\SubPlugin\Plugin\PluginController@index");
|
|
RouteCollection::get("/form", "\App\SubPlugin\Plugin\PluginController@create");
|
|
RouteCollection::post("/", "\App\SubPlugin\Plugin\PluginController@store");
|
|
RouteCollection::get("/[i:id]", "\App\SubPlugin\Plugin\PluginController@show");
|
|
RouteCollection::put("/[i:id]", "\App\SubPlugin\Plugin\PluginController@update");
|
|
RouteCollection::patch("/[i:id]", "\App\SubPlugin\Plugin\PluginController@update");
|
|
RouteCollection::delete("/[i:id]", "\App\SubPlugin\Plugin\PluginController@destroy");
|
|
});
|
|
```
|
|
|
|
#### Setup/Service Routes
|
|
|
|
This library allows you to create sintetic routes with housekeeping features, for example:
|
|
|
|
* Setup plugins configurations
|
|
* Building menus
|
|
* Manipulate data before executing routes
|
|
|
|
**This snippet merges the content from `php://input` and `$_POST` on weight -10**
|
|
```php
|
|
<?php
|
|
use Routes\RouteCollection as RouteCollection;
|
|
|
|
RouteCollection::add("WEB", "*", function () {
|
|
|
|
if (isset($_SERVER['REQUEST_METHOD']) && $_SERVER['REQUEST_METHOD'] != 'POST') {
|
|
return;
|
|
}
|
|
|
|
$_POST = array_merge($_POST, (array) json_decode(file_get_contents('php://input')));
|
|
|
|
}, -10)->notBlock()->doIgnore();
|
|
```
|
|
|
|
**This snippet create menus and submenus**
|
|
```php
|
|
<?php
|
|
use Routes\RouteCollection as RouteCollection;
|
|
|
|
RouteCollection::get('*', function() {
|
|
Output::addSubmenu('menuname', 'Item name', "<i class='fa fa-globe'></i>", ['class' => 'nav-link'] );
|
|
}, -11)->doIgnore();
|
|
|
|
RouteCollection::get('*', function () {
|
|
Output::addOnSubmenu('menuname', '/url', 'SubItem name', "", ['class' => 'nav-link']);
|
|
}, -10)->doIgnore();
|
|
```
|
|
|
|
## Routes Properties
|
|
|
|
The routes can have some properties configured on them. This section will Describe them
|
|
|
|
### Blocking
|
|
|
|
The routing system will iterate over all the registered routes, when a Route is matched and it's not configured to block the execution, more routes on the chain might match and be executed.
|
|
|
|
The default behavior of a Route is **TO BLOCK** the executions when it is executed, but this behavior can be changed with the `notBlock()` method
|
|
|
|
```php
|
|
<?php
|
|
use Routes\RouteCollection as RouteCollection;
|
|
|
|
// If executed, this route will not stop the matchin chain
|
|
RouteCollection::get('*', function() { })->notBlock();
|
|
```
|
|
|
|
### Ignore
|
|
|
|
If during the Routing process, the library didn't match any Route, a fallback `404` route will be executed. If you want a specific Route not to count on this process, you can ignore it with the function `doIgnore()`. The default behavior of routese is to **NOT IGNORE** the route.
|
|
|
|
Routes with this property assigned, will not prevent a `404` code. It is usefull for Setup/Service Routes.
|
|
|
|
```php
|
|
<?php
|
|
use Routes\RouteCollection as RouteCollection;
|
|
|
|
// This route will execute, but will not count. Make some setup or preparation with this functionality
|
|
RouteCollection::get('*', function() { })->doIgnore();
|
|
```
|
|
|
|
### Weight
|
|
|
|
When adding a Route, you can define it's weight. Before dispatching the routing process, the route set will be sorted and the routes will be checked on the specified order. The library will execute all routes until it get blocked, so the Route order might matter on the execution.
|
|
|
|
The weight is the third argument on `get|post|put|patch|delete` functions and the fouth on the `add` method. You can also mannually define the weight with the `setWeight(int $weight)` function.
|
|
|
|
```php
|
|
<?php
|
|
use Routes\RouteCollection as RouteCollection;
|
|
|
|
// This route has the wight 0, but it's redefined to -1
|
|
RouteCollection::get('*', function() { }, 0)->setWeight(-1);
|
|
```
|
|
|
|
### Name (#ToDo)
|
|
|
|
You can name your routes with the `name(string $name)` function
|
|
|
|
```php
|
|
<?php
|
|
use Routes\RouteCollection as RouteCollection;
|
|
|
|
RouteCollection::get("*", function(){ })->name('routeName');
|
|
```
|
|
|
|
### Tag (#ToDo)
|
|
|
|
You can tag your routes with the `setTag(string|array $key, string $value)` function
|
|
```php
|
|
<?php
|
|
use Routes\RouteCollection as RouteCollection;
|
|
|
|
RouteCollection::get("*", function(){ })->setTag('group', 'value');
|
|
|
|
// Not implemented yet
|
|
RouteCollection::get("*", function () { })->setTag(
|
|
[
|
|
['group', "value1"],
|
|
["group2", "value2"]
|
|
]
|
|
);
|
|
```
|
|
|
|
## Middlewares
|
|
|
|
The library provides a simple Middleware functionality.
|
|
|
|
You can register
|
|
* Named Middlewares
|
|
* AdHock Middlewares
|
|
* Global Middlewares
|
|
|
|
This middlewares can be attached or removed from the Routes
|
|
|
|
### General Middlewares
|
|
|
|
A general Middlewares can be created with the API `RouteCollection::registerMiddleware(string $name, callable $function)` and will be stored as available on the `RouteCollection` Singleton.
|
|
|
|
```php
|
|
<?php
|
|
use Routes\RouteCollection as RouteCollection;
|
|
|
|
RouteCollection::registerMiddleware("myMiddleware", function($param){
|
|
// Do some validation or stuff
|
|
});
|
|
```
|
|
|
|
This Middleware can be latter attached to Routes or RouteGroups with the function `middlewareAdd(string $name)`
|
|
|
|
```php
|
|
<?php
|
|
use Routes\RouteCollection as RouteCollection;
|
|
|
|
RouteCollection::get('*', function() { })->middlewareAdd("myMiddleware", Array("someValue"));
|
|
|
|
// #ToDo - Group Middlewares are not receaving parameters
|
|
RouteCollection::group("/group", function(){ })->middlewareAdd("myMiddleware", Array("someValue"));
|
|
```
|
|
|
|
### AdHock Middlewares
|
|
|
|
You can simply attach a function to be executed before the Route/Group execute with the `middlewareAppend(string $name, callable $callback)` function
|
|
|
|
```php
|
|
<?php
|
|
use Routes\RouteCollection as RouteCollection;
|
|
|
|
// #ToDo Routes do not have this functionality yet
|
|
RouteCollection::get('*', function() { })->middlewareAppend("myMiddleware", Array("someValue"));
|
|
|
|
// #ToDo Refactor the middleware API for the RouteGroup
|
|
RouteCollection::group("/group", function(){ })->middlewareAppend("myMiddleware", Array("someValue"));
|
|
```
|
|
|
|
### Default Middleware
|
|
|
|
Default middlewares can be registered on the `RouteCollection` with the function `addDefaultMiddleware(string $name, callable $function)` Singleton and will be executed before all Routes
|
|
|
|
```php
|
|
<?php
|
|
use Routes\RouteCollection as RouteCollection;
|
|
|
|
RouteCollection::addDefaultMiddleware("auth", function(Route $route){
|
|
// Do some auth validation here
|
|
});
|
|
```
|
|
|
|
A Route/RouteGroup can also ignore a Default Middleware with the function `middlewareIgnore(string $name)`
|
|
|
|
```php
|
|
<?php
|
|
use Routes\RouteCollection as RouteCollection;
|
|
|
|
// #ToDo Routes do not have this functionality yet
|
|
RouteCollection::get('*', function() { })->middlewareIgnore("auth");
|
|
```
|
|
|
|
## Server configuration
|
|
|
|
#### Requirements
|
|
|
|
The following packages need to be installed for the project to run
|
|
|
|
* Apache
|
|
- apache2 phpX.X phpX.X-fpm libapache2-mod-phpX.X
|
|
* Nginx
|
|
- nginx phpX.X phpX.X-fpm
|
|
|
|
The ports `80` and `443` must be open: `ufw allow 80 && ufw allow 443`
|
|
|
|
|
|
|
|
#### Apache
|
|
|
|
For apache, the basic required configuration
|
|
|
|
```
|
|
<VirtualHost *:80>
|
|
ServerAdmin webmaster@localhost
|
|
DocumentRoot /var/www/html/public
|
|
ServerName example.com
|
|
|
|
<Directory /var/www >
|
|
Options Indexes FollowSymLinks MultiViews
|
|
AllowOverride All
|
|
Order allow,deny
|
|
Allow from all
|
|
</Directory>
|
|
|
|
ErrorLog ${APACHE_LOG_DIR}/error.log
|
|
CustomLog ${APACHE_LOG_DIR}/access.log combined
|
|
</VirtualHost>
|
|
```
|
|
|
|
For a server with HTTPs, the configuration with redirection
|
|
|
|
```
|
|
<VirtualHost *:80>
|
|
ServerName example.com
|
|
Redirect / https://example.com
|
|
</VirtualHost>
|
|
|
|
<IfModule mod_ssl.c>
|
|
<VirtualHost *:443>
|
|
|
|
ServerAdmin webmaster@localhost
|
|
DocumentRoot /var/www/html/public
|
|
ServerName urfat.com.br
|
|
|
|
|
|
ErrorLog ${APACHE_LOG_DIR}/error.log
|
|
CustomLog ${APACHE_LOG_DIR}/access.log combined
|
|
|
|
SSLCertificateFile /etc/letsencrypt/live/example.com.br/fullchain.pem
|
|
SSLCertificateKeyFile /etc/letsencrypt/live/example.com.br/privkey.pem
|
|
Include /etc/letsencrypt/options-ssl-apache.conf
|
|
</VirtualHost>
|
|
</IfModule>
|
|
```
|
|
|
|
#### Nginx
|
|
|
|
*For Nginx,this is the basic required configuration with PHP-FPM*
|
|
|
|
```
|
|
server {
|
|
listen 82 default_server;
|
|
listen [::]:82 default_server;
|
|
|
|
server_name example.com;
|
|
|
|
root /var/www/html/public;
|
|
index index.php index.html index.htm index.nginx-debian.html;
|
|
|
|
server_name localhost;
|
|
|
|
location / {
|
|
try_files $uri $uri/ /index.php$is_args$args;
|
|
}
|
|
|
|
location ~ \.php$ {
|
|
include snippets/fastcgi-php.conf;
|
|
#Check fpm-version
|
|
fastcgi_pass unix:/run/php/php7.2-fpm.sock;
|
|
}
|
|
|
|
location ~ /\.ht {
|
|
deny all;
|
|
}
|
|
}
|
|
```
|
|
|
|
For a server with HTTPs, the configuration with redirection
|
|
|
|
```
|
|
server {
|
|
listen 80;
|
|
listen [::]:80;
|
|
listen 443 default_server ssl;
|
|
|
|
server_name example.com;
|
|
|
|
ssl_certificate /path/to/my/cert;
|
|
ssl_certificate_key /path/to/my/key;
|
|
|
|
ssl_session_cache shared:SSL:10m;
|
|
ssl_session_timeout 10m;
|
|
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
|
|
ssl_ciphers "ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+3DES:!aNULL:!MD5:!DSS:!AES256";
|
|
ssl_prefer_server_ciphers on;
|
|
ssl_dhparam /path/to/my/dhp-4096.pem #sudo openssl dhparam -out /path/to/my/dhp-4096.pem 4096
|
|
|
|
if ($scheme = http) {
|
|
return 301 https://$server_name$request_uri;
|
|
}
|
|
}
|
|
```
|
|
|
|
## Inner workings
|
|
|
|
The package consist in 3 main files, with `RouteCollection.php` providing the main API
|
|
|
|
- `Route.php` => Stores each route information
|
|
- `RouteCollection.php` => Aggregate all routes and provide a interface to interact with the routes dataset
|
|
- `RouteGroup.php` => Aggregate a group of routes based on their namespaces
|
|
|
|
The class `RouteCollection` is treated as a Singleton that return it's own global instance when loaded. The main interface would be something like: `RouteCollection::add($verb, $uri, $callback, $weight = 0)`, this method will return the instance of the `Route` object, so that the Route properties can be configured
|
|
|
|
*Route settings:*
|
|
- `RouteCollection::add($verb, $uri, $callback, $weight = 0)->doBlock()`
|
|
- After this route execute, no more routes would be executed
|
|
- `RouteCollection::add($verb, $uri, $callback, $weight = 0)->notBlock()`
|
|
- The execution of this route will not block the execution of the next routes
|
|
- `RouteCollection::add($verb, $uri, $callback, $weight = 0)->doIgnore()`
|
|
- This route will not count as a executed route, so a 404 can be detected
|
|
- `RouteCollection::add($verb, $uri, $callback, $weight = 0)->middlewareIgnore($name = '')`
|
|
- This route will not execute a registered global middleware
|
|
- `RouteCollection::add($verb, $uri, $callback, $weight = 0)->middlewareAdd($name = '', $params = [])`
|
|
- Register that this route must pass by a registered middleware
|
|
- `RouteCollection::add($verb, $uri, $callback, $weight = 0)->middlewareAppend($name = '', $function)`
|
|
- Append a ad-hock middleware to this specific route
|
|
- `RouteCollection::add($verb, $uri, $callback, $weight = 0)->setWeight($weigth = 0)`
|
|
- Define the priority of this route on the execution chain
|
|
- `RouteCollection::add($verb, $uri, $callback, $weight = 0)->setName($name)`
|
|
- Add a property name for the route object
|
|
- `RouteCollection::add($verb, $uri, $callback, $weight = 0)->setTag($key = '', $value = '')`
|
|
- Add a custom arbitrary tag on the route object
|
|
|
|
|
|
|
|
## Other resources
|
|
https://stackoverflow.com/questions/8054165/using-put-method-in-html-form
|