routes/README.md

# 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

```
"repositories": [{
    "type": "composer",
    "url": "https://satis.domain.com"
}],
```

### 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;
    }
}
```

#### Hello World

With the dependencies and the server with the correct configuration, create a index.php with the content

```
<?php

include_once 'vendor/autoload.php';
use Routes\RouteCollection as RouteCollection;

RouteCollection::get ("/", function(){
    echo "Hello World";
});

RouteCollection::getInstance()->submit();
```

## 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