kj/duckbrain
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

docs: Improve documentation and translate comments to English

Browse Source
This commit is contained in:
kj
2025-10-10 21:18:22 -03:00
parent 674c9d5ff4
commit 7f62e06ff9
8 changed files with 369 additions and 307 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
src/Libs/Database.php
View File

@@ -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',

274
src/Libs/Model.php
View File

@@ -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<static>
* 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<static>
* 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
*/

27
src/Libs/Neuron.php
View File

@@ -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
{

28
src/Libs/Request.php
View File

@@ -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
*

143
src/Libs/Router.php
View File

@@ -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 '<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>';
}
/**
@@ -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);
}
}

32
src/Libs/Synapsis.php
View File

@@ -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,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<ReflectionParameter> $parameters
*
* @return array
* @return array<mixed>
* @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;
}

96
src/Libs/Validator.php
View File

@@ -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
*/

66
src/Libs/View.php
View File

@@ -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
*