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()

autoload.php

@@ -12,8 +12,3 @@ spl_autoload_register(function ($className) {
         require_once $file;
     }
 });
-
-set_exception_handler(function ($exception) {
-    echo "Uncaught exception: " , $exception->getMessage(), "\n";
-    echo $exception->getTraceAsString();
-});

src/Libs/Model.php

@@ -176,6 +176,10 @@ class Model
 
             $vars = json_encode(static::$dbQueryVariables);
 
+            if ($resetQuery) {
+                static::resetQuery();
+            }
+
             throw new Exception(
                 "\nError at query to database.\n" .
                 "Query: $query\n" .
@@ -1008,7 +1012,9 @@ class Model
     public static function orderBy(string $value, string $order = 'ASC'): static
     {
         if ($value == "RAND") {
-            static::$dbQuery['orderBy'] = 'RAND()';
+            $random = static::db()->getAttribute(PDO::ATTR_DRIVER_NAME) == 'mysql' ? 'RAND()' : 'RANDOM()';
+            static::$dbQuery['orderBy'] = $random;
+
             return new static();
         }
 

src/Libs/Request.php

@@ -2,6 +2,8 @@
 
 namespace Libs;
 
+use Exception;
+
 /**
  * Request - DuckBrain
  *
@@ -59,17 +61,20 @@ class Request extends Neuron
         }
 
         // Run configured validations
-        if (!$this->validate()) {
-            exit();
-        }
+        $this->validate();
     }
 
     /**
      * 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'])},
@@ -88,7 +93,7 @@ class Request extends Neuron
             Validator::validateList(static::getRules(), $this->get) &&
             Validator::validateList(static::rules(), $body)
         ) {
-            return true;
+            return;
         }
 
         $error = Validator::message(
@@ -98,7 +103,6 @@ class Request extends Neuron
         );
 
         static::onInvalid($error);
-        return false;
     }
 
     /**
@@ -157,27 +161,20 @@ class Request extends Neuron
     /**
      * Function to execute when an invalid value has been detected.
      *
-     * Always answers with a single error and HTTP 422. The representation is
-     * negotiated from the request's Accept header: JSON when the client asks
-     * for application/json, plain text otherwise.
+     * 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);
-
-        $accept = $_SERVER['HTTP_ACCEPT'] ?? '';
-
-        if (str_contains($accept, 'application/json')) {
-            header('Content-Type: application/json');
-            print(json_encode(['error' => $error]));
-
-            return;
-        }
-
-        print($error);
+        throw new Exception($error, 422);
     }
 }

src/Libs/Router.php

@@ -50,7 +50,7 @@ class Router
      *
      * @var callable $notFoundCallback
      */
-    public static $notFoundCallback = 'Libs\Router::defaultNotFound';
+    public static $notFoundCallback =  'Libs\Router::defaultNotFound';
 
     /**
      * Default callback function for when
@@ -64,6 +64,54 @@ class Router
         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());
+    }
+
     /**
      * __construct
      */
@@ -136,7 +184,6 @@ class Router
     public static function redirect(string $path): void
     {
         header('Location: ' . static::basePath() . ltrim($path, '/'));
-        exit;
     }
 
     /**
@@ -363,50 +410,60 @@ class Router
     /**
      * Applies the route configuration.
      *
+     * 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']) { // Selects an array of routers based on the method
-            '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) { // 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]);
+            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]);
 
-                // 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]);
+                    // 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]);
+                        }
                     }
-                }
 
-                // Processes the callback queue
-                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);
+                    }
 
-                // By default, prints as JSON if something is returned
-                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;
+                }
             }
-        }
 
-        // If no router matches, call $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

@@ -65,12 +65,14 @@ class Synapsis
     /**
      * 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) { // If it's an anonymous function
             $reflectionCallback = new ReflectionFunction($action);
@@ -90,7 +92,7 @@ class Synapsis
         // Get the parameters
         return call_user_func_array(
             $action,
-            static::resolveParameterValues($reflectionCallback->getParameters())
+            static::resolveParameterValues($reflectionCallback->getParameters(), $named)
         );
     }
 
@@ -132,11 +134,15 @@ class Synapsis
      * 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<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) {
@@ -144,6 +150,11 @@ class Synapsis
                 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;

src/Libs/Validator.php

@@ -38,7 +38,7 @@ use Exception;
  * | url           |               | Must be a valid URL                         |
  * | date          |               | Must be a parseable date                    |
  * | regex         | :pattern      | Must match a PCRE pattern (with delimiters) |
- * | enum          | :a,b,c        | Must be one of the listed values            |
+ * | in            | :a,b,c        | Must be one of the listed values            |
  * | min           | :n            | Length/number/count min (files: KB)         |
  * | max           | :n            | Length/number/count max (files: KB)         |
  * | between       | :min,:max     | Value within range (files: KB per upload)   |
@@ -105,7 +105,7 @@ class Validator
      * | :size      | the size rule value                              |
      * | :value     | the required_if expected value                   |
      * | :other     | the required_if companion field / confirmation   |
-     * | :values    | a comma list (enum, mimes, required_with)        |
+     * | :values    | a comma list (in, mimes, required_with)          |
      * |----------+----------------------------------------------------|
      *
      * @var array<string,string>
@@ -122,7 +122,7 @@ class Validator
         'array'        => 'The :attribute must be an array.',
         'email'        => 'The :attribute must be a valid email address.',
         'url'          => 'The :attribute must be a valid URL.',
-        'enum'         => 'The selected :attribute is invalid. Allowed: :values.',
+        'in'           => 'The selected :attribute is invalid. Allowed: :values.',
         'min'          => 'The :attribute must be at least :min.',
         'max'          => 'The :attribute must not be greater than :max.',
         'between'      => 'The :attribute must be between :min and :max.',
@@ -243,7 +243,7 @@ class Validator
             case 'size':
                 $replace[':size'] = $args[0] ?? '';
                 break;
-            case 'enum':
+            case 'in':
             case 'mimes':
             case 'required_with':
                 $replace[':values'] = implode(', ', $args);
@@ -305,7 +305,7 @@ class Validator
      * arguments legitimately contain ':' or ',' - such as regex or mimes -
      * are preserved intact. The caller decides how to split the arguments.
      *
-     * @param string $rule The rule to parse. Ex: "regex:/^a,b$/" or "enum:a,b".
+     * @param string $rule The rule to parse. Ex: "regex:/^a,b$/" or "in:a,b".
      *
      * @return array A two element array: [name, rawArguments]. When the rule
      *               has no parameters, rawArguments is an empty string.
@@ -419,7 +419,7 @@ class Validator
      * Splits a rule's raw argument string into the arguments to pass to the
      * rule's method (the subject is not included).
      *
-     * Most rules take a comma-separated list of values (e.g. "enum:a,b").
+     * Most rules take a comma-separated list of values (e.g. "in:a,b").
      * A few rules receive an argument that must be kept intact because it can
      * legitimately contain commas or colons: "regex" (a pattern) and "not"
      * (a sub-rule that is itself parsed recursively). An empty argument string
@@ -810,7 +810,7 @@ class Validator
      *
      * @return bool
      */
-    public static function enum(mixed $subject, ...$values): bool
+    public static function in(mixed $subject, ...$values): bool
     {
         return in_array($subject, $values);
     }