add comments to Libs.

src/Libs/Router.php

@@ -1,19 +1,44 @@
 <?php
+/*
+* DuckBrain - Microframework
+*
+* Librería de Enrrutador. 
+* Depende de manera forzada de que la constante ROOT_DIR esté definida
+* y de manera optativa de que la constante SITE_URL lo esté también.
+*
+* Autor: KJ
+* Web: https://kj2.me
+* Licencia: MIT
+*/
 
 namespace Libs;
 
 use Libs\Request;
 
-class Router{
+class Router {
   private static $get = [];
   private static $post = [];
   private static $put = [];
   private static $delete = [];
   private static $last;
   
-  private function __construct(){}
+  private function __construct() {}
   
-  private static function parse($path, $callback){
+  /*
+  * Parsea para deectar las pseudovariables (ej: {variable})
+  *
+  * @param string $path
+  *   URI con pseudovariables
+  *
+  * @param function $callback
+  *   Función en formato Clase::Método que será llamada cuando la url y el método coincidan
+  *
+  * @return array
+  *   Arreglo con 2 índices:
+  *     path        - Contiene la URI con la pseudovariables reeplazadas por expresiones regulares
+  *     callback    - Contiene el callback en formato Namespace\Clase::Método
+  */
+  private static function parse($path, $callback) {
     $path = preg_quote($path, '/');
     $path = preg_replace(
             ['/\\\{[\w-]+\\\}/s'],
@@ -29,15 +54,38 @@ class Router{
     ];
   }
   
-  public static function baseURI(){
+  
+  /*
+  * Devuelve el path o URI base sobre la que trabajará el router.
+  *
+  * Ej: Si la url del sistema está en "https://ejemplo.com/duckbrain"
+  *     entonces la URI base sería "/duckbrain" 
+  */
+  public static function baseURI() {
+    if (defined('SITE_URL'))
+      return parse_url(SITE_URL, PHP_URL_PATH);
     return str_replace($_SERVER['DOCUMENT_ROOT'],'/', ROOT_DIR);
   }
   
-  public static function redirect($uri){
+  /*
+  * Redirije a una ruta relativa interna.
+  *
+  * @param string $uri
+  *   La URI relativa a la URI base.
+  *
+  * Ej: Si nuesto sistema está en "https://ejemplo.com/duckbrain"
+  *     llamamos a Router::redirect('/docs'), entonces seremos
+  *     redirigidos a "https://ejemplo.com/duckbrain/docs".
+  */
+  public static function redirect($uri) {
     header('Location: '.self::baseURI().substr($uri,1));
   }
   
-  public static function middleware($middleware){ // Solo soporta un middleware a la vez
+  /*
+  * Añade un middleware a la última ruta usada.
+  * Solo se puede usar un middleware a la vez.
+  */
+  public static function middleware($middleware){
     if (!isset(self::$last)) return;
     
     $method = self::$last[0];
@@ -45,14 +93,16 @@ class Router{
     
     self::$$method[$index]['middleware'] = 'Middlewares\\'.$middleware;
   }
-
-  public static function get($path, $callback){
-    self::$get[] = self::parse($path, $callback);
-    self::$last = ['get', count(self::$get)-1];
-    return new static();
-  }
   
-  private static function params(){
+  /*
+  * @return object
+  *   Devuelve un objeto que contiene los atributos:
+  *     post  - Donde se encuentran los valores enviados por $_POST
+  *     get   - Donde se encuentran los valores enviados por $_GET
+  *     json  - Donde se encuentran los valores JSON enviados en el body
+  *
+  */
+  private static function params() {
     $args             = (object) '';
     $args->get        = new Params($_GET);
     $args->post       = new Params($_POST);
@@ -60,37 +110,120 @@ class Router{
     return $args;
   }
   
-  private static function get_json(){
+  /*
+  * @return object
+  *   Devuelve un objeto con los datos recibidos en JSON
+  */
+  private static function get_json() {
     $contentType = isset($_SERVER["CONTENT_TYPE"]) ? trim($_SERVER["CONTENT_TYPE"]) : '';
-    if ($contentType === "application/json"){
+    if ($contentType === "application/json") {
       return json_decode(trim(file_get_contents("php://input")));
     }
     return (object) '';
   }
   
-  public static function post($path, $callback){
+  /*
+  * Define los routers para el método GET.
+  *
+  * @param string $path
+  *   URI con pseudovariables
+  *
+  * @param function $callback
+  *   Función en formato Clase::Método que será llamada cuando la url y el método coincidan
+  *
+  * @return static
+  *   Devuelve un enlace estático
+  */
+  public static function get($path, $callback) {
+    self::$get[] = self::parse($path, $callback);
+    self::$last = ['get', count(self::$get)-1];
+    return new static();
+  }
+  
+  /*
+  * Define los routers para el método POST.
+  *
+  * @param string $path
+  *   URI con pseudovariables
+  *
+  * @param function $callback
+  *   Función en formato Clase::Método que será llamada cuando la url y el método coincidan
+  *
+  * @return static
+  *   Devuelve un enlace estático
+  */
+  public static function post($path, $callback) {
     self::$post[] = self::parse($path, $callback);
     self::$last   = ['post', count(self::$post)-1];
     return new static();
   }
   
-  public static function put($path, $callback){
+  public static function put($path, $callback) {
     self::$put[]  = self::parse($path, $callback);
     self::$last   = ['put', count(self::$put)-1];
     return new static();
   }
   
-  public static function delete($path, $callback){
+  /*
+  * Define los routers para el método DELETE.
+  *
+  * @param string $path
+  *   URI con pseudovariables
+  *
+  * @param function $callback
+  *   Función en formato Clase::Método que será llamada cuando la url y el método coincidan
+  *
+  * @return static
+  *   Devuelve un enlace estático
+  */
+  public static function delete($path, $callback) {
     self::$delete[] = self::parse($path, $callback);
     self::$last     = ['delete', count(self::$put)-1];
     return new static();
   }
   
-  public static function apply(){
+  /*
+  * Aplica los routers.
+  * 
+  * Este método ha de ser llamado luego de que todos los routers hayan sido configurados.
+  *
+  * En caso que la URI actual coincida con un router configurado,
+  * pueden suecedor los siguientes casos:
+  *
+  * 1. Tiene pseudovariables por URI
+  *
+  *   1.1. Tiene middleware, por lo que se llama al middleware enviándole los datos
+  *        en el siguiente orden:
+  *           - Función callback del router
+  *           - Objeto que contiene $_POST, $_GET y el JSON recibido
+  *           - Todas las pseudovariables (en el mismo orden que están escritas)
+  *
+  *   1.1. No tiene middleware, por lo que se llama a la función callback del router
+  *        enviándole los datos en el siguiente orden:
+  *           - Todas las pseudovariables (en el mismo orden que están escritas)
+  *           - Objeto que contiene $_POST, $_GET y el JSON recibido
+  *   
+  * 2. No tiene pseudovariables por URI
+  *
+  *   2.1. Tiene middleware, por lo que se llama al middleware enviándole los datos
+  *        En el siguiente orden:
+  *           - Función callback del router
+  *           - Todas las pseudovariables (en el mismo orden que están escritas)
+  *
+  *   2.2. No tiene middleware, por lo que se llama a la función callback del router
+  *        enviándole solo ún parámetro:
+  *           - Objeto que contiene $_POST, $_GET y el JSON recibido
+  *
+  * Nota: Gracias a que se usa call_user_func_array, los callbacks no es necesario que reciban
+  *       la misma cantidad de parámetros que se les envía. De ese modo, pueden recibir solo
+  *       los parámetros que van a utilizar, con el detalle de que siempre se respeta el orden
+  *       especificado anteriormente a la hora de recibirlos.
+  */
+  public static function apply() {
     $uri =  preg_replace('/'.preg_quote(self::baseURI(), '/').'/',
             '/', strtok($_SERVER['REQUEST_URI'], '?'), 1);
     $routers = [];
-    switch ($_SERVER['REQUEST_METHOD']){
+    switch ($_SERVER['REQUEST_METHOD']){ // Según el método selecciona un arreglo de routers configurados
       case 'POST':
         $routers = self::$post;
         break;
@@ -105,35 +238,35 @@ class Router{
         break;
     }
     
-    foreach ($routers as $router){
+    foreach ($routers as $router) { // revisa todos los routers para ver si coinciden con la URI actual
       if (preg_match_all('/^'.$router['path'].'\/?$/si',$uri, $matches)){
         unset($matches[0]);
         $args = self::params();
         
-        if (isset($matches[1])){
+        if (isset($matches[1])) { // Caso 1 - Con pseudovariables por URI
           $params = [];
-          foreach ($matches as $match){
+          foreach ($matches as $match) {
             if (!empty($match))
               $params[] = "$match[0]";
           }
           
-          if (isset($router['middleware'])){
+          if (isset($router['middleware'])) { // Caso 1.1 - Con middleware
             $middleware = explode('::',$router['middleware']);
             $data = call_user_func_array($middleware, [$router['callback'], $args, $params]);
-          } else {
+          } else { // Caso 1.2 - Sin middleware
             $params[] = $args;
             $data = call_user_func_array($router['callback'], $params); 
           }
-        }else{
-          if (isset($router['middleware'])){
+        } else { // Caso 2 - Sin Pseudo variables por URI
+          if (isset($router['middleware'])) { // Caso 2.1 - Con middleware
             $middleware = explode('::',$router['middleware']);
             $data = call_user_func_array($middleware, [$router['callback'], $args]);
-          } else {
+          } else { // Caso 2.2 - Sin middleware
             $data = call_user_func_array($router['callback'], [$args]);
           }
         }
         
-        if (isset($data)){
+        if (isset($data)) {
           header('Content-Type: application/json');
           print(json_encode($data));
         }
@@ -141,7 +274,7 @@ class Router{
         return;
       }
     }
-    header("HTTP/1.0 404 Not Found");
+    header("HTTP/1.0 404 Not Found"); // Si no hay router que coincida, se devuelve error 404
     echo '<h2 style="text-align: center;margin: 25px 0px;">Error 404 - Página no encontrada</h2>';
   }
 }