refactor(validator): rename enum rule and method to in

70b1016 refactor(autoload): remove global exception handler
a534613 refactor(request): propagate validation failures as exceptions
5f3fc16 feat(router): add error boundary with exception callback
9dbfd7d feat: add named parameter injection to resolve()

.htaccess

@@ -1,6 +1,9 @@
 <IfModule mod_rewrite.c>
     RewriteEngine On
 
+    # Bloquear acceso a las carpetas vendor/ y src/
+    RewriteRule ^(vendor|src)/.*$ - [F,L]
+
     # Handle Front Controller...
     RewriteCond %{REQUEST_FILENAME} !-d
     RewriteCond %{REQUEST_FILENAME} !-f

autoload.php

@@ -0,0 +1,14 @@
+<?php
+
+require_once('config.php');
+
+// Autoloader for the core classes
+spl_autoload_register(function ($className) {
+    $fp = str_replace('\\', '/', $className);
+    $name = basename($fp);
+    $dir  = dirname($fp);
+    $file = ROOT_CORE . '/' . $dir . '/' . $name . '.php';
+    if (file_exists($file)) {
+        require_once $file;
+    }
+});

config.php

@@ -1,15 +1,15 @@
 <?php
 
-// Configuración de la base de datos
+// Database configuration
 define('DB_TYPE', 'mysql');
 define('DB_HOST', 'localhost');
 define('DB_NAME', '');
 define('DB_USER', '');
 define('DB_PASS', '');
 
-// Configuración del sitio
+// Site configuration
 define('SITE_URL', '');
 
-// Configuración avanzada
+// Advanced configuration
 define('ROOT_DIR', __DIR__);
 define('ROOT_CORE', ROOT_DIR . '/src');

index.php

@@ -1,23 +1,15 @@
 <?php
 
-require_once('config.php');
+use Libs\Loader;
+use Libs\Router;
 
-// Incluir clases
-spl_autoload_register(function ($className) {
-    $fp = str_replace('\\', '/', $className);
-    $name = basename($fp);
-    $dir  = dirname($fp);
-    $file = ROOT_CORE . '/' . $dir . '/' . $name . '.php';
-    if (file_exists($file)) {
-        require_once $file;
-    }
-});
+require_once('autoload.php');
 
-// Incluir routers
-$routers = glob(ROOT_CORE . '/Routers/*.php');
+// Router autoload
+Loader::load(ROOT_CORE . '/Routers/');
 
-foreach ($routers as $file) {
-    require_once($file);
-}
+// Other autoloads
+Loader::load(ROOT_CORE . '/Autoloads/');
 
-\Libs\Router::apply();
+// Run the routers
+Router::apply();

readme.org

@@ -28,79 +28,91 @@ En la siguiente tabla se encuentra la lista de estados de los gestores de bases
 + *En blanco* como que no ha sido probado aún.
 + *error* como que fue probado, no funciona y no ha sido aún arreglado.
 + *not supported* como no soportado por el gestor de bases de datos.
-+ *fixed* para aquello que no existe en el gestor de DB, pero la librería lo traduce a un equivalente.
++ *fixed* para aquello que no existe en el gestor de BD, pero la librería lo traduce a un equivalente.
 
-|------------------+---------------+---------------+------------|
-| method           | MySQL/MariaDB | sqlite3       | postgreSQL |
-|------------------+---------------+---------------+------------|
-| db               | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| query            | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| resetQuery       | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| buildQuery       | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| getInstance      | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| getVars          | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| className        | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| table            | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| update           | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| beginTransaction | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| rollBack         | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| commit           | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| add              | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| save             | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| delete           | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| select           | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| from             | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| where            | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| where_in         | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| leftJoin         | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| rightJoin        | ok            | not supported |            |
-|------------------+---------------+---------------+------------|
-| innerJoin        | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| and              | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| or               | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| groupBy          | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| limit            | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| orderBy          | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| count            | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| getById          | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| search           | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| get              | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| getFirst         | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| all              | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
-| setNull          | ok            | ok            |            |
-|------------------+---------------+---------------+------------|
+|------------------+---------------+---------+------------|
+| method           | MySQL/MariaDB | sqlite3 | postgreSQL |
+|------------------+---------------+---------+------------|
+| db               | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| query            | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| resetQuery       | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| buildQuery       | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| getInstance      | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| getVars          | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| className        | ok            | ok      | pk         |
+|------------------+---------------+---------+------------|
+| table            | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| update           | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| beginTransaction | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| rollBack         | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| commit           | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| add              | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| save             | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| delete           | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| select           | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| from             | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| where            | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| whereIn          | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| whereNotIn       | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| whereNull        | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| whereNotNull     | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| whereExists      | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| whereNotExists   | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| leftJoin         | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| rightJoin        | ok            | fixed   | ok         |
+|------------------+---------------+---------+------------|
+| innerJoin        | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| crossJoin        | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| and              | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| or               | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| groupBy          | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| limit            | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| orderBy          | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| count            | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| getById          | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| search           | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| get              | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| getFirst         | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| all              | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
+| setNull          | ok            | ok      | ok         |
+|------------------+---------------+---------+------------|
 
 * Contacto
 

src/Libs/Database.php

@@ -9,24 +9,28 @@ use PDOException;
 /**
  * Database - DuckBrain
  *
- * Clase diseñada para crear y devolver una única instancia PDO (database).
+ * Class designed to create and return a single PDO instance (database).
  *
  * @author KJ
  * @website https://kj2.me
- * @licence MIT
+ * @license MIT
  */
 class Database extends PDO
 {
     private static array $databases = [];
 
+    /**
+     * Private constructor to prevent direct instantiation.
+     */
     private function __construct()
     {
     }
 
     /**
-     * Devuelve una instancia homogénea (singlenton) de la base de datos (PDO).
+     * Returns a homogeneous (singleton) instance of the database (PDO).
      *
      * @return PDO
+     * @throws Exception If there is an error connecting to the database.
      */
     public static function getInstance(
         string $type = 'mysql',

src/Libs/Loader.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace Libs;
+
+/**
+ * Loader - DuckBrain
+ *
+ * Simple library to bulk load multiple php files inside a folder.
+ *
+ * @author KJ
+ * @website https://kj2.me
+ * @license MIT
+ */
+class Loader
+{
+    /**
+     * Loads all PHP files from a specified directory.
+     * If the directory does not exist or is not a directory, no files will be loaded.
+     *
+     * @param  string $directoryPath The path to the directory containing the PHP files to load.
+     * @return void
+     */
+    public static function load(string $directoryPath): void
+    {
+        if (is_dir($directoryPath)) {
+            foreach (glob(rtrim($directoryPath, '/') . '/*.php') as $file) {
+                require_once($file);
+            }
+        }
+    }
+}

src/Libs/Neuron.php

@@ -7,25 +7,25 @@ use AllowDynamicProperties;
 /**
  * Neuron - DuckBrain
  *
- * Neuron, sirve para crear un objeto que alojará valores.
- * Además, tiene la característica especial de que al intentar
- * acceder a una propiedad no definida, devolverá null en
- * lugar de generar un aviso (PHP notice) por variable o propiedad no definida.
+ * Neuron, serves to create an object that will hold values.
+ * In addition, it has the special characteristic that when trying
+ * to access an undefined property, it will return null instead
+ * of generating a notice (PHP notice) for an undefined variable or property.
  *
- * El constructor acepta un objeto o un arreglo que contiene los
- * valores que estarán definidos.
+ * The constructor accepts an object or an array containing the
+ * values that will be defined.
  *
  * @author KJ
  * @website https://kj2.me
- * @licence MIT
+ * @license MIT
  */
 #[AllowDynamicProperties]
 class Neuron
 {
     /**
-     * __construct
+     * Constructor
      *
-     * @param array $data
+     * @param array $data Data to initialize the Neuron with. Can be an array or an object.
      */
     public function __construct(...$data)
     {
@@ -44,12 +44,15 @@ class Neuron
     }
 
     /**
-     * __get
+     * Magic method __get
      *
-     * @param  string $index
-     * @return null
+     * This method is called when an undefined property is accessed.
+     * It returns null instead of triggering an E_NOTICE.
+     *
+     * @param  string $index The name of the property being accessed.
+     * @return null   Always returns null for undefined properties.
      */
-    public function __get(string $index): null
+    public function __get(string $index)
     {
         return null;
     }

src/Libs/Request.php

@@ -2,15 +2,17 @@
 
 namespace Libs;
 
+use Exception;
+
 /**
  * Request - DuckBrain
  *
- * Libería complementaria de la libería Router.
- * Contiene el cuerpo básico de la petición http (POST, GET, JSON, etc).
+ * Complementary library to the Router library.
+ * Contains the basic body of the http request (POST, GET, JSON, etc).
  *
  * @author KJ
  * @website https://kj2.me
- * @licence MIT
+ * @license MIT
  */
 class Request extends Neuron
 {
@@ -27,8 +29,6 @@ class Request extends Neuron
 
     /**
      * __construct
-     *
-     * @param string $path Ruta actual tomando como raíz la instalación de DuckBrain.
      */
     public function __construct()
     {
@@ -38,7 +38,7 @@ class Request extends Neuron
         $this->put    = new Neuron();
         $this->patch  = new Neuron();
         $this->delete = new Neuron();
-        $this->params = new Neuron(Router::$currentParams);
+        $this->params = Router::$params ?? new Neuron();
         $this->body   = file_get_contents("php://input");
 
         $contentType = isset($_SERVER["CONTENT_TYPE"]) ? trim($_SERVER["CONTENT_TYPE"]) : '';
@@ -52,52 +52,61 @@ class Request extends Neuron
                 in_array($_SERVER['REQUEST_METHOD'], ['PUT', 'PATCH', 'DELETE']) &&
                 preg_match('/^[^;?\/:@&=+$,]{1,255}[=]/', $this->body, $matches)
             ) {
-                // Con la expresión regular verificamos que sea un http
-                // query string válido y evitamos errores de memoria en caso
-                // de que el body tenga algo más grande que eso.
+                // With the regular expression, we verify that it is a valid
+                // http query string and avoid memory errors in case
+                // the body contains something larger than that.
                 parse_str($this->body, $input_vars);
                 $this->{strtolower($_SERVER['REQUEST_METHOD'])} = new Neuron($input_vars);
             }
         }
 
-        // Corremos las validaciones configuradas
-        if (!$this->validate()) {
-            exit();
-        }
+        // Run configured validations
+        $this->validate();
     }
 
     /**
-     * Inicia la validación que se haya configurado.
+     * Starts the configured validation.
      *
-     * @return bool
+     * On failure the single error message is built with Validator::message()
+     * and handed to onInvalid(), which throws by default: failures travel up
+     * as exceptions instead of answering HTTP here.
+     *
+     * @return void
+     * @throws Exception When a configured rule fails.
      */
-    public function validate(): bool
+    public function validate(): void
     {
         $actual = match ($_SERVER['REQUEST_METHOD']) {
             'POST', 'PUT', 'PATCH', 'DELETE' => $this->{strtolower($_SERVER['REQUEST_METHOD'])},
             default => $this->get
         };
 
+        // Merge uploaded files ($_FILES) into the body data set so the file rules
+        // (file/image/mimes and the routed min/max/required...) can validate
+        // uploads through a Request. $this->post is left untouched.
+        $body = empty($_FILES)
+            ? $actual
+            : new Neuron(array_merge(get_object_vars($actual), $_FILES));
+
         if (
             Validator::validateList(static::paramRules(), $this->params) &&
             Validator::validateList(static::getRules(), $this->get) &&
-            Validator::validateList(static::rules(), $actual)
+            Validator::validateList(static::rules(), $body)
         ) {
-            return true;
+            return;
         }
 
-        if (isset(static::messages()[Validator::$lastFailed])) {
-            $error =  static::messages()[Validator::$lastFailed];
-        } else {
-            $error = 'Error: validation failed of ' . preg_replace('/\./', ' as ', Validator::$lastFailed, 1);
-        }
+        $error = Validator::message(
+            Validator::$lastFailed,
+            static::messages(),
+            static::attributes()
+        );
 
         static::onInvalid($error);
-        return false;
     }
 
     /**
-     * Reglas para el método actual.
+     * Rules for the current method.
      *
      * @return array
      */
@@ -107,7 +116,7 @@ class Request extends Neuron
     }
 
     /**
-     * Reglas para los parámetros por URL.
+     * Rules for URL parameters.
      *
      * @return array
      */
@@ -117,7 +126,7 @@ class Request extends Neuron
     }
 
     /**
-     * Reglas para los parámetros GET.
+     * Rules for GET parameters.
      *
      * @return array
      */
@@ -127,7 +136,7 @@ class Request extends Neuron
     }
 
     /**
-     * Mensajes de error en caso de fallar una validación.
+     * Error messages in case a validation fails.
      *
      * @return array
      */
@@ -137,15 +146,35 @@ class Request extends Neuron
     }
 
     /**
-     * Función a ejecutar cuando se ha detectado un valor no válido.
+     * Human-readable names for the fields.
+     *
+     * Forwarded to Validator::message() so the :attribute marker in the error
+     * text can be replaced with a friendlier name (e.g. "edad" => "la edad").
+     *
+     * @return array
+     */
+    public function attributes(): array
+    {
+        return [];
+    }
+
+    /**
+     * Function to execute when an invalid value has been detected.
+     *
+     * The default implementation always throws a generic \Exception carrying
+     * the single error message and HTTP 422 as its code; the framework's
+     * exception boundary (Router::apply) renders the response. Override it to
+     * throw a more specific exception type instead. The never return type is
+     * the contract: an override that returned would let the request continue
+     * with invalid data, so PHP rejects such an override at compile time.
      *
      * @param string $error
      *
-     * @return void
+     * @return never
+     * @throws Exception
      */
-    public function onInvalid(string $error): void
+    public function onInvalid(string $error): never
     {
-        http_response_code(422);
-        print($error);
+        throw new Exception($error, 422);
     }
 }

src/Libs/Router.php

@@ -5,35 +5,111 @@ namespace Libs;
 /**
  * Router - DuckBrain
  *
- * 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.
+ * Router library.
+ * It strictly depends on the ROOT_DIR constant being defined
+ * and optionally on the SITE_URL constant being defined.
  *
  * @author KJ
  * @website https://kj2.me
- * @licence MIT
+ * @license MIT
  */
 class Router
 {
-    private static $get    = [];
-    private static $post   = [];
-    private static $put    = [];
-    private static $patch  = [];
-    private static $delete = [];
-    private static $last;
-    public static $currentParams = [];
-    public static $notFoundCallback = 'Libs\Router::defaultNotFound';
+    private static array $get    = [];
+    private static array $post   = [];
+    private static array $put    = [];
+    private static array $patch  = [];
+    private static array $delete = [];
 
     /**
-     * Función callback por defectio para cuando
-     * no se encuentra configurada la ruta.
+     * Stores a temporary stack of middlewares to be applied to routes defined
+     * within a specific scope, typically configured by `withMiddleware()`.
+     * These middlewares are active only during the execution of the scope's callback.
+     *
+     * @var array $withMiddlewares<callable>
+     */
+    private static array $withMiddlewares = [];
+
+    /**
+     * Stores the method and index of the last configured route, e.g., ['get', 0].
+     * Used for chaining methods like middleware() or reconfigure().
+     *
+     * @var array $last
+     */
+    private static array $last;
+
+    /**
+     * Stores the parameters extracted from the current matching route.
+     *
+     * @var Neuron $params
+     */
+    public static Neuron $params;
+
+    /**
+     * The callback function to be executed when no route matches.
+     *
+     * @var callable $notFoundCallback
+     */
+    public static $notFoundCallback =  'Libs\Router::defaultNotFound';
+
+    /**
+     * Default callback function for when
+     * the route is not found.
      *
      * @return void
      */
     public static function defaultNotFound(): void
     {
         header("HTTP/1.0 404 Not Found");
-        echo '<h2 style="text-align: center;margin: 25px 0px;">Error 404 - Página no encontrada</h2>';
+        echo '<h2 style="text-align: center;margin: 25px 0px;">Error 404 - Page Not Found</h2>';
+    }
+
+    /**
+     * The callback function to be executed when the router's boundary
+     * catches an exception thrown anywhere in the matched route chain.
+     * It receives the exception as a named argument: the handler must
+     * declare its parameter as $exception (typeable as \Throwable).
+     *
+     * @var callable $exceptionCallback
+     */
+    public static $exceptionCallback = 'Libs\Router::defaultException';
+
+    /**
+     * Default callback function for exception responses.
+     *
+     * The HTTP status comes from the exception's code only when it is an
+     * integer in the 400-599 range; anything else (0, arbitrary codes, the
+     * SQLSTATE string carried by PDOException) answers 500. The body is
+     * negotiated from the request's Accept header: JSON when the client asks
+     * for application/json, plain text otherwise. The trace is serialized
+     * from getTraceAsString() because json_encode() of a Throwable yields an
+     * empty object: its properties are protected.
+     *
+     * @param \Throwable $exception
+     *
+     * @return void
+     */
+    public static function defaultException(\Throwable $exception): void
+    {
+        $code = $exception->getCode();
+        http_response_code(is_int($code) && $code >= 400 && $code <= 599 ? $code : 500);
+
+        $accept = $_SERVER['HTTP_ACCEPT'] ?? '';
+
+        if (str_contains($accept, 'application/json')) {
+            header('Content-Type: application/json');
+            print(json_encode([
+                'error'     => $exception->getMessage(),
+                'exception' => get_class($exception),
+                'file'      => $exception->getFile(),
+                'line'      => $exception->getLine(),
+                'trace'     => explode(PHP_EOL, $exception->getTraceAsString()),
+            ]));
+
+            return;
+        }
+
+        print($exception->getMessage() . PHP_EOL . $exception->getTraceAsString());
     }
 
     /**
@@ -44,18 +120,19 @@ class Router
     }
 
     /**
-     * Parsea para deectar las pseudovariables (ej: {variable})
+     * Parses to detect pseudovariables (e.g., {variable})
      *
      * @param string $path
-     *                     Ruta con pseudovariables.
+     *                     Route with pseudovariables.
      *
      * @param callable $callback
-     *                           Callback que será llamado cuando la ruta configurada en $path coincida.
+     *                           Callback that will be called when the route configured in $path matches.
      *
      * @return array
-     *               Arreglo con 2 índices:
-     *               path        - Contiene la ruta con las pseudovariables reeplazadas por expresiones regulares.
-     *               callback    - Contiene el callback en formato Namespace\Clase::Método.
+     *               Array with 3 indices:
+     *               path        - Contains the route with pseudovariables replaced by regular expressions.
+     *               callback    - Contains the callback in Namespace\Class::Method format.
+     *               paramNames  - An array of parameter names found in the path.
      */
     private static function parse(string $path, callable $callback): array
     {
@@ -78,10 +155,10 @@ class Router
 
 
     /**
-     * Devuelve el ruta base o raiz del proyecto sobre la que trabajará el router.
+     * Returns the base or root path of the project on which the router will work.
      *
-     * Ej: Si la url del sistema está en "https://ejemplo.com/duckbrain"
-     *     entonces la ruta base sería "/duckbrain"
+     * Ex: If the system URL is "https://example.com/duckbrain"
+     *     then the base path would be "/duckbrain"
      *
      * @return string
      */
@@ -94,31 +171,30 @@ class Router
     }
 
     /**
-     * Redirije a una ruta relativa interna.
+     * Redirects to an internal relative path.
      *
      * @param string $path
-     *                     La ruta relativa a la ruta base.
+     *                     The path relative to the base path.
      *
-     * Ej: Si nuesto sistema está en "https://ejemplo.com/duckbrain"
-     *     llamamos a Router::redirect('/docs'), entonces seremos
-     *     redirigidos a "https://ejemplo.com/duckbrain/docs".
+     * Ex: If our system is at "https://example.com/duckbrain"
+     *     and we call Router::redirect('/docs'), we will be
+     *     redirected to "https://example.com/duckbrain/docs".
      * @return void
      */
     public static function redirect(string $path): void
     {
         header('Location: ' . static::basePath() . ltrim($path, '/'));
-        exit;
     }
 
     /**
-     * Añade un middleware a la última ruta usada.
-     * Solo se puede usar un middleware a la vez.
+     * Adds a middleware to the last used route.
+     * Only one middleware can be added at a time.
      *
      * @param callable $callback
-     * @param int      $prioriry
+     * @param int|null $priority Optional priority for the middleware execution order.
      *
      * @return static
-     *                Devuelve la instancia actual.
+     *                Returns the current instance.
      */
     public static function middleware(callable $callback, ?int $priority = null): static
     {
@@ -147,7 +223,29 @@ class Router
     }
 
     /**
-     * Reconfigura el callback final de la última ruta.
+     * Temporarily applies a set of middlewares to routes defined within a given callback.
+     * The middlewares are only active for the duration of the callback execution
+     * and are reset afterwards.
+     *
+     * @param callable $middleware
+     * @param callable $callback
+     *
+     * @return static
+     */
+    public static function withMiddleware(callable $middleware, callable $callback): static
+    {
+        $currentMiddlewares = static::$withMiddlewares;
+        array_unshift(static::$withMiddlewares, $middleware);
+
+        $callback();
+
+        static::$withMiddlewares = $currentMiddlewares; // Restore withMiddleware
+
+        return new static();
+    }
+
+    /**
+     * Reconfigures the final callback of the last route.
      *
      * @param callable $callback
      *
@@ -168,20 +266,20 @@ class Router
     }
 
     /**
-     * Configura calquier método para todas las rutas.
+     * Configures any method for all routes.
      *
-     * En caso de no recibir un callback, busca la ruta actual
-     * solo configura la ruta como la última configurada
-     * siempre y cuando la misma haya sido configurada previamente.
+     * If no callback is received, it searches for the current route
+     * and only sets the route as the last configured one
+     * provided it has been configured previously.
      *
      * @param string        $method
-     *                                Método http.
+     *                                HTTP method.
      * @param string        $path
-     *                                Ruta con pseudovariables.
+     *                                Route with pseudovariables.
      * @param callable|null $callback
      *
-     * @return
-     *    Devuelve la instancia actual.
+     * @return static
+     *                Returns the current instance.
      */
     public static function configure(string $method, string $path, ?callable $callback = null): static
     {
@@ -205,19 +303,24 @@ class Router
 
         static::$$method[] = static::parse($path, $callback);
         static::$last = [$method, count(static::$$method) - 1];
+
+        foreach (static::$withMiddlewares as $middleware) {
+            static::middleware($middleware);
+        }
+
         return new static();
     }
 
     /**
-     * Define los routers para el método GET.
+     * Defines routers for the GET method.
      *
      * @param string        $path
-     *                                Ruta con pseudovariables.
+     *                                Route with pseudovariables.
      * @param callable|null $callback
-     *                                Callback que será llamado cuando la ruta configurada en $path coincida.
+     *                                Callback that will be called when the route configured in $path matches.
      *
      * @return static
-     *                Devuelve la instancia actual.
+     *                Returns the current instance.
      */
     public static function get(string $path, ?callable $callback = null): static
     {
@@ -225,15 +328,15 @@ class Router
     }
 
     /**
-     * Define los routers para el método POST.
+     * Defines routers for the POST method.
      *
      * @param string        $path
-     *                                Ruta con pseudovariables.
+     *                                Route with pseudovariables.
      * @param callable|null $callback
-     *                                Callback que será llamado cuando la ruta configurada en $path coincida.
+     *                                Callback that will be called when the route configured in $path matches.
      *
      * @return static
-     *                Devuelve la instancia actual.
+     *                Returns the current instance.
      */
     public static function post(string $path, ?callable $callback = null): static
     {
@@ -241,15 +344,15 @@ class Router
     }
 
     /**
-     * Define los routers para el método PUT.
+     * Defines routers for the PUT method.
      *
      * @param string        $path
-     *                                Ruta con pseudovariables.
+     *                                Route with pseudovariables.
      * @param callable|null $callback
-     *                                Callback que será llamado cuando la ruta configurada en $path coincida.
+     *                                Callback that will be called when the route configured in $path matches.
      *
      * @return static
-     *                Devuelve la instancia actual
+     *                Returns the current instance
      */
 
     public static function put(string $path, ?callable $callback = null): static
@@ -258,15 +361,15 @@ class Router
     }
 
     /**
-     * Define los routers para el método PATCH.
+     * Defines routers for the PATCH method.
      *
      * @param string        $path
-     *                                Ruta con pseudovariables.
+     *                                Route with pseudovariables.
      * @param callable|null $callback
-     *                                Callback que será llamado cuando la ruta configurada en $path coincida.
+     *                                Callback that will be called when the route configured in $path matches.
      *
      * @return static
-     *                Devuelve la instancia actual
+     *                Returns the current instance
      */
     public static function patch(string $path, ?callable $callback = null): static
     {
@@ -274,15 +377,15 @@ class Router
     }
 
     /**
-     * Define los routers para el método DELETE.
+     * Defines routers for the DELETE method.
      *
      * @param string        $path
-     *                                Ruta con pseudovariables
+     *                                Route with pseudovariables
      * @param callable|null $callback
-     *                                Callback que será llamado cuando la ruta configurada en $path coincida.
+     *                                Callback that will be called when the route configured in $path matches.
      *
      * @return static
-     *                Devuelve la instancia actual
+     *                Returns the current instance
      */
     public static function delete(string $path, ?callable $callback = null): static
     {
@@ -290,7 +393,7 @@ class Router
     }
 
     /**
-     * Devuelve la ruta actual tomando como raíz la ruta de instalación de DuckBrain.
+     * Returns the current path, taking the DuckBrain installation path as the root.
      *
      * @return string
      */
@@ -305,51 +408,62 @@ class Router
     }
 
     /**
-     * Aplica la configuración de rutas.
+     * Applies the route configuration.
      *
-     * @param string|null $path (opcional) Ruta a usar. Si no se define, detecta la ruta actual.
+     * This method is the framework's error boundary: any \Throwable thrown
+     * while running the matched route's callback chain, while printing the
+     * returned data, or while resolving the not-found callback is caught
+     * here and rendered through $exceptionCallback. A failing handler is
+     * deliberately left uncaught (double failure falls back to PHP itself).
+     *
+     * @param string|null $path (optional) Path to use. If not defined, it detects the current path.
      *
      * @return void
      */
     public static function apply(?string $path = null): void
     {
-        $path    = $path ?? static::currentPath();
-        $routers = match ($_SERVER['REQUEST_METHOD']) { // Según el método selecciona un arreglo de routers
-            'POST'   => static::$post,
-            'PUT'    => static::$put,
-            'PATCH'  => static::$patch,
-            'DELETE' => static::$delete,
-            default  => static::$get
-        };
+        try {
+            $path    = $path ?? static::currentPath();
+            $routers = match ($_SERVER['REQUEST_METHOD']) { // Selects an array of routers based on the method
+                'POST'   => static::$post,
+                'PUT'    => static::$put,
+                'PATCH'  => static::$patch,
+                'DELETE' => static::$delete,
+                default  => static::$get
+            };
 
-        foreach ($routers as $router) { // revisa todos los routers para ver si coinciden con la ruta actual
-            if (preg_match_all('/^' . $router['path'] . '\/?$/si', $path, $matches, PREG_PATTERN_ORDER)) {
-                unset($matches[0]);
+            foreach ($routers as $router) { // Checks all routers to see if they match the current path
+                if (preg_match_all('/^' . $router['path'] . '\/?$/si', $path, $matches, PREG_PATTERN_ORDER)) {
+                    unset($matches[0]);
 
-                // Comprobando y guardando los parámetros variables de la ruta
-                if (isset($matches[1])) {
-                    foreach ($matches as $index => $match) {
-                        $paramName = $router['paramNames'][$index - 1];
-                        static::$currentParams[$paramName] = urldecode($match[0]);
+                    // Checking and storing the variable parameters of the route
+                    if (isset($matches[1])) {
+                        static::$params = new Neuron();
+                        foreach ($matches as $index => $match) {
+                            $paramName = $router['paramNames'][$index - 1];
+                            static::$params->{$paramName} = urldecode($match[0]);
+                        }
                     }
-                }
 
-                // Procesa la cola de callbacks
-                foreach (array_reverse($router['callback']) as $callback) {
-                    $data = Synapsis::resolve($callback);
-                }
+                    // Processes the callback queue
+                    foreach (array_reverse($router['callback']) as $callback) {
+                        $data = Synapsis::resolve($callback);
+                    }
 
-                // Por defecto imprime como JSON si se retorna algo
-                if (isset($data)) {
-                    header('Content-Type: application/json');
-                    print(json_encode($data));
-                }
+                    // By default, prints as JSON if something is returned
+                    if (isset($data)) {
+                        header('Content-Type: application/json');
+                        print(json_encode($data));
+                    }
 
-                return;
+                    return;
+                }
             }
-        }
 
-        // Si no hay router que coincida llamamos a $notFoundCallBack
-        Synapsis::resolve(static::$notFoundCallback);
+            // If no router matches, call $notFoundCallBack
+            Synapsis::resolve(static::$notFoundCallback);
+        } catch (\Throwable $exception) {
+            Synapsis::resolve(static::$exceptionCallback, ['exception' => $exception]);
+        }
     }
 }

src/Libs/Synapsis.php

@@ -12,11 +12,11 @@ use ReflectionParameter;
 /**
  * Synapsis - DuckBrain
  *
- * Clase encargada de la resolución e inyección de dependencias
+ * Class responsible for dependency resolution and injection.
  *
  * @author KJ
  * @website https://kj2.me
- * @licence MIT
+ * @license MIT
  */
 class Synapsis
 {
@@ -30,12 +30,13 @@ class Synapsis
     private static array $instances = [];
 
     /**
-     * Asocia una interface a una clase para instanciarla en su lugar.
+     * Binds an interface to a class to instantiate it instead.
      *
      * @param class-string $interfaceName
      * @param class-string $className
      *
      * @return void
+     * @throws Exception If the interface or class does not exist.
      */
     public static function bind(string $interfaceName, string $className): void
     {
@@ -48,7 +49,7 @@ class Synapsis
     }
 
     /**
-     * Asocia en lote múltiples interfaces con múltiples clases.
+     * Binds multiple interfaces to multiple classes in bulk.
      *
      * @param array<class-string, class-string> $bindings
      *
@@ -62,22 +63,25 @@ class Synapsis
     }
 
     /**
-     * Resuelve e inyecta las dependencias de un callable y devuelve su resultado.
+     * Resolves and injects dependencies for a callable and returns its result.
      *
-     * @param callable $action
+     * @param callable             $action
+     * @param array<string, mixed> $named  Associative array of values injected into the callable's
+     *                                     parameters by exact name match. Consumed in resolveParameterValues().
      *
      * @return mixed
+     * @throws Exception If an unhandled callable type is provided.
      */
-    public static function resolve(callable $action): mixed
+    public static function resolve(callable $action, array $named = []): mixed
     {
-        if ($action instanceof Closure) { // si es función anónima
+        if ($action instanceof Closure) { // If it's an anonymous function
             $reflectionCallback = new ReflectionFunction($action);
-        } else { // Areglo o string con el método
+        } else { // Array or string with the method
             if (is_string($action)) {
                 $action = preg_split('/::/', $action);
             }
 
-            // Revisamos su es un método o solo una función
+            // Check if it's a method or just a function
             if (count($action) == 2) {
                 $reflectionCallback = new ReflectionMethod($action[0], $action[1]);
             } else {
@@ -85,19 +89,20 @@ class Synapsis
             }
         }
 
-        // Obtenemos los parámetros
+        // Get the parameters
         return call_user_func_array(
             $action,
-            static::resolveParameterValues($reflectionCallback->getParameters())
+            static::resolveParameterValues($reflectionCallback->getParameters(), $named)
         );
     }
 
     /**
-     * Resuelve e inyecta las dependencias de una clase y devuelve su resultado.
+     * Resolves and injects dependencies for a class and returns its result.
      *
      * @param class-string $className
      *
      * @return mixed
+     * @throws Exception If a binding is missing for an interface or the class does not exist.
      */
     public static function &resolveInstance(string $className): mixed
     {
@@ -114,11 +119,11 @@ class Synapsis
         }
 
         if (!isset(static::$instances[$className])) {
-            // Si la instancia no ha sido resuelta antes, la devolvemos
+            // If the instance has not been resolved before, resolve it
             $reflectionClass = new ReflectionClass($className);
             $constructor = $reflectionClass->getConstructor();
             static::$instances[$className] = new $className(
-                ...static::resolveParameterValues($constructor->getParameters())
+                ...static::resolveParameterValues($constructor?->getParameters() ?? [])
             );
         }
 
@@ -126,28 +131,48 @@ class Synapsis
     }
 
     /**
-     * resolveParameterValues
+     * Resolves parameter values by injecting dependencies.
      *
      * @param array<ReflectionParameter> $parameters
+     * @param array<string, mixed> $named
+     *                                   Values injected into parameters whose name matches the key,
+     *                                   taking precedence over optional defaults and DI resolution.
+     *                                   Keys matching no parameter are ignored.
      *
-     * @return array
+     * @return array<mixed>
+     * @throws Exception    If a primitive parameter does not have a default value.
      */
-    public static function resolveParameterValues(array $parameters): array
+    public static function resolveParameterValues(array $parameters, array $named = []): array
     {
         $values = [];
         foreach ($parameters as $parameter) {
-            if ($parameter->isOptional()) { // Siempre usamos el valor por defecto primero
+            if ($parameter->isVariadic()) { // Skip variatic parameters
+                continue;
+            }
+
+            if (array_key_exists($parameter->getName(), $named)) { // Named values win over defaults and DI
+                $values[] = $named[$parameter->getName()];
+                continue;
+            }
+
+            if ($parameter->isOptional()) { // Always use the default value first
                 $values[] = $parameter->getDefaultValue();
                 continue;
             }
 
-            // Intentamos darle un valor equivalente a nulo si es una clase primitiva pare evitar
-            // errores innecesarios, lo
-            if ($parameter->getType()->isBuiltin()) {
-                throw new Exception('Primitive parameters expect at least a default value.');
+            $paramType = $parameter->getType();
+            if ($paramType === null) {
+                // If no type is declared, and it's not optional, we cannot resolve it.
+                throw new Exception(
+                    "Untyped parameter '{$parameter}' expect at least a default value or must be optional."
+                );
             }
 
-            $values[] = static::resolveInstance($parameter->getType()->getName());
+            if ($paramType->isBuiltin()) {
+                throw new Exception("Primitive parameter '{$parameter->getName()}' expects at least a default value.");
+            }
+
+            $values[] = static::resolveInstance($paramType->getName());
         }
         return $values;
     }

src/Libs/View.php

@@ -5,20 +5,20 @@ namespace Libs;
 /**
  * View - DuckBrain
  *
- * Manejador de vistas simplificado.
+ * Simplified view handler.
  *
  * @author KJ
  * @website https://kj2.me
- * @licence MIT
+ * @license MIT
  */
 class View extends Neuron
 {
     /**
-     * Incluye el archivo.
+     * Includes the file.
      *
-     * @param string      $viewName  Ruta relativa y el nommbre sin extensión del archivo.
-     * @param string|null $viewPath  (opcional) Ruta donde se encuentra la vista.
-     * @param string      $extension (opcional) Extensión del archivo.
+     * @param string      $viewName  Relative path and filename without extension.
+     * @param string|null $viewPath  (Optional) Path where the view file is located.
+     * @param string      $extension (Optional) File extension.
      *
      * @return void
      */
@@ -39,14 +39,14 @@ class View extends Neuron
     }
 
     /**
-     * Función que "renderiza" las vistas
+     * Function that "renders" views.
      *
-     * @param string       $viewName  Ruta relativa y el nommbre sin extensión del archivo.
-     * @param array|Neuron $params    (opcional) Arreglo que podrá ser usado en la vista
-     *                                mediante $view ($param['index'] se usaría así: $view->index)
-     * @param string|null  $viewPath  (opcional) Ruta donde se encuentra la vista. En caso de que
-     *                                la vista no se encuentre en esa ruta, se usará la ruta por defecto "src/Views/".
-     * @param string       $extension (opcional) Extensión del archivo.
+     * @param string       $viewName  Relative path and filename without extension.
+     * @param array|Neuron $params    (Optional) Array that can be used in the view
+     *                                via $view ($param['index'] would be used as: $view->index).
+     * @param string|null  $viewPath  (Optional) Path where the view is located. If the
+     *                                view is not found in this path, the default path "src/Views/" will be used.
+     * @param string       $extension (Optional) File extension.
      *
      * @return void
      */
@@ -61,12 +61,12 @@ class View extends Neuron
     }
 
     /**
-     * Renderiza las vistas HTML
+     * Renders HTML views.
      *
-     * @param string      $viewName  Ruta relativa y el nommbre sin extensión del archivo ubicado en src/Views
-     * @param string|null $viewPath  (opcional) Ruta donde se encuentra la vista. En caso de que la vista no se
-     *                               encuentre en esa ruta, se usará la ruta por defecto "src/Views/".
-     * @param string      $extension (opcional) Extensión del archivo.
+     * @param string      $viewName  Relative path and filename without extension located in src/Views.
+     * @param string|null $viewPath  (Optional) Path where the view is located. If the view is not
+     *                               found in this path, the default path "src/Views/" will be used.
+     * @param string      $extension (Optional) File extension.
      *
      * @return void
      */
@@ -83,12 +83,12 @@ class View extends Neuron
     }
 
     /**
-     * Renderiza código CSS.
+     * Renders CSS code.
      *
-     * @param string      $viewName  Ruta relativa y el nommbre sin extensión del archivo ubicado en src/Views
-     * @param string|null $viewPath  (opcional) Ruta donde se encuentra la vista. En caso de que la vista no se
-     *                               encuentre en esa ruta, se usará la ruta por defecto "src/Views/".
-     * @param string      $extension (opcional) Extensión del archivo.
+     * @param string      $viewName  Relative path and filename without extension located in src/Views.
+     * @param string|null $viewPath  (Optional) Path where the view is located. If the view is not
+     *                               found in this path, the default path "src/Views/" will be used.
+     * @param string      $extension (Optional) File extension.
      *
      * @return void
      */
@@ -102,12 +102,12 @@ class View extends Neuron
     }
 
     /**
-     * Renderiza código Javascript.
+     * Renders Javascript code.
      *
-     * @param string      $viewName  Ruta relativa y el nommbre sin extensión del archivo ubicado en src/Views
-     * @param string|null $viewPath  (opcional) Ruta donde se encuentra la vista. En caso de que la vista no se
-     *                               encuentre en esa ruta, se usará la ruta por defecto "src/Views/".
-     * @param string      $extension (opcional) Extensión del archivo.
+     * @param string      $viewName  Relative path and filename without extension located in src/Views.
+     * @param string|null $viewPath  (Optional) Path where the view is located. If the view is not
+     *                               found in this path, the default path "src/Views/" will be used.
+     * @param string      $extension (Optional) File extension.
      *
      * @return void
      */
@@ -121,9 +121,9 @@ class View extends Neuron
     }
 
     /**
-     * Imprime los datos en Json.
+     * Prints data as JSON.
      *
-     * @param object|array $data Objeto o array que se imprimirá a JSON.
+     * @param object|array $data Object or array to be printed as JSON.
      *
      * @return void
      */
@@ -134,9 +134,9 @@ class View extends Neuron
     }
 
     /**
-     * Imprime los datos en texto plano
+     * Prints data as plain text.
      *
-     * @param string $txt Contenido de texto.
+     * @param string $txt Text content.
      *
      * @return void
      */
@@ -147,7 +147,7 @@ class View extends Neuron
     }
 
     /**
-     * Intenta devolver la url absoluta a partir de una ruta relativa.
+     * Attempts to return the absolute URL from a relative path.
      *
      * @param string $path
      *