Addin a lot of changes

2026-08-20 00:20:17 -03:00
parent 03e9f93e00
commit 795062bb6d
5 changed files with 1082 additions and 468 deletions
@@ -13,14 +13,293 @@ A simple and dependency free routing system providing:
 ### 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"
 }],
 ```

-### Server configuration
+
+#### 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

@@ -33,6 +312,8 @@ The following packages need to be installed for the project to run

 The ports `80` and `443` must be open: `ufw allow 80 && ufw allow 443`

+
+
 #### Apache

 For apache, the basic required configuration
@@ -139,23 +420,6 @@ server {
 }
 ```

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