diff --git a/src/Libs/Database.php b/src/Libs/Database.php index a5f467a..74048a7 100644 --- a/src/Libs/Database.php +++ b/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', diff --git a/src/Libs/Model.php b/src/Libs/Model.php index f31d0f6..f0918ef 100644 --- a/src/Libs/Model.php +++ b/src/Libs/Model.php @@ -12,23 +12,50 @@ use ReflectionProperty; /** * Model - DuckBrain * - * Modelo ORM para objetos que hagan uso de una base de datos. - * Depende de Libs\Database y hace uso de las constantes - * DB_TYPE, DB_HOST, DB_NAME, DB_USER y DB_PASS. + * ORM Model for database-backed objects. + * Depends on Libs\Database and uses constants + * DB_TYPE, DB_HOST, DB_NAME, DB_USER, and DB_PASS. * * @author KJ * @website https://kj2.me - * @licence MIT + * @license MIT */ #[AllowDynamicProperties] class Model { + /** + * @var array Attributes that should be set to NULL on update. + */ protected array $toNull = []; + + /** + * @var string The name of the primary key column. + */ protected static string $primaryKey = 'id'; + + /** + * @var array Attributes to ignore when saving to the database. + */ protected static array $ignoreSave = ['id']; + + /** + * @var array Attributes that should be explicitly saved, even if private/protected. + */ protected static array $forceSave = []; + + /** + * @var string The database table name. + */ protected static string $table; + + /** + * @var array Variables for PDO prepared statements. + */ protected static array $queryVars = []; + + /** + * @var array Current SELECT query components. + */ protected static array $querySelect = [ 'select' => ['*'], 'where' => '', @@ -42,7 +69,7 @@ class Model ]; /** - * Sirve para obtener la instancia de la base de datos. + * Retrieves the database instance. * * @return PDO */ @@ -65,8 +92,8 @@ class Model } /** - * Ejecuta PDO::beginTransaction para iniciar una transacción. - * Más info: https://www.php.net/manual/es/pdo.begintransaction.php + * Executes PDO::beginTransaction to start a transaction. + * More info: https://www.php.net/manual/es/pdo.begintransaction.php (Spanish, will keep for context) * * @return bool */ @@ -76,8 +103,8 @@ class Model } /** - * Ejecuta PDO::rollBack para deshacher los cambios de una transacción. - * Más info: https://www.php.net/manual/es/pdo.rollback.php + * Executes PDO::rollBack to undo changes in a transaction. + * More info: https://www.php.net/manual/es/pdo.rollback.php (Spanish, will keep for context) * * @return bool */ @@ -91,8 +118,8 @@ class Model } /** - * Ejecuta PDO::commit para consignar una transacción. - * Más info: https://www.php.net/manual/es/pdo.commit.php + * Executes PDO::commit to commit a transaction. + * More info: https://www.php.net/manual/es/pdo.commit.php (Spanish, will keep for context) * * @return bool */ @@ -106,21 +133,21 @@ class Model } /** - * Ejecuta una sentencia SQL en la base de datos. + * Executes an SQL statement in the database. * * @param string $query - * Contiene la sentencia SQL que se desea ejecutar. + * Contains the SQL statement to be executed. * * @throws Exception - * En caso de que la sentencia SQL falle, devolverá un error en - * pantalla y hará rolllback en caso de estar dentro de una - * transacción (ver método beginTransacction). + * If the SQL statement fails, it will throw an error + * and perform a rollback if currently within a transaction + * (see beginTransaction method). * * @param bool $resetQuery - * Indica si el query debe reiniciarse o no (por defecto es true). + * Indicates whether the query should be reset (defaults to true). * * @return array - * Contiene el resultado de la llamada SQL . + * Contains the result of the SQL call. */ protected static function query(string $query, bool $resetQuery = true): array { @@ -154,7 +181,7 @@ class Model } /** - * Reinicia la configuración de la sentencia SQL. + * Resets the SQL query configuration. * @return void */ protected static function resetQuery(): void @@ -174,11 +201,11 @@ class Model } /** - * Construye la sentencia SQL a partir static::$querySelect y una vez - * construída, llama a resetQuery. + * Builds the SQL statement from static::$querySelect and, once + * built, calls resetQuery. * * @return string - * Contiene la sentencia SQL. + * Contains the SQL statement. */ protected static function buildQuery(): string { @@ -223,14 +250,14 @@ class Model /** - * Configura $queryVars para vincular un valor a un - * parámetro de sustitución y devuelve este último. + * Configures $queryVars to bind a value to a + * substitution parameter and returns the latter. * * @param string $value - * Valor a vincular. + * Value to bind. * * @return string - * Parámetro de sustitución. + * Substitution parameter. */ private static function bindValue(string $value): string { @@ -240,14 +267,14 @@ class Model } /** - * Crea una instancia del objeto actual a partir de un arreglo. + * Creates an instance of the current object from an array. * * @param mixed $elem - * Puede recibir un arreglo o un objeto que contiene los valores - * que tendrán sus atributos. + * Can receive an array or an object containing the values + * that its attributes will have. * * @return static - * Retorna un objeto de la clase actual. + * Returns an object of the current class. */ protected static function getInstance(array $elem = []): static { @@ -276,13 +303,12 @@ class Model } /** - * Devuelve los atributos a guardar de la case actual. - * Los atributos serán aquellos que seran public y - * no esten excluidos en static::$ignoresave y aquellos - * que sean private o protected pero estén en static::$forceSave. + * Returns the attributes to be saved for the current class. + * Attributes will be those that are public and not excluded in static::$ignoreSave, + * and those that are private or protected but are in static::$forceSave. * * @return array - * Contiene los atributos indexados del objeto actual. + * Contains the indexed attributes of the current object. */ protected function getVars(): array { @@ -316,7 +342,7 @@ class Model } /** - * Devuelve el nombre de la clase actual aunque sea una clase extendida. + * Returns the name of the current class, even if it's an extended class. * * @return string * @@ -330,9 +356,9 @@ class Model } /** - * Construye (a partir del nombre de la clase y el sufijo en static::$tableSufix) - * y/o develve el nombre de la tabla de la BD en la que se alojará o - * se aloja el objeto actual. + * Constructs (from the class name and the suffix in static::$tableSufix) + * and/or returns the name of the DB table where the current object will be + * or is stored. * * @return string */ @@ -346,7 +372,7 @@ class Model } /** - * Convierte de lowerCamelCase a snake_case + * Converts from lowerCamelCase to snake_case. * * @param string $string * @@ -364,7 +390,7 @@ class Model } /** - * Convierte de snake_case a lowerCamelCase + * Converts from snake_case to lowerCamelCase. * * @param string $string * @@ -378,7 +404,7 @@ class Model } /** - * Actualiza los valores en la BD con los valores del objeto actual. + * Updates the values in the database with the current object's values. * @return void */ protected function update(): void @@ -408,14 +434,16 @@ class Model } /** - * Inserta una nueva fila en la base de datos a partir del - * objeto actual. + * Inserts a new row into the database from the + * current object. * @return void */ protected function add(): void { $db = static::db(); $atts = $this->getVars(); + $into = []; + $values = []; foreach ($atts as $key => $value) { if (isset($value)) { @@ -434,8 +462,8 @@ class Model } /** - * Revisa si el objeto a guardar es nuevo o no y según el resultado - * llama a update para actualizar o add para insertar una nueva fila. + * Checks if the object to be saved is new or not, and based on the result, + * calls `update` to update an existing row or `add` to insert a new row. * @return void */ public function save(): void @@ -449,7 +477,7 @@ class Model } /** - * Elimina el objeto actual de la base de datos. + * Deletes the current object from the database. * @return void */ public function delete(): void @@ -463,10 +491,10 @@ class Model } /** - * Define SELECT en la sentencia SQL. + * Defines SELECT in the SQL statement. * * @param array $columns - * Columnas que se selecionarán en la consulta SQL. + * Columns to be selected in the SQL query. * * @return static */ @@ -478,10 +506,10 @@ class Model } /** - * Define FROM en la sentencia SQL. + * Defines FROM in the SQL statement. * * @param array $tables - * Tablas que se selecionarán en la consulta SQL. + * Tables to be selected in the SQL query. * * @return static */ @@ -493,20 +521,20 @@ class Model } /** - * Define el WHERE en la sentencia SQL. + * Defines the WHERE clause in the SQL statement. * * @param string $column - * La columna a comparar. + * The column to compare. * * @param string $operatorOrValue - * El operador o el valor a comparar como igual en caso de que $value no se defina. + * The operator or the value to compare as equal if $value is not defined. * * @param string|null $value - * (opcional) El valor a comparar en la columna. + * (Optional) The value to compare against the column. * * @param bool $no_filter - * (opcional) Se usa cuando $value es una columna o un valor que no requiere filtros - * contra ataques SQLI (por defeco es false). + * (Optional) Used when $value is a column or a value that does not require + * filtering against SQL injection attacks (defaults to false). * * @return static */ @@ -525,20 +553,20 @@ class Model } /** - * Define AND en la sentencia SQL (se puede anidar). + * Defines AND in the SQL statement (can be nested). * * @param string $column - * La columna a comparar. + * The column to compare. * * @param string $operatorOrValue - * El operador o el valor a comparar como igual en caso de que $value no se defina. + * The operator or the value to compare as equal if $value is not defined. * * @param string|null $value - * (opcional) El valor el valor a comparar en la columna. + * (Optional) The value to compare against the column. * * @param bool $no_filter - * (opcional) Se usa cuando $value es una columna o un valor que no requiere filtros - * contra ataques SQLI (por defecto es false). + * (Optional) Used when $value is a column or a value that does not require + * filtering against SQL injection attacks (defaults to false). * * @return static */ @@ -567,20 +595,20 @@ class Model } /** - * Define OR en la sentencia SQL (se puede anidar). + * Defines OR in the SQL statement (can be nested). * * @param string $column - * La columna a comparar. + * The column to compare. * * @param string $operatorOrValue - * El operador o el valor a comparar como igual en caso de que $value no se defina. + * The operator or the value to compare as equal if $value is not defined. * * @param string|null $value - * (opcional) El valor el valor a comparar en la columna. + * (Optional) The value to compare against the column. * * @param bool $no_filter - * (opcional) Se usa cuando $value es una columna o un valor que no requiere filtros - * contra ataques SQLI (por defecto es false). + * (Optional) Used when $value is a column or a value that does not require + * filtering against SQL injection attacks (defaults to false). * * @return static */ @@ -609,16 +637,16 @@ class Model } /** - * Define WHERE usando IN en la sentencia SQL. + * Defines WHERE using IN in the SQL statement. * * @param string $column - * La columna a comparar. + * The column to compare. * * @param array $arr - * Arreglo con todos los valores a comparar con la columna. + * Array with all values to compare against the column. * * @param bool $in - * Define si se tienen que comprobar negativa o positivamente. + * Defines whether to check positively (IN) or negatively (NOT IN). * * @return static */ @@ -648,20 +676,20 @@ class Model } /** - * Define LEFT JOIN en la sentencia SQL. + * Defines LEFT JOIN in the SQL statement. * * @param string $table - * Tabla que se va a juntar a la del objeto actual. + * Table to join with the current object's table. * * @param string $columnA - * Columna a comparar para hacer el join. + * Column to compare for the join. * * @param string $operatorOrColumnB - * Operador o columna a comparar como igual para hacer - * el join en caso de que $columnB no se defina. + * Operator or column to compare as equal for the join + * if $columnB is not defined. * * @param string|null $columnB - * (opcional) Columna a comparar para hacer el join. + * (Optional) Column to compare for the join. * * @return static */ @@ -682,20 +710,20 @@ class Model } /** - * Define RIGHT JOIN en la sentencia SQL. + * Defines RIGHT JOIN in the SQL statement. * * @param string $table - * Tabla que se va a juntar a la del objeto actual. + * Table to join with the current object's table. * * @param string $columnA - * Columna a comparar para hacer el join. + * Column to compare for the join. * * @param string $operatorOrColumnB - * Operador o columna a comparar como igual para hacer - * el join en caso de que $columnB no se defina. + * Operator or column to compare as equal for the join + * if $columnB is not defined. * * @param string|null $columnB - * (opcional) Columna a comparar para hacer el join. + * (Optional) Column to compare for the join. * * @return static */ @@ -716,20 +744,20 @@ class Model } /** - * Define INNER JOIN en la sentencia SQL. + * Defines INNER JOIN in the SQL statement. * * @param string $table - * Tabla que se va a juntar a la del objeto actual. + * Table to join with the current object's table. * * @param string $columnA - * Columna a comparar para hacer el join. + * Column to compare for the join. * * @param string $operatorOrColumnB - * Operador o columna a comparar como igual para hacer - * el join en caso de que $columnB no se defina. + * Operator or column to compare as equal for the join + * if $columnB is not defined. * * @param string|null $columnB - * (opcional) Columna a comparar para hacer el join. + * (Optional) Column to compare for the join. * * @return static */ @@ -750,10 +778,10 @@ class Model } /** - * Define GROUP BY en la sentencia SQL. + * Defines GROUP BY in the SQL statement. * * @param array $arr - * Columnas por las que se agrupará. + * Columns to group by. * * @return static */ @@ -764,13 +792,13 @@ class Model } /** - * Define LIMIT en la sentencia SQL. + * Defines LIMIT in the SQL statement. * * @param int $offsetOrQuantity - * Define el las filas a ignorar o la cantidad a tomar en - * caso de que $quantity no esté definido. - * @param int $quantity - * Define la cantidad máxima de filas a tomar. + * Defines the rows to skip or the quantity to take + * if $quantity is not defined. + * @param int|null $quantity + * (Optional) Defines the maximum number of rows to take. * * @return static */ @@ -786,14 +814,14 @@ class Model } /** - * Define ORDER BY en la sentencia SQL. + * Defines ORDER BY in the SQL statement. * * @param string $value - * Columna por la que se ordenará. + * Column to order by. * * @param string $order - * (opcional) Define si el orden será de manera ascendente (ASC), - * descendente (DESC) o aleatorio (RAND). + * (Optional) Defines whether the order will be ascending (ASC), + * descending (DESC), or random (RAND). * * @return static */ @@ -814,14 +842,14 @@ class Model } /** - * Retorna la cantidad de filas que hay en un query. + * Returns the number of rows in a query. * * @param bool $resetQuery - * (opcional) Indica si el query debe reiniciarse o no (por defecto es true). + * (Optional) Indicates whether the query should be reset (defaults to true). * * @param bool $useLimit - * (opcional) Permite usar limit para estabecer un máximo inical y final para contar. - * Requiere que se haya definido antes el límite (por defecto en false). + * (Optional) Allows using limit to establish an initial and final maximum for counting. + * Requires the limit to have been defined beforehand (defaults to false). * * @return int */ @@ -860,12 +888,12 @@ class Model static::$querySelect['orderBy'] = $backup['orderBy']; } - return $result; + return (int)$result; } /** - * Obtiene una instancia según su primary key (generalmente id). - * Si no encuentra una instancia, devuelve nulo. + * Retrieves an instance by its primary key (usually 'id'). + * If no instance is found, returns null. * * @param mixed $id * @@ -877,13 +905,13 @@ class Model } /** - * Realiza una búsqueda en la tabla de la instancia actual. + * Performs a search in the current instance's table. * * @param string $search - * Contenido a buscar. + * Content to search for. * * @param array|null $in - * (opcional) Columnas en las que se va a buscar (null para buscar en todas). + * (Optional) Columns to search within (null to search all). * * @return static */ @@ -918,13 +946,13 @@ class Model } /** - * Obtener los resultados de la consulta SQL. + * Retrieves the results of the SQL query. * * @param bool $resetQuery - * (opcional) Indica si el query debe reiniciarse o no (por defecto es true). + * (Optional) Indicates whether the query should be reset (defaults to true). * * @return array - * Arreglo con instancias del la clase actual resultantes del query. + * Array with instances of the current class resulting from the query. */ public static function get(bool $resetQuery = true): array { @@ -941,13 +969,13 @@ class Model } /** - * El primer elemento de la consulta SQL. + * Retrieves the first element from the SQL query result. * * @param bool $resetQuery - * (opcional) Indica si el query debe reiniciarse o no (por defecto es true). + * (Optional) Indicates whether the query should be reset (defaults to true). * * @return static|null - * Puede retornar una instancia de la clase actual o null. + * Can return an instance of the current class or null. */ public static function getFirst(bool $resetQuery = true): ?static { @@ -957,10 +985,10 @@ class Model } /** - * Obtener todos los elementos del la tabla de la instancia actual. + * Retrieves all elements from the current instance's table. * * @return array - * Contiene un arreglo de instancias de la clase actual. + * Contains an array of instances of the current class. */ public static function all(): array { @@ -977,11 +1005,11 @@ class Model } /** - * Permite definir como nulo el valor de un atributo. - * Sólo funciona para actualizar un elemento de la BD, no para insertar. + * Allows defining an attribute's value as null. + * Only works for updating an element in the DB, not for inserting. * * @param array $attributes - * Atributo o arreglo de atributos que se definirán como nulos. + * Attribute or array of attributes that will be set to null. * * @return void */ diff --git a/src/Libs/Neuron.php b/src/Libs/Neuron.php index a45463e..97ff558 100644 --- a/src/Libs/Neuron.php +++ b/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,10 +44,13 @@ 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 { diff --git a/src/Libs/Request.php b/src/Libs/Request.php index aea343f..75fea8e 100644 --- a/src/Libs/Request.php +++ b/src/Libs/Request.php @@ -5,12 +5,12 @@ namespace Libs; /** * 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 { @@ -28,7 +28,7 @@ class Request extends Neuron /** * __construct * - * @param string $path Ruta actual tomando como raíz la instalación de DuckBrain. + * @param string $path Current path, taking the DuckBrain installation as root. */ public function __construct() { @@ -52,22 +52,22 @@ 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 + // Run configured validations if (!$this->validate()) { exit(); } } /** - * Inicia la validación que se haya configurado. + * Starts the configured validation. * * @return bool */ @@ -97,7 +97,7 @@ class Request extends Neuron } /** - * Reglas para el método actual. + * Rules for the current method. * * @return array */ @@ -107,7 +107,7 @@ class Request extends Neuron } /** - * Reglas para los parámetros por URL. + * Rules for URL parameters. * * @return array */ @@ -117,7 +117,7 @@ class Request extends Neuron } /** - * Reglas para los parámetros GET. + * Rules for GET parameters. * * @return array */ @@ -127,7 +127,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,7 +137,7 @@ class Request extends Neuron } /** - * Función a ejecutar cuando se ha detectado un valor no válido. + * Function to execute when an invalid value has been detected. * * @param string $error * diff --git a/src/Libs/Router.php b/src/Libs/Router.php index 4b6aa2d..3793a6d 100644 --- a/src/Libs/Router.php +++ b/src/Libs/Router.php @@ -5,13 +5,13 @@ 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 { @@ -20,20 +20,36 @@ class Router private static $put = []; private static $patch = []; private static $delete = []; + /** + * Stores the method and index of the last configured route, e.g., ['get', 0]. + * Used for chaining methods like middleware() or reconfigure(). + * + * @var array|null + */ private static $last; + /** + * Stores the parameters extracted from the current matching route. + * + * @var array + */ public static $currentParams = []; + /** + * The callback function to be executed when no route matches. + * + * @var callable|string + */ public static $notFoundCallback = 'Libs\Router::defaultNotFound'; /** - * Función callback por defectio para cuando - * no se encuentra configurada la ruta. + * 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 '

Error 404 - Página no encontrada

'; + echo '

Error 404 - Page Not Found

'; } /** @@ -44,18 +60,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 +95,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,14 +111,14 @@ 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 @@ -111,14 +128,14 @@ class Router } /** - * 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 $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 +164,7 @@ class Router } /** - * Reconfigura el callback final de la última ruta. + * Reconfigures the final callback of the last route. * * @param callable $callback * @@ -168,20 +185,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 { @@ -209,15 +226,15 @@ class Router } /** - * 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 +242,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 +258,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 +275,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 +291,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 +307,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,16 +322,16 @@ 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. + * @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 + $routers = match ($_SERVER['REQUEST_METHOD']) { // Selects an array of routers based on the method 'POST' => static::$post, 'PUT' => static::$put, 'PATCH' => static::$patch, @@ -322,11 +339,11 @@ class Router default => static::$get }; - foreach ($routers as $router) { // revisa todos los routers para ver si coinciden con la ruta actual + 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 + // Checking and storing the variable parameters of the route if (isset($matches[1])) { foreach ($matches as $index => $match) { $paramName = $router['paramNames'][$index - 1]; @@ -334,12 +351,12 @@ class Router } } - // Procesa la cola de callbacks + // Processes the callback queue foreach (array_reverse($router['callback']) as $callback) { $data = Synapsis::resolve($callback); } - // Por defecto imprime como JSON si se retorna algo + // By default, prints as JSON if something is returned if (isset($data)) { header('Content-Type: application/json'); print(json_encode($data)); @@ -349,7 +366,7 @@ class Router } } - // Si no hay router que coincida llamamos a $notFoundCallBack + // If no router matches, call $notFoundCallBack Synapsis::resolve(static::$notFoundCallback); } } diff --git a/src/Libs/Synapsis.php b/src/Libs/Synapsis.php index 96035b2..9da591f 100644 --- a/src/Libs/Synapsis.php +++ b/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 $bindings * @@ -62,22 +63,23 @@ 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 * * @return mixed + * @throws Exception If an unhandled callable type is provided. */ public static function resolve(callable $action): 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,7 +87,7 @@ class Synapsis } } - // Obtenemos los parámetros + // Get the parameters return call_user_func_array( $action, static::resolveParameterValues($reflectionCallback->getParameters()) @@ -93,11 +95,12 @@ class Synapsis } /** - * 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,7 +117,7 @@ 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( @@ -126,17 +129,18 @@ class Synapsis } /** - * resolveParameterValues + * Resolves parameter values by injecting dependencies. * * @param array $parameters * - * @return array + * @return array + * @throws Exception If a primitive parameter does not have a default value. */ public static function resolveParameterValues(array $parameters): array { $values = []; foreach ($parameters as $parameter) { - if ($parameter->isOptional()) { // Siempre usamos el valor por defecto primero + if ($parameter->isOptional()) { // Always use the default value first $values[] = $parameter->getDefaultValue(); continue; } diff --git a/src/Libs/Validator.php b/src/Libs/Validator.php index 29f2d78..7551b3d 100644 --- a/src/Libs/Validator.php +++ b/src/Libs/Validator.php @@ -7,43 +7,48 @@ use Exception; /** * Validator - DuckBrain * - * Libería complementaria de la libería Request. - * Sirve para simplpificar la verificación de valores. + * Complementary library to the Request library. + * Simplifies value verification. * - * Tiene la posibilida de verificar tanto reglas individuales como en lote. + * It has the ability to verify both individual rules and in batches. * * |----------+--------------------------------------------------------| - * | Regla | Descripción | + * | Rule | Description | * |----------+--------------------------------------------------------| - * | not | Niega la siguiente regla. Ej: not:float | - * | exists | Es requerido; debe estar definido y puede estar vacío | - * | required | Es requerido; debe estar definido y no vacío | - * | number | Es numérico | - * | int | Es entero | - * | float | Es un float | - * | bool | Es booleano | - * | email | Es un correo | - * | enum | Esta en un lista ve valores. Ej: enum:admin,user,guest | - * | url | Es una url válida | + * | not | Negates the next rule. Ex: not:float | + * | exists | Is required; must be defined and can be empty | + * | required | Is required; must be defined and not empty | + * | number | Is numeric | + * | int | Is an integer | + * | float | Is a float | + * | bool | Is a boolean | + * | email | Is an email | + * | enum | Is in a list of values. Ex: enum:admin,user,guest | + * | url | Is a valid URL | * |----------+--------------------------------------------------------| * - * Las listas de reglas están separadas por |, Ej: required|email + * Rule lists are separated by |, e.g., required|email * * @author KJ * @website https://kj2.me - * @licence MIT + * @license MIT */ class Validator { + /** + * Stores the last failed rule. + * + * @var string + */ public static string $lastFailed = ''; /** - * Validar lista de reglas sobre las propiedades de un objeto. + * Validates a list of rules against the properties of an object. * - * @param array $rulesList Lista de reglas. - * @param Neuron $haystack Objeto al que se le verificarán las reglas. + * @param array $rulesList The list of rules. + * @param Neuron $haystack The object whose properties will be validated. * - * @return bool Retorna true solo si todas las reglas se cumplen y false en cuanto una falle. + * @return bool Returns true only if all rules are met, and false as soon as one fails. */ public static function validateList(array $rulesList, Neuron $haystack): bool { @@ -62,12 +67,13 @@ class Validator } /** - * Revisa si una regla se cumple. + * Checks if a rule is met. * - * @param mixed $subject Lo que se va a verfificar. - * @param string $rule La regla a probar. + * @param mixed $subject The value to verify. + * @param string $rule The rule to test. * * @return bool + * @throws Exception If the rule is not callable. */ public static function checkRule(mixed $subject, string $rule): bool { @@ -83,10 +89,10 @@ class Validator } /** - * Verifica la regla de manera negativa. + * Verifies the rule in a negative way. * - * @param mixed $subject Lo que se va a verfificar. - * @param mixed $rule La regla a probar. + * @param mixed $subject The value to verify. + * @param mixed $rule The rule to test. * * @return bool */ @@ -96,9 +102,9 @@ class Validator } /** - * Comprueba que que esté definido/exista. + * Checks if the value is defined/exists. * - * @param mixed $subject + * @param mixed $subject The value to check. * * @return bool */ @@ -108,9 +114,9 @@ class Validator } /** - * Comprueba que que esté definido y no esté vacío. + * Checks if the value is defined and not empty. * - * @param mixed $subject + * @param mixed $subject The value to check. * * @return bool */ @@ -120,9 +126,9 @@ class Validator } /** - * number + * Checks if the value is numeric. * - * @param mixed $subject + * @param mixed $subject The value to check. * * @return bool */ @@ -132,9 +138,9 @@ class Validator } /** - * int + * Checks if the value is an integer. * - * @param mixed $subject + * @param mixed $subject The value to check. * * @return bool */ @@ -144,9 +150,9 @@ class Validator } /** - * float + * Checks if the value is a float. * - * @param mixed $subject + * @param mixed $subject The value to check. * * @return bool */ @@ -156,9 +162,9 @@ class Validator } /** - * bool + * Checks if the value is a boolean. * - * @param mixed $subject + * @param mixed $subject The value to check. * * @return bool */ @@ -168,9 +174,9 @@ class Validator } /** - * email + * Checks if the value is a valid email address. * - * @param mixed $subject + * @param mixed $subject The value to check. * * @return bool */ @@ -180,9 +186,9 @@ class Validator } /** - * url + * Checks if the value is a valid URL. * - * @param mixed $subject + * @param mixed $subject The value to check. * * @return bool */ @@ -192,10 +198,10 @@ class Validator } /** - * enum + * Checks if the value is present in a list of allowed values. * - * @param mixed $subject - * @param mixed $values + * @param mixed $subject The value to check. + * @param mixed ...$values A variable number of allowed values. * * @return bool */ diff --git a/src/Libs/View.php b/src/Libs/View.php index 8ccaa81..366829c 100644 --- a/src/Libs/View.php +++ b/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 *