Manual de JuncoCMS (Librerías)

Este es el manual de JuncoCMS para desarrolladores backend.

Tabla de contenidos

Introducción

JuncoCMS tiene su propio framework, el cual está escrito en PHP. Esta decisión de diseño no tiene un motivo en particular, sino que ha sido consecuencia de varios años de desarrollo.

Dicho esto, nuestro framework no pretende ser original, por el contrario, intenta ser familiar a muchos otros frameworks del ecosistema.

Uso de las PSR

Con la intención clara de tener un framework fluido, lo primero que debemos saber, es que se implementan muchas interfaces de las PSR (PHP Standards Recommendations), como ser:

• PSR-3 (Logger Interface)
• PSR-7 (HTTP Message Interface)
• PSR-11 (Container Interface)
• PSR-15 (HTTP Handlers)
• PSR-16 (Simple Cache)
• PSR-17 (HTTP Factories)
• PSR-18 (HTTP Client)

Composer y el autoload

El framework tiene su propio autoload para cargar sus librerías, y no requiere de composer para funcionar. Sin embargo, si se desea, es posible utilizar composer sin necesidad de configuración u otro cambio. El framework detectará el autoload de composer y lo incluirá automáticamente.

Otras librerías

El framework cuenta con muchas librerías.

En general, no difieren demasiado de las librerías de otros frameworks. Por ejemplo, podemos encontrar: Assets, Config, Database, Date, Email, Filesystem, Filter, entre otras.

Sin embargo, en algunas de ellas encontraremos modos únicos para la resolución de las tareas asignadas. Como se dijo al comienzo, esto no es por originalidad, sino por necesidades concretas.

No todo es genial

No es posible tener un framework propio sin acotar el número de prestaciones soportadas. Es por eso que pueden encontrar limitaciones. Por ejemplo, una limitación importante, es que soporta únicamente bases de datos mysql.

Sin embargo, en la medida que se llegue a profundizar en el conocimiento del framework, se podrá apreciar que cuenta con muchas de las necesidades mínimas y, sobre todo, cuenta con una estructura robusta, que facilita la inclusión de nuevas características.

El archivo Index

Cómo muchos frameworks, todas las consultas dinámicas al servidor, son procesadas por el archivo index.php.

Este archivo, se encargará de: incluir el autoload, inicializar el sistema, procesar la consulta y emitir la respuesta.

Incluir el autoload

El autoload permite, con el solo hecho de crear un objeto, incluir automáticamente la librería que lo define. Incluyendo el autoload, no debemos volver a incluir otra librería.

El autoload se incluye en dos pasos:

include 'bootstrap.php';
include SYSTEM_ABSPATH . SYSTEM_AUTOLOAD;

Primero, se incluye el archivo bootstrap.php. Este arhivo está a salvo de cualquier actualización, y contiene las rutas básicas y otras configuraciones mínimas. Luego, se incluye la librería autoload.

Inicializar el sistema

Muchas librerías se inicializan a través del contenedor (Container), por lo que resulta conveniente inicializarlo antes que nada.

$container = Container::getInstance();

Luego, se inicializarán dos librerías:

$container->get('system');
$container->get('debugger');

El sistema, incluye:

• las fachadas (facades), que son funciones que facilitan el acceso a las librerías más comunes.
• las constantes del sistema y del sistema de permisos.

También, setea algunas funciones de php, como ser el charset y el timezone.

El depurador, es necesario para registrar cualquier error del sistema y brindar una respuesta adecuada.

Nota: al inicializar el sistema, es posible intercalar el Perfilador.

Procesar la consulta

El sistema para procesar la consulta está basado en una implementación de las PSR.

Primero, con un objeto ServerRequest se representa la consulta. Esta consulta se pasa a un manejador de consultas RequestHandler, que a su vez, la pasará a través varios Middleware hasta que uno de ellos devuelva un objeto Response.

En nuestro framework, el objeto RequestHandler, encargado de ejecutar los middlewares, se llama Runner.

$request = (new ServerRequestFactory)->createServerRequest();
$handler = new Runner();
$handler->add('router');
$response = $handler->handle($request);

Algunos de los middlewares más importantes del framework son:

• RouterMiddleware: ejecuta el controlador.
• ProfilerMiddleware: renderiza el perfilador de código.
• AuthenticateMiddleware: verifica los permisos del usuario.

Emitir la respuesta

Una vez obtenida la respuesta, ésta debe ser emitida a la consola sapi. Para ello, se utiliza la clase SapiEmitter.

(new SapiEmitter)->emit($response);

El autoload

El autoload permite, con el sólo hecho de crear un objeto, incluir automáticamente la librería que lo define. En otras palabras, incluyendo el autoload, no debemos volver a incluir otra librería.

El framework tiene su propio autoload. Su ruta está definida por una constante, en el archivo bootstrap.php, lo que permite su reemplazo. Por último, su inclusión se realiza al comienzo del archivo index.php.

En concreto, el autoload tiene registradas varias funciones, cada una de ellas incluirá diferentes librerías: framework, framework (Heredado), PSR.

Incluir librerías del framework

El framework se incluirá utilizando un espacio de nombre que comienza con la palabra Junco. Así tenemos que:

new Junco\Assets\Compiller();

Incluirá la librería:

include "cms/libraries/assets/Compiler.php";

Incluir librerías del framework (Heredado)

Hay una función para incluir librerías sin el uso de espacios de nombre. En muchos casos, aún se mantiene porque resulta práctico.

Por ejemplo, si creamos el objeto:

new DatabaseImporter();

se incluirá la librería:

include "cms/libraries/database/DatabaseImporter.php";

Incluir las interfaces PSR

Esta función evita necesitar de composer para tener a disposición las interfaces PSR de la carpeta vendor.

Extensiones

Las librerías del framework se encuentran en la carpeta cms/libraries/, todas organizadas en carpetas con el nombre de la extensión a la que pertenecen.

La carpeta de librerías se ve similar a:

Archive

Librería para comprimir y extraer archivos.

Dependiendo de las extensiones instaladas en PHP, es posible gestionar las siguientes extensiones:

Crear una instancia Archive

Para comprimir y extraer archivos, es necesario crear una instancia Archive.

$archive = new Archive();

Opcionalmente, puede pasar como parámetro una cadena con la ruta base, de lo contrario, la ruta base será: SYSTEM_ABSPATH.

Extraer un archivo

Un archivo se extrae de la siguiente manera:

$archive->extract($zipfile, $dirpath, true);

zipfile

La ruta al archivo a extraer.

dirpath

La ruta a la carpeta donde se colocará lo extraído (opcional).

delete

Elimina el archivo extraido (opcional).

Tenga en cuenta la ruta base declarada al crear una instancia. Por ejemplo, si queremos descomprimir un archivo en la misma carpeta en la que se encuentra, podemos escribir:

$archive = new Archive('path/to/dir/');
$archive->extract('filename_to_extrac');

Comprimir archivos

Un archivo se comprime de la siguiente manera:

$archive->compress($zipfile, $dirpath, $nodes);

zipfile

La ruta al archivo comprimido a crear.

dirpath

La ruta a la carpeta que se usará como base desde donde se comenzará a comprimir. Esta carpeta no será incluída en el archivo comprimido.

nodes

Un arreglo con los nodos a incluir. Si no se completa, se incluirá todo.

Extensiones aceptadas

Para conocer, en tiempo de ejecución, las extensiones aceptadas, están los métodos:

$archive->acceptsToExtract();
$archive->acceptsToCompress();

Assets

La extensión permite gestionar los archivos css y javascript, que, en adelante, llamaremos activos.

Básicamente, se encarga de:

• Crear un único archivo "asset", que agrupa varios activos.
• Comprimir los archivos asset para el entorno de producción.
• Desagrupar los archivos asset para el entorno de desarrollo.
• Compilar y distribuir los archivos asset.
• Realizar un control de versión en la caché de los navegadores de los clientes.
• Utilizar sass para las hojas de estilo, administrar las variables sass y generar temas.
• Personalizar las hojas de estilo de las distribuciones, de acuerdo a los temas instalados.
• Reemplazar los archivos que trae una extensión, por archivos propios.

Assets

La librería principal es Assets. Se encarga de incluir activos en una página web.

De modo complementario, es posible utilizarla para declarar etiquetas meta y variables, que luego, pueden ser utilizadas por una plantilla.

La librería debe ejecutarse a través de una instancia única:

$assets = app('assets');

Sin embargo, pocas veces se utiliza la librería directemente, ya que es más común utilizarla, indirectamente, con el objeto Template.

Es decir, los métodos que detallaremos a continuación, podrán ser utilizados desde una plantilla.

Agregar archivos css

Agregue archivos css de la siguiente manera:

$assets->css('path/to/css/styles.css, path/to/css/styles2.css');
$assets->css(['path/to/css/styles.css', 'path/to/css/styles2.css']);
$assets->css([
	['href' => 'path/to/css/styles.css', 'integrity' => '...']
]);

La lista de rutas a las hojas de estilos puede ser:

1. una cadena separada por comas;
2. un arreglo;
3. un arreglo multidimensional, siendo cada uno de ellos, un par attributo/valor del activo.

Agregar archivos javascript

$assets->js('path/to/js/scripts.js, path/to/js/scripts2.js', true);
$assets->js(['path/to/js/scripts.js', 'path/to/js/scripts2.js']);
$assets->js([
	['src' => 'path/to/js/scripts.js', 'defer' => '']
]);

La lista de rutas a los archivos javascript puede ser:

1. una cadena separada por comas;
2. un arreglo;
3. un arreglo multidimensional, siendo cada uno de ellos, un par attributo/valor del activo.

Por defecto, los archivos javascript se declaran antes del cierre de la etiqueta body.

Si se desea declarar los archivos javascript en el head, debe pasarse true como segundo parámetro.

Utilizar los archivos de assets

Las rutas a los archivos generados por Assets, se definen como:

"assets/asset-key.min.css"
"assets/asset-key.min.js"

Con el solo hecho de utilizar estos archivos, ya estamos utilizando las funciones de la librería. Por ejemplo:

• en producción, las hojas de estilo pueden ser reemplazadas por las de otro tema;
• todos los activos pueden realizar un control de versión en la caché de los navegadores;
• en tiempo de desarrollo, es posible utilizar los archivos originales en lugar de las agrupaciones.

Ejecutar javascript

Es posible ejecutar código javascript cuando se termina de cargar la página, de la siguiente manera:

$assets->domready("alert('Hello word')");

Agregar etiquetas meta

Para ingresar etiquetas meta, utilice el método:

$assets->meta(['title' => '...', 'content' => '...']);

Utilizar un único método

Para agregar opciones de manera flexible, incluso variables aleatorias, se utiliza el método:

$assets->options([
	'js' => 'path/to/js/scripts.js',
	'css' => ['path/to/css/styles.css', 'path/to/css/styles2.css'],
	'domready' => "alert('Hello word')",
	'hash' => 'page-hash',
]);

En el ejemplo, agregamos una variable llamada hash. Para recuperar esa variable, se utiliza:

$hash = $assets->getOption('hash');

Cache

La caché es un área de almacenamiento de los datos utilizados con más frecuencia. Guardar y recuperar datos en una caché permite mejorar el rendimiento general de la aplicación.

Está librería es una implementación de PSR-16 (Simple Cache). Los datos son guardados, dependiendo del adaptador, en:

• File, un archivo con los datos serializados.
• Memcached,
• Apcu,
• Redis, 
• Null, utilizado para las pruebas.

Crear una instancia Cache

Se recomienda enfáticamente utilizar una instancia única, a través de la fachada cache().

Ejemplo inicial

En el siguiente ejemplo se guarda un dato en la caché y luego se recupera.

$cache = cache();
// set data
$cache->set('key', $data, 300);
// get data
$data = $cache->get('key');

Métodos

Cache::get

Obtiene un valor de la memoria caché.

public Cache::get( string $key, mixed $default = null ): mixed

key

La clave única de este elemento en la memoria caché.

default

Valor predeterminado para devolver si la clave no existe.

Cache::set

Persiste los datos en la memoria caché, a los que se hace referencia de forma exclusiva mediante una clave con un tiempo TTL de expiración opcional.

public Cache::set ( string $key, mixed $value, mixed $ttl = null ): bool

key

La clave del artículo para almacenar.

value

El valor del artículo para almacenar, debe ser serializable.

ttl

El valor TTL de este elemento, puede ser null, int o DateInterval.

Cache::delete

Elimina los datos de la memoria caché.

public Cache::delete ( string $key ): bool

key

La clave del artículo para eliminar.

Cache::clear

Limpia todas las claves de la memoria caché.

public Cache::clear ( ): bool

Config

Administra las configuraciones en tiempo de ejecución.

Ejemplo inicial

$config = new Config();

// El nombre del sitio
$siteName = $config->get('site.name');

Sistema de claves de configuración

Cada configuración se llamará a sí misma por un nombre de clave único.

El nombre de la clave está compuesto por un ámbito y un nombre de configuración, separados por punto: {scope}.{config_name}.

El ámbito estará compuesto por el alias de la extensión a la que pertenece y, opcionalmente, un sub-ámbito, separados por guión medio: {extension_alias}{-sub-scope}?.

En el siguiente ejemplo, tenemos la configuración developer_mode de la extensión system:

$key = 'system.developer_mode';

En este otro ejemplo, tenemos la configuración host del sub-ámbito memcached de la extensión cache:

$key = 'cache-memcached.host';

Métodos

Config::get

Encuentra una clave y la devuelve.

public Config::get( string $key = '' ): mixed

key

La clave a buscar. Si se ingresa sólo el ámbito de la clave, devolverá todas las configuraciones de dicho ámbito.

Config::has

Devuelve verdadero si encuentra la configuración.

public Config::has( string $key = '' ): bool

key

La clave a buscar.

Config::set

Guarda un valor en tiempo de ejecución. Este valor no quedará en memoria permanente.

public Container::set( string $key = '', mixed $value = null ): bool

Key

Una clave para la entrada.

value

El valor a registrar.

La fachada config

Se recomienda el uso de la función de fachada config(). Si no se especifica una clave, devolverá la instancia única.

function config( string $key = '' ): object

key

La clave de la configuración a buscar.

Container

Contenedor de inyección de dependencia.

Container::__construct

Crea un contenedor.

public Container::__constuct( )

Container::getInstance

Devuelve una instancia única de la clase.

public static Container::getInstance( ): self

Container::get

Encuentra una entrada del contenedor por su identificador y la devuelve.

public Container::get( string $id ): mixed

id

Identificador de la entrada a buscar.

Container::has

Devuelve verdadero si el contenedor puede devolver una entrada para el identificador dado.

public Container::has( string $id ): bool

id

Identificador de la entrada a buscar.

Container::set

Guarda la instancia de una clase.

public Container::set( string $id, object $class, bool $rewrite = false ): void

id

Un identificador para la entrada.

class

Una instancia de la clase a registrar.

rewrite

Permite reescribir la entrada si ya existe.

Container::unset

Elimina una instancia de clase.

public Container::unset( string $id ): void

id

El identificador de la entrada a eliminar.

Container::register

Registra el nombre de una clase, para instanciarla en caso de ser requerida.

public Container:.register( string $id, string $className = '', bool $shared = false ): void

id

Un identificador para la entrada.

className

El nombre de la clase.

shared

Si es true, se creará una instancia única.

La fachada app

Se recomienda el uso de la función de fachada app().

Si se especifica un identificador, ejecuta el método Container::get, de lo contario, devuelve la instancia única, es decir: Container::getInstance.

function app(string $id = '' ): object

id

Identificador de la entrada a buscar.

Currency

Gestiona el formateo de monedas.

El formato de la moneda no depende de las configuraciones, sino que utiliza el sistema de idioma y traducciones. En este sentido, el framework tiene una entrada de traducción como la siguiente $.,00, con la cual, es posible configurar el formato de la moneda, dependiendo del idioma.

Si atendemos a la etiqueta, podemos ver que, después del símbolo de dolar $, que sólo cumple una función informativa, tenemos el separador para las unidades de mil, el separador para los decimales y el número de decimales, representado con la cantidad de ceros.

Ejemplo inicial

$currency = new Currency();
echo $currency ->format(1234.5); // 123.4,50

Currency::format

Formatea un valor monetario. Internamente, utiliza la función number_format.

public Currency::format( float $number, bool $simplify_integers = false ): string

number

El valor a formatear.

simplify_integers

En el caso de tener un valor entero, no agregará los ceros correspondientes a los decimales.

Currency::removeFormat

Transforma un valor formateado en un número de punto flotante.

public Currency::removeFormat( string $number ): float

number

El valor a formatear.

Currency::getDecimals

Devuelve el número de decimales configurados.

public Currency::getDecimals( ): int

Currency::__toString

Devuelve la entrada de traducción con la que ha sido configurada la clase.

public Currency::__toString( ): string

Database

Gestiona la conexión a la base de datos y sus consultas. Actualmente, el framework utiliza sólo base de datos MySql y MariaDB.

Métodos básicos

Database::__construct

En el constructor se realiza la conexión a la base de datos.

public Database::__construct ( array $config = [] )

Salvo los casos en los en que se debe cambiar la base de datos por defecto, se recomienda enfáticamente utilizar una instancia única, a través de la función de fachada db().

Métodos heredados

Database::prepare

Este método es practicamente el original de la librería mysqli. Internamente, agrega el prefijo a las tablas y maneja errores.

public Database::prepare ( string $query ): StatementInterface

Database::quote

Escapa un valor que será incluido en una consulta.

public Database::quote ( mixed $value ): string

value

El valor a escapar. Se desaconseja su uso en favor de las consultas preparadas.

Database::lastInsertId

Devuelve el identificador de la última consulta de inserción.

public Database::lastInsertId ( ): int

Consultas que no devuelven resultados

Database::exec

Ejecuta una consulta a la base de datos.

public Database::exec ( string|StatementInterface $stmt, mixed ... $params ): int

stmt

Puede ser una cadena con la consulta o un objeto que implememente StatementInterface.

params

Valores de relleno para las consultas preparadas.

Database::execAll

Ejecuta un conjunto de consultas preparadas.

public Database::execAll ( string|StatementInterface $stmt, mixed ...$params ): void

query

Puede ser una cadena con la consulta o un objeto que implememente StatementInterface.

params

Los parámetros que se deseen agregar a la consulta. Si un parámetro es escalar, todas las consultas contendrán dicho parámetro. En cambio, si es un arreglo, cada consulta tendrá el valor en correspondencia con un índice.

Consultas que devuelven resultados

Database::query

Ejecuta una consulta a la base de datos y guarda internamente su resultado. Devuelve un objeto del tipo ResultInterface con el que podrá obtener los resultados.

public Database::query ( string|StatementInterface $stmt, mixed ... $params ): ResultInterface

stmt

Puede ser una cadena con la consulta o un objeto que implememente StatementInterface.

params

Valores de relleno para las consultas preparadas.

ResultInterface::fetch

Retorna una fila de resultados.

public Database::fetch ( $style = Database::FETCH_ASSOC ): array

style

Una de las constantes de tipo de resultados.

ResultInterface::fetchColumn

Devuelve una única columna de la siguiente fila de un conjunto de resultados, o false si no existen más filas.

public ResultInterface::fetchColumn ( int $column_number = 0 ): mixed

column_number

El número de índice de la columna a retornar.

ResultInterface::fetchAll

Devuelve un array que contiene todas las filas del conjunto de resultados.

public ResultInterface::fetchAll ( int $style = Database::FETCH_ASSOC, $index = null, array $rows = [] ): array

style

Controla el contenido del array devuelto, tal como en db::fetch().

index

Este parámetro tiene diferentes comportamientos según el parámetro style. Sin perjuicio de lo dicho, es importante aclarar que no es igual al comportamiento que el mismo método en PDO.

En caso de que el parámero style sea db::FETCH_NUM o db::FETCH_ASSOC, las filas tendrán por índice el valor del campo que se indique en este parámetro.

En caso de que el parámero style sea db::FETCH_COLUMN, el index puede tener el valor de la columna o el nombre del campo que se incluirá de cada fila. También, puede ser un array que contenga el par [index => column] o [key => field].

rows

Un array que se utilizará como base.

Marcadores de posición

El marcador de posición o placeholder por defecto en MySql es el símbolo de pregunta (?). Además de dicho marcador, a continuación, listaremos otros que pofrán utilizarse, y que son de gran ayuda.

Marcador de posición flexible ( ?.. )

Un marcador de posición flexible, simbolizado como ?.., permite variar el número de valores de relleno, según el número de valores que se pasan como parámetro.

En el siguiente ejemplo, se consulta los datos de los usuarios que se pasan a través de un arreglo.

$users = [1, 2, 5, 8];

$db->query("SELECT * FROM `users` WHERE id IN (?..)", $users);

Marcador de posición de conjunto ( ?? )

Un marcador de posición de conjunto genera los valores de relleno a partir de arreglos que poseen el par field => value. Se pueden utilizar en sentencias INSERT, UPDATE y INSERT .. ON DUPLICATE KEY.

Por ejemplo, si tenemos un conjunto:

$data = ['username' => 'user123', 'email' => 'user123@example.com'];

Podemos hacer las siguientes consultas:

$db->exec("INSERT INTO `users` ( ?? ) VALUES ( ?? )", $data) ;
$db->exec("UPDATE `users` SET ?? WHERE id = ?", $data, $user_id) ;
$db->exec("INSERT INTO `users` ( ?? ) VALUES ( ?? ) ON DUPLICATE KEY UPDATE ??", $data) ; 

Marcador de posición de búsqueda de texto ( %? )

Este tipo de marcador de posición modifica (y prepara) el valor pasado como parámetro, para ser utilizado de manera más efectiva en las sentencias LIKE ?.

Actualmente, lo que hace el framework es:

1. si el al texto de búsqueda tiene un carácter, le agregará un comodín % al final, por lo que filtrará todos los valores que comienzan con dicho caracter.
2. si el texto de búsqueda tiene más de un caracter, agregará en ambos extremos el comodín %, por lo que filtrará los valores que contengan dicho texto.

En el siguiente ejemplo, devolverá los usuarios cuyo username comience con la letra m.

$username = 'm';
$db->query("SELECT * FROM `users` WHERE `username` LIKE %?", $username) ;

Declaraciones flexibles

Las declaraciones flexibles permiten al framework interactuar con la declaración sql. Para escribir una declaración flexible, se utilizarán corchetes.

Ejemplo inicial

En la siguiente consulta, se modifica el orden a través de una variable pasada en el método Database::sort.

$db->sort($sort); // $sort puede ser 'asc' o 'desc'
$db->query("SELECT * FROM `users` ORDER BY name [SORT]");

Database::where

Crea la declaración WHERE ... AND ... . En la consulta, se escribe como [WHERE].

Este método permite ingresar parámetros, su uso invalida aquellos parámetros ingresados en los métodos query y exec.

public Database::where ( string $where, ...$params ): void

where

La declaración.

params

Todos los parámetros que requiere la declaración.

Buscar en varios campos

En ocaciones, debemos buscar un valor en varios campos, utilizando el operador OR. Para ello, el método incluye una forma abreviada, utilizando la barra vertical (|), y, si se quiere, ingresando una única vez el parámetro.

// lo convencional
$db->where("(firstname = ? OR surname = ?)", $seach, $seach);

// abreviado
$db->where("firstname = ?|surname = ?", $seach);

Database::having

Crea la declaración HAVING ... AND .... En la consulta, se escribe como [HAVING].

Este método permite ingresar parámetros, su uso invalida aquellos parámetros ingresados en los métodos query y exec.

public Database::having ( string $having, ...$params ): void

where

La declaración.

params

Todos los parámetros que requiere la declaración.

Database::setParam

Cuando se utiliza los métodos where o having, se invalidan los parámetros ingresados en los métodos query y exec. Por lo tanto, este método permite ingresar un parámetro, sin que sea necesaria una declaración flexible.

public db::setParam ( mixed $param ): void

param

El parámetro a ingresar.

Database::order

Crea la declaración ORDER BY .... a partir de una lista de varias opciones. En la consulta, se escribe como [ORDER].

public db::order ( int &$order, array $orders, int $default = 0 ): void

order

El índice de la declaración a utilizar, entre las opciones pasadas en el siguiente parámetro.

Note que este valor se pasa por referencia.

En caso de no hallar una declaración, el método sobrescribirá la variable con el valor por defecto, de esta manera, no tendrá que preocuparse de la lógica del caso.

orders

La lista completa de las posibles declaraciones a utilizar.

default

Valor por defecto para el caso de que no exista el índice pasado en el primer parámetro.

Database::sort

Completa la declaración ORDER BY .... con las declaraciones ASC y DESC. En la consulta, se escribe como [SORT].

Si en la consulta no se halla el marcador [SORT], la declaración se escribirá al final de la declaración ingresada en el método db::order. 

public db::sort ( string &$sort, string $default = 'asc' ): void

sort

Una cadena con cualquiera de las dos opciones asc o desc.

Note que este valor se pasa por referencia.

En caso de pasar un valor distinto a los permitidos, el método sobrescribirá la variable con el valor por defecto, de esta manera, no tendrá que preocuparse de la lógica del caso.

default

Valor por defecto.

Date

Extiende las funciones de DateTime, fundamentalmente, en lo referido a los formatos de fechas locales.

Ejemplo inicial

$date = new Date('2018-01-01');
$date->format('d-M-Y'); // 01-ene-2018

Date::format

Formatea una fecha. La salida, si es necesario, es traducida.

public Date::format ( string $format ): string

format

Formato aceptado por date().

Date::formatInterval

Formatea un intervalo de tiempo. La salida considerará años, meses, días, horas, minutos y segundos.

public Date::formatInterval ( mixed $datetime2, int $granularity = 2 ): string

datetime2

Una cadena o un objeto DateTime.

granularity

Cantidad de iteraciones que se tendrán en cuenta para la salida.

Propiedades

Las siguientes propiedades muestran parte de la fecha. Internamente, ejecutan el método Date::format().

Ejemplo

$date = new Date('2018-01-01');
echo $date->dayName; // Lunes

Email

Gestor de envío de correo electrónico.

Ejemplo inicial

$email = new Email();
$email->to('to@example.com');
$email->replyTo('reply@example.com');
$email->subject('Test');
$email->message('...', Email::MESSAGE_ONLY_PLAIN);

$result = $email->send();

Email::__construct

public Email::__construct( TransportInterface $transport = null )

transport

Un transporte para enviar los correos. Si no se ingrresa un transporte, se utilizará el declarado en las configuraciones.

Email::from,

Email::replyTo,

Email::to,

Email::cc,

Email::bcc

Métodos para ingresar direcciones de correo.

public Email::to( string|array $address ): void

address

Acepta formatos del tipo: 

1. "example@example.com",
2. "<example@example.com>",
3. "Example <example@example.com>",
4. ['name' => 'Example', 'address' => 'example@example.com']

Email::$subject, Email::subject

Propiedad y método para ingresar el motivo del mensaje.

public Email::subject( string $subject ): void

Email::message

Ingresa el mensaje.

public Email::message ( string $message, mixed $alternative ): void

message

El mensage a enviar, puede ser texto plano o html.

alternative

Puede ser una cadena de texto plano, alternativo al mensaje. También una de las siguientes constantes:

Email::attachment

Adjunta archivos al correo.

public Email::attachment (
 string $filename,
 string $name = '',
 string $disposition = 'attachment',
 string $cid = '',
 string $encoding = 'base64'
): bool

filename

Ruta al archivo a adjuntar.

name

Nombre del archivo.

disposition

Puede ser 'attachment' o 'inline'

cid

Identificador. Se utiliza sólo en la disposición inline.

encoding

Generalmente será base64.

Email::send

Envia el mensaje a las direcciones ingresadas.

public Email::send ( string $transport = '' ): bool

transport

Selecciona un transporte para enviar el mensaje, de no ingresar nada, se enviará a través del transporte predeterminado.

Propiedades

La mayoría de las propiedades son configurables desde el sistema. Eso simplifica la utilización.

Email::$x_mailer

Agrega el encabezado x-mailer.

public Email::$x_mailer

Email::$priority

Agrega el encabezado priority.

public Email::$priority = 0

Email::$h_charset

Juego de caracteres del encabezado.

public Email::$h_charset // 'iso-8859-1' or 'utf-8' or ...

Email::$h_enconding

Codificación del encabezado.

public Email::$h_enconding // 'Q' or 'B'

Email::$m_charset

Juego de caracteres del mensaje.

public Email::$m_charset

Email::$m_enconding

Codificación del mensaje.

public Email::$m_enconding

Email::$word_wrap

Ajuste de línea del mensaje.

public Email::$word_wrap = 70;

Email::$attachment_base

Ruta base para los archivos adjuntos.

public Email::$attachment_base = '';

Transportes

Los tranportes deben implementar la interface TransportInterface. También, pueden extender la clase abstracta TransportAbstract, que implementa la depuración.

Los transportes disponibles son:

1. Mail: internamente, utiliza la función mail.
2. Smtp: implementación del protocolo smtp.
3. Null: utilizado para los test y la depuración.

Para utilizar un tranporte o para configurarlo, debe ir a los Ajustes del CMS. En cambio, si por ejemplo, quiere tener una configuración separada del CMS, debe inyectar una instancia del transporte al crear un objeto Email.

use Junco\Email\Transport\MailTransport;

$transport = new MailTransport();
$email = new Email($transport);

use Junco\Email\Transport\SmtpTransport;

$transport = new SmtpTransport();

public SmtpTransport::$smtp_host = '...';
public SmtpTransport::$smtp_port = 0;
public SmtpTransport::$smtp_timeout = 30;

public SmtpTransport::$smtp_secure = true;
public SmtpTransport::$smtp_auth = true;
public SmtpTransport::$smtp_user = '...';
public SmtpTransport::$smtp_pwd = '...';

Filesystem

Gestor del sistema de archivos.

Filesystem::__construct

public Filesystem::__construct( string $abspath = SYSTEM_ABSPATH )

abspath

Ruta absoluta. Por defecto será la indicada en la constante del sistema: SYSTEM_ABSPATH.

Filesystem::setMode

Guarda el modo con que serán creados los archivos.

public Filesystem::setMode ( int $mode ): void

mode

El modo con el que, si es necesario, se crearán los directorios. Se utiliza en Filesystem::copy. 

Filesystem::scandir

Escanea un directorio. Devuelve los archivos y carpetas hallados.

public Filesystem::scandir ( string $dir = '', array $ignore = [] ): array

dir

El directorio a escanear.

ignore

Archivos a ignorar.

Filesystem::mkdir

public Filesystem::mkdir ( string $dir, int $mode = null ): bool

dir

El directorio a crear.

mode

El modo con el que, si es necesario, se crearán los directorios.

Filesystem::copy

Copia archivos y directorios. En éste último caso, copiará todo su contenido.

public Filesystem::copy ( string $from, string $to ): bool

from

La ruta de la fuente. De no existir, devolverá false.

to

La ruta de destino.

Filesystem::rename

Renombra archivos y directorios.

Si deseamos renombrar un directorio y ya existe el directorio de destino, los mezclará, rescribiendo cualquier archivo de igual nombre.

public Filesystem::rename ( string $from, string $to ): bool

from

La ruta de la fuente. De no existir devolverá false.

to

La ruta de destino.

Filesystem::remove

Remueve un directorio de manera recursiva.

public Filesystem::remove ( string $node ): bool

node

La ruta a remover, puede ser un archivo o una carpeta.

Filesystem::removeDirIfEmpty

Remueve los directorios, de manera recursiva, sólo si están vacíos.

public Filesystem::removeDirIfEmpty ( string $dir, array $ignore = [] ): bool

dir

El directorio a eliminar.

ignore

Archivos que, de existir, no los tomará en cuenta.

Filesystem::chmod

Cambia los permisos de archivos y/o directorios.

public Filesystem::chmod ( string $node, int $mode[, $option = 0] ): bool

node

La ruta al archivo o directorio.

mode

El modo, puede ser octal u decimal.

option

Las opciones pueden ser:

• 0 = no se incluyen las sub-carpetas
• 1 = incluye sólo las sub-carpetas
• 2 = incluye sub-carpets y sub-archivos
• 3 = sólo sub-archivos

Filesystem::sanitizeDir

Fuerza a que la ruta de un directorio finalice con un separador determinado.

public Filesystem::sanitizeDir ( string &$dir, string $separator = DIRECTORY_SEPARATOR ): void

dir

El directorio a sanitizar.

separator

Barra de separación.

MediaStorage

Se encarga de la ruta base a la carpeta media. Esta carpeta se utiliza para que las aplicaciones guarden los archivos estáticos que suben los usuarios, estos archivos pueden ser: imágenes, videos, documentos, etc.

MediaStorage::getPath

Devuelve la ruta absoluta al directorio media/.

public MediaStorage::getPath( string $path = '' ): string

path

Concatena la ruta a continuación de la ruta absoluta.

También, acepta una clave de configuración, lo que hará buscar en las configuraciones la ruta a concatenar.

MediaStorage::getUrl

Devuelve la url al directorio media/.

public MediaStorage::getUrl( string $path = '', bool $absolute = false): string

path

Concatena la ruta a continuación de la url.

También, acepta una clave de configuración, lo que hará buscar en las configuraciones la url a concatenar.

absolute

Opción para cambiar entre url absoluta o parcial.

Ejemplos

$media_path = media_path(); // -> absolute/path/to/media/
$media_url = media_url('contents.image_path', true) // -> https://example.com/media/contents/image/

UploadedFileManager

Gestiona la carga de archivos. 

Ejemplo inicial

// upload
$ufm = new UploadedFileManager($uploadedFile);
$ufm->moveTo('the/directory/');

$filename = $ufm->getFilename();

UploadedFileManager::__construct

public FilesUploadedManager::__construct ( UploadedFileInterface|array|null $UploadedFile[ , bool $isMultiple = false ] )

UploadedFile

Puede ser un objeto UploadedFileInterface o, en caso de ser multiple, un array de ellos. También acepta un valor null.

isMultiple

Corresponde con la carga multiple de archivos.

UploadedFileManager::validate

Valida los archivos agregados. Si uno de los parámetros es false, no se validará. En caso de fallo, lanza una Exception.

public UploadedFileManager::validate ( array $rules = null ): void

rules

Las reglas podrán ser:

UploadedFileManager::moveTo

Mueve los archivos agregado. En caso de fallo, lanza una Exception.

public UploadedFileManager::moveTo ( string $targetPath, int $rename = 0, bool $rewrite = false ): void

targetPath

Ruta al directorio donde se guardarán los archivos.

rename

Uno de los modos en que puede ser renombrado el archivo a subir.

rewrite

Está opción permite reescribir un archivo existente cuando se sube uno de igual nombre. En caso de optar por no reescribir, se lanzará una excepción.

UploadedFileManager::setCurrentFile

Configura el archivo actual, para que, en caso de ser necesario, se reemplace por el nuevo archivo.

public UploadedFileManager::setCurrentFile( ?string $filename = null)

filename

El nombre del archivo actual.

UploadedFileManager::getUploadedFile

Obtiene el objeto UploadedFile que se está administrando, o un array de ellos en caso de ser multiple.

public UploadedFileManager::getUploadedFile( ): mixed

UploadedFileManager::getUploadedFileData

Obtiene un array con los datos correspondientes a uno o multiples archivos.

public UploadedFileManager::getUploadedFileData( ): array

Valores devueltos

Los valores devueltos son:

[
 'clientFilename'    => 'original_name.extension',
 'filename'             => 'current_name.extension',
 'basename'           => 'current_name',
 'extension'           => 'extension'
];

UploadedFileManager::getClientFilename

Obtiene el nombre original del archivo, o un array de ellos.

public UploadedFileManager::getClientFilename( ): string|array

UploadedFileManager::getFilename

Obtiene el nombre del archivo, o un array de ellos.

public UploadedFileManager::getFilename( ): string|array

UploadedFileManager::$num_files

Devuelve el número de archivos agregados hasta el momento.

public UploadedFileManager::$num_files : int

UploadedImageManager

Extiende la clase UploadedManager para gestionar imágenes.

Redimensionar imágenes

El nuevo tamaño de una imagen va a estar dado por: el modo de la redimensión y un valor. A continuación, se muestra un cuadro con los modos posibles:

UploadedImageManager::resize

Redimensiona un imagen a varios tamaños.

public UploadedImageManager::resize(
	string $resizes_path,
	mixed  $resizes,
	int    $resize_mode = 0,
	bool   $save_orig = true
): self

public UploadedImageManager::setResizes (
	string $resizes_path,
	mixed  $resizes,
	int    $resize_mode = 0,
	bool   $save_orig = true
): self

$resizes = ['small' => 120, 'large' => 1024];

$resizes = [
	'small' => ['size' => 120, 'mode' => 1],
	'large' => ['size' => 1024, 'mode' => 2],
];

public UploadedImageManager::setOrder ( string $order ): self

public UploadedImageManager::setCurrentImage ( string $filename = null ): self

public UploadedImageManager::setCurrentImages ( array|string $filenames, string $separator = ',' ): self

Filter

Al igual que su homónima de PHP, filtra el valor de diferentes variables, a partir de la definición de reglas.

Ejemplos iniciales

$email = Filter::input(GET, 'email'); 
// -> '...'

$data = Filter::all(POST, [
	'username' => 'text|max:48|required',
	'password' => 'text|required'
]);
// -> ['username' => '...', 'password' => '...'];

En el primer ejemplo, del arreglo global $_GET, se filtra y devuelve la clave email.

En el segundo ejemplo, del arreglo global $_POST, se filtra y devuelven las claves username y password, en este caso, va a devolver un array con dichas claves.

Los métodos

Filter::input

Filtra el valor de una variable global, similar a filter_input.

public static Filter::( int $type, string $var_name, string|array $rules = '' ): mixed

type

Pueden ser las constantes INPUT_GET O INPUT_POST, o sus alias GET y POST.

var_name

El nombre de la variable que se desea recuperar.

rules

Las reglas con las que se filtrará la variable. Puede ser un arreglo o una cadena con todas las reglas separadas por una barra vertical.

Filter::var

Filtra el valor de una variable, similar a filter_var.

public static Filter::(mixed $variable, string|array $rules = ''): mixed

variable

La variable a filtrar.

rules

Las reglas con las que se filtrará la variable. Puede ser un arreglo o una cadena con todas las reglas separadas por una barra vertical.

filter::all

Filtra un arreglo o una variable global, similar a filter_input_array y filter_var_array, aunque no es exáctamente igual. Los cambios están en el tercer parámetro y en los valores devueltos.

public static Filter::all ( array|int $data, array $definition, bool $iterate = false ): ?array

data

Si el valor es una de las constantes GET o POST, las variables se buscarán en las variables globales. De lo contrario se viltrará el arreglo de variables.

rules

Un arreglo que contiene en las claves el nombre de la variable, y en el valor, las reglas de filtrado.

iterate

Si es false, devuelve un arreglo igual que filter_input_array con el tercer parámetro activo, add_empty = true.

Si es true, devuelve un arreglo multidimensional con filas que contienen los pares key => value que han sido definidos o null en el caso de no hallar una fila para devolver.

Las reglas

Las reglas consisten en un filtro y modificadores. Los filtros dan los tipos de datos que deseamos obtener y los modificadores mejoran las espectativas.

La librería pretende que los valores devueltos sean siempre utilizables, sobre todo, para ser guardados en una base de datos. Por eso, si la regla falla, tendremos siempre un valor aceptable.

Filtros

int

Devuelve un entero.

id

Es un alias de: int|min:0.

float

Devuelve un número con punto flotante.

text

Devuelve una cadena a la que se le aplica el filtro FILTER_FLAG_STRIP_LOW y las funciones htmlspecialchars y trim.

multiline

Devuelve una cadena a la que se le aplica el filtro FILTER_SANITIZE_SPECIAL_CHARS y las funciones nl2br y trim. El resultado es un valor seguro obtenido de un textarea.

email

Valida un email a través del filtro FILTER_VALIDATE_EMAIL.

url

Valida una url a través del filtro FILTER_VALIDATE_URL. Como valor, acepta una lista blanca de protocolos, por ejemplo: 'url:http,https'.

color

Valida un color. Como valor, acepta una lista de tipos de notaciones, por ejemplo: 'color:hex'.

Actualmente, los tipos de notaciones válidos son:

1. hex hexadecimal de 6 dígitos;
2. hex+ hexadecimal con 3, 4, 6 u 8 dígitos;
3. named colores nombrados de css;
4. named+ a los colores nombrados se le agregan las palabras claves: currencolor y transparent.

slug

Sanitiza una cadena para ser utilizada como "slug" en una url.

bool

Valida una valor boolean utilizando el filtro FILTER_VALIDATE_BOOLEAN.

Puede devolver un boolean o cualquier otro valor pasado en el filtro. Por ejemplo: bool:no/yes devolverá una cadena con cualquiera de estos valores. Otro ejemplo muy útil puede ser bool:0/1.

date, datetime, time, month

Validan fechas y horas reales. En caso de que falle, devolverá el valor null, que es un valor aceptable para los campos date de una base de datos.

file, files, image, images, archive

Cargan uno o varios archivos. Devuelven SIEMPRE un objeto del tipo UploadedFileManager.

Pueden aceptar como valor, las extensiones permitidas. Por ejemplo: 'file:doc,docx'.

callback

Utiliza el filtro FILTER_CALLBACK.

enum

A partir de una cadena, intenta devolver un enum válido. El filtro requiere que se le pase como valor el enum que se desea utilizar, por ejemplo:

// array
$rule = ["enum" => Junco\Users\Enum\UserStatus::class];
// string
$rule = "enum:users.user_status";

Si se utiliza el modificador default sin un valor, buscará el valor por defecto en un método estático de igual nombre del Enum, por ejemplo:

$rule = "enum:users.user_status|default";

enum UserStatus {
    case active;

    static function default(): self
    {
        return self::active;
    }
}

json

Valida una cadena json. Alternativamente, puede decodificar la cadena como un objeto o un array asociativo. Algunos ejemlos:

$rule = 'json:decode'; // json_decode($value)
$rule = 'json:decode_a'; // json_decode($value, true)
$rule = 'json:decode_a,2'; // json_decode($value, true, 2)

none

En caso de no colocar un filtro, se utilizará éste por defecto. Básicamente, no hace nada y equivale a FILTER_DEFAULT.

Modificadores

min, max

En los números, modifica los valores por defecto.

En los textos, verifica el tamaño de las cadenas.

En las fechas, si no se le coloca una fecha, tomará la fecha actual.

En los archivos, verifica su tamaño.

default

Modifica los valores por defecto del sistema. Cualquier nuevo valor, será parseado al tipo de filtro.

array

Devolverá un array. En caso de fallo, devolverá un array vacío. Si se le pasa el parámetro :first, tomará la entrada como un array, pero devolverá el primer valor del mismo.

in

Devolverá solo aquellos valores pasados como parámetros o false en caso de fallo.

or_use

Utilizará el valor de otra clave si su valor se evalúa como falso. En todos los casos, se utilizarón los valores de entrada.

$value = Filter::all([
    'title' => '',
    'slug' => 'slug|or_use:title'
]);

En el ejemplo, si no se ingresa un valor de slug, se utilizará el valor de title.

only_if

Devolverá la clave y su valor sólo si la clave pasada como parámetro tiene un valor que se representa como verdadero.

$value = Filter::all([
    'accept' => 'bool',
    'item_id' => 'id|only_if:accept|required'
]);

En el ejemplo, solo si se acepta, deberá solicitarse un item_id.

only_if_not

Igual que only_if, pero devolverá la clave y su valor, solo si la clave pasada como parámetro tiene un valor que se representa como falso.

required

La clave deberá tener un valor true o lanzará una excepción. En caso de ser un array, también comprobará que todos sus valores sean true.

Si el modificador tiene un valor "abort", en lugar de una excepción lanzará un error del sistema.

Cuadro de filtros y modificadores

Http

Contiene las librerías básicas http de un framework moderno. Estas librerías están separadas en:

Client

Librerías para consultas http. Implementa la interface PSR-18 (HTTP Client)

Server

Librerías para consultas http. Implementa la interface PSR-15 (HTTP Server Request Handlers).

Message

Librerías para gestionar los mensages http, tanto de consultas, como de respuestas. Implementa la interface PSR-7 (HTTP message interfaces).

Emitter

Librería para emitir una respuesta http.

Jobs

En su conjunto, la librería permite realizar tareas en segundo plano.

Jobs

La clase ejecuta una cola de trabajos. Para ello, guarda un trabajo en una cola y, luego, desde una llamada en segundo plano, los ejecuta.

Las llamadas en segundo plano pueden ser a través de tareas programadas (cron) o de un Worker. Actualmente, el framework sólo permite la primera opción.

Internamente, utiliza un Driver para la persistencia. Actualmente, sólo se puede utilizar la base de datos.

Jobs::__construct

public Jobs::__construct( string $driver = '' )

driver

El manejador que almacenará y recuperará los trabajos.

Jobs::push

Coloca un trabajo al final de una cola de trabajos.

public Jobs::push( JobInterface $job, string $queue = '' ): void

job

Un objeto que implementa JobInterface, capaz de realizar un trabajo.

queue

La cola donde se colocará el trabajo a realizar.

Jobs::run

Ejecuta la cola de trabajos.

public Jobs::run( string $queue = '' ): void

queue

La cola de trabajos a ejecutar.

JobInterface

Interface necesaria para guardar un trabajo en cola. Como se ve a continuación, tiene un único método llamado handle, que será ejecutado cuando se ejecute la cola.

Jobs::handle

Método llamado cuando se ejecuta el trabajo. Debe retornar un estado, representado con un valor booleano.

public JobInterface::handle( ): bool

Language

Gestiona el idioma y las traducciones.

Language::__construct

En el constructor se inicializa completamente el idioma. 

public Language::__construct( string $domain = '', string $locale = '' )

El dominio donde se guardarán las traducciones.

La ruta al directorio local.

Se recomienda ejecutar la clase a través de una instancia única:

$language = app('language');

public Language::getAvailables(): array

public Language::getCurrent(): string

public Language::getTranslator(): TranslatorInterface

public Language::gettext( string $message ): string

function _t( string $message ): string

public Language::ngettext( string $singular, string $plural, int $n ): string

function _nt( string $singular, string $plural, int $n ): string

Logger

Crea un registro del sistema, que puede tener diversos usos.

Por ejemplo, se puede utilizar para realizar un seguimiento de los errores; o informar problemas de seguridad; o, simplemente, generar información en tiempo de ejecución.

Es una implementación de PSR-4. Actualmente, guarda los registros en un archivo.

Crear una instancia Logger

Se recomienda enfáticamente utilizar una instancia única, a través de la fachada del contenedor app('logger').

Ejemplo inicial

$logger = app('logger');
$logger->log(Logger::WARNING, 'This is a warning...');

Logger::log

Realiza un registro.

public Logger::log ( int $level, string $message, array $context = [] ): void

level

Un nivel de registro. Puede utilizar las constantes:

Logger::EMERGENCY;
Logger::ALERT;
Logger::CRITICAL;
Logger::ERROR;
Logger::WARNING;
Logger::NOTICE;
Logger::INFO;
Logger::DEBUG;

message

Una descripción corta del problema, a modo de mensaje.

context

Un arreglo asociativo con cualquier dato que amplie la información.

Logger::emergency,

Logger::alert,

Logger::critical,

Logger::error,

Logger::warning,

Logger::notice,

Logger::info,

Logger::debug

Registros con un nivel específico.

public Logger::emergency ( string $message, array $context = [] ): void

Menus

Recupera los datos necesarios para generar un menú, y los devuelve en un arreglo.

Menus::__construct

public Menus::__construct ( string $key ): self

key

Clave única que identifica a un menú.

Menus::read

El método se encarga de devolver un arreglo con los datos necesarios para generar un menú.

public Menus::read ( ): array

Menus::render

Devuelve una cadena html con el menú ya construido. El método depende de una vista, no funcionará sin ésta.

public Menus::render( ): string

MVC

El framework está diseñado siguiendo el patrón MVC (Modelo - Vista - Controlador).

Esta librería se encarga de tender las bases para la implementación de dicho patrón.

Controller

Todos los controladores de las aplicaciones deben extender esta clase. Aunque no siempre sea evidente, cuando el Router llama al controlador, ejecuta métodos de esta clase.

A su vez, el framework no tiene una clase dedicada a las vistas, sino que hay un método de esta clase, que realiza la tarea de incluir las vistas. Esto se debe a que el framework vincula un punto de entrada de un controlador con una vista, facilitando el desarrollo.

Controller::middleware

Agrega middlewares en la cola del Runner (ver El archivo Index).

public Controller::middleware( ...$middlewares ): bool

middlewares

La lista de middlewares a agregar.

Los middlewares pueden ser agregados en el constructor, lo que se ejutará en todos los puntos de entrada, de la siguiente manera:

use Junco\Mvc\Controller;

class ApiTestController extends Controller
{
	public function __construct()
	{
		$this->middleware('test');
	}
}

También, puede ser agregado en un punto de entrada en particular.

El mecanismo para hacerlo puede parecer extraño, pero debe entender que cualquier middleware debe ser ejecutado ANTES de ejecutar el punto de entrada, por lo tanto, la opción que nos queda para lograr esto es, ejecutar dos veces ese punto de entrada, uno para agregar los middleware en la cola y ejecutarlos, y otra para ejecutar el punto de entrada en sí.

Dicho esto, el código será:

use Junco\Mvc\Controller;

class ApiTestController extends Controller
{
	public function index()
	{
		if ($this->middleware('test')) {
			return true;
		}
		return '...';
	}
}

Si un punto de acceso devuelve true, eso significa que ha agregado middlewares y debe volver a ejecutar el ciclo de middlewares hasta llegar nuevamente al punto de acceso y volver a ejecutarlo, esta vez, para obtener una respuesta.

Controller::authenticate

Agrega el middleware de autenticación. Por su uso frecuente, se facilita su uso con un método propio.

public Controller::authenticate( int ...$label_id ): bool

label_id

La etiqueta con la que se limitarán los permisos de acceso. Ver la extensión users.

Controller::view

Incluye una vista. La vista será incluída dentro del método, por lo que, la variable $this, prodrá ser utilizada allí.

public Controller::view( string|callable $view = null, array $data = null )

view

La ruta a la vista a incluir, si no se completa, agregará la vista predeterminada por las convenciones.

data

Los datos que se le pasará a la vista.

Model

Según el patrón de arquitectura de MVC, el modelo se encarga de la lógica de negocio.

La clase Model contiene algunos métodos que ayudarán a ejecutar esa lógica de negocio. Sin embargo, a diferencia de otros frameworks, no incluye la conexión a la base de datos.

Actualmente, esta clase contiene únicamente métodos que permiten disponer de datos de entrada de manera segura.

Model::setData

Introduce datos que quedarán disponibles en el filtro.

final public Model::setData( array $data = null ): self

data

Un arreglo con los datos.

Model::filter

Filtra los datos externos al modelo. Note que es un método protegido, que se ejecuta dentro del modelo. Para conocer más, ver Filter.

final protected Model::filter( int $type, array $rules ): void

type

El lugar donde de donde tomará los datos, en el caso de que estos no sean introducidos. Puede ser GET o POST. 

rules

Las reglas de filtrado.

Model::setDataArray

Introduce datos múltiples, que quedarán disponibles en el filtro.

final public Model::setDataArray( array $data_array = null ): self

data_array

Un arreglo múltiple con los datos.

Model::filterArray

Filtra datos múltiples, externos al modelo. Note que es un método protegido, que se ejecuta dentro del modelo.

En el caso de que no pueda obtener al menos una fila, retornará false. Para conocer más, ver Filter.

final protected Model::filterArray( int $type, array $rules ): bool

type

El lugar donde de donde tomará los datos, en el caso de que estos no sean introducidos. Puede ser GET o POST.

rules

Las reglas de filtrado.

Model::extract

Extrae claves del arreglo data a una propiedad de igual nombre. Para ello, las propiedades deben estar previamente declaradas.

final protected Model::extract( ...$names ): void

names

Las claves a extraer del arreglo data.

Nestedset

La librería contiene un conjunto de herramientas para manipular arreglos del tipo árbol. Se utiliza en proyectos como menús, categorías, taxonomías, etc.

Nestedset::toNestedArrays

Convierte un arreglo del tipo lista, basado en filas y columnas (como los obtenidos en una base de datos), en uno multidimensional. Para ello, utiliza las columnas left_id y right_id.

Las porciones de arreglo anidadas, serán agregada con el índice edge. Paralelamente, en cada fila agrega el índice depth con un valor de profundidad, que comienza en 0.

Devuelve el arreglo con una estructura del tipo árbol.

public static Nestedset::toNestedArrays( array $rows ): array

Nestedset::toNestedArraysFromDepth

Realiza la misma operación que toNestedArrays, pero lo realiza a partir del índice depth.

public static Nestedset::toNestedArraysFromDepth( array $rows ): array

Nestedset::toList

Realiza la operación inversa a toNestedArrays. Es decir, convierte un arreglo con anidaciones, en uno del tipo lista.

Para realizar la tarea, busca los índices edge.

public static Nestedset::toList( array $rows ): array

public static Nestedset::toListWithUpDown( array $rows ): array

public static Nestedset::sort( array $rows, string $column_name = 'ordering' ): array

public static Nestedset::sortNestedArrays( array $rows, string $column_name = 'ordering' ): array

Pagination

Pagina registros de una base de datos o de un arreglo, también se encarga de la vista.

Ejemplo inicial

En el siguiente ejemplo, se extrae una porción de un arreglo que corresponde a una página actual y a un número de filas por páginas.

$pagi = new Pagination();
$pagi->cur_page      = 2;
$pagi->rows_per_page = 20;
$pagi->slice($rows);

Métodos

Pagination::slice

Extrae una porción de arreglo correspondiente a la página actual.

public Pagination::slice ( array $rows ): void

rows

El arreglo que se desea paginar. El arreglo paginado se devolverá con el método fetchAll.

Pagination::fetchAll

Devuelve un arreglo con el resultado de la paginación.

public Pagination::fetchAll( ): array

Pagination::url

Se utiliza para ingresar la url que luego, en un fragmento, será utilizada para generar los botones de paginación.

public Pagination::url ( string $route = '', array $args = [], $hash = ''): void

route

La ruta, igual que en Router::url.

args

Un arreglo con los parámetros de la queryString.

hash

Una cadena con el hash, incluido el símbolo # al comienzo.

Metodos para librerías

En general, los siguientes métodos solo deberían ser utilizados, internamente, por otras librerías. Por ejemplo, como lo hace Database.

Pagination::calculate()

Se encarga de calcular la paginación.

public Pagination::calculate(): void

Pagination::setRows

Ingresa el arreglo ya paginado.

public Pagination::setRows( array $rows ): void

Propiedades

Algunas de estas propiedades, deben ser configuradas. Otras, se calculan a partir de las primeras.

Pagination::$cur_page

La página actual. De no declararse, se buscará en la variable $_REQUEST.

Pagination::$rows_per_page

El número de filas por página. Por defecto es de 15.

Pagination::$num_rows

El número total de filas a paginar. Por lo general, este valor surge del tamaño del arreglo a paginar o de una consulta a la base de datos.

Pagination::$num_pages

El número total de páginas. Este valor es calculado internamente por la clase.

Pagination::$offset

Valor inicial a partir del cual se devolverán las filas ya paginadas.

Profiler

Recopila datos de una consulta en tiempo de ejecución. Es una herramienta para los desarrolladores que permite obtener información valiosa para la toma de desiciones y la depuración del código.

Ejemplo inicial

En el siguiente ejemplo, se pone a pruebas dos funciones, y se muestra los resultados.

$profiler = new Profiler();

// test 1
func1();
$profiler->mark();

// test 2
func2();
$profiler->mark();

// output
echo $profiler->render();

Profiler::__construct

Crea una instancia del perfilador. 

public Profiler::__construct( bool $from_outset = false )

from_outset

Toma como punto de inicio el comienzo de la ejecución. Para ello, utiliza la variable global $_SERVER['REQUEST_TIME_FLOAT'].

Profiler::mark

Guarda los datos al momento de la ejecución.

public Profiler::mark( string $label = '', ...$args )

label

Una etiqueta para, posteriormente, reconocer la marca.

...args

Valores de relleno de la etiqueta. Estos valores serán convertidos a una cadena, por ejemplo, un null será convertido en 'NULL'.

Internamente, utiliza la función vsprintf.

Profiler::render

Devuelve una cadena formateada con todos los datos obtenidos.

public Profiler::render( bool $full = false ): string

full

Renderiza también información de las extensiones Database y Router.

Router

Router::getAccessPoint

Retorna el punto de acceso actual.

public Router::getAccessPoint( ): string

Router::getAccessPoints

Devuelve todos los puntos de acceso disponibles.

public function routeWith ( string $uri, array $paramNames, string|array $callback, string $id = '' )

Router::getComponent

Devuelve el nombre del componente, o del subcomponente, actual.

public Router::getComponent( bool $full = false ): string

full

En caso de true, devolverá tambien el subcomponente.

Router::getTask

Devuelve la tarea actual.

public Router::getTask( ): string

Router::getFormat

Devuelve el formato actual.

public Router::getFormat( ): string

Router::isFormat

Verifica el formato actual.

public Router::isFormat( string $format ): bool

Router::getController

Devuelve el controlador actual. En caso de no hallarlo, devolverá false.

public Router::getController(): callable|false

Router::getControllerAsString

Devuelve el nombre del controlador actual.

public Router::getControllerAsString( ): string

Router::getRoute

Devuelve la ruta actual.

public Router::getRoute( ): string

Router::getArgsWithFormat

A un arreglo de argumentos, le agrega un formato. Se utiliza para indicar en una url de consulta, un formato de salida.

public Router::getArgsWithFormat( string $format, array $args = [] ): array

Router::getHash

Devuelve una cadena, basada en la ruta que se está ejecutando actualmente.

public Router::getHash( ): string

Generadores de Url

Router::getUrl

url

Crea una URL.

public Router::getUrl ( string $route = '', array  $args = [], bool   $absolute = false): string

/* Alias */
function url ( string $route = '', array  $args = [], bool   $absolute = false): string

route

La ruta al recurso. El formato debe ser: access_point/component/task. Todos los valores se deberían poder omitir.

args

Otros valores que se agregarán a la cadena de consulta.

absolute

Crea una URL absoluta en lugar de una relativa.

Router::getUrlForm

Cumple la misma función que Router::getUrl pero la salida está orientada a un formulario. Devuelve un array con dos valores:

• action: la acción para el formulario.
• hidden: elementos ocultos del formulario con los restantes valores a enviar.

public Router::getUrlForm ( string $route = '',  array $args = [], bool $absolute = false ): array

Router::absoluteUrl

Devuelve una url con su ruta absoluta.

public Router::absoluteUrl( string $url ): string

Router::redirect

redirect

Redirecciona la Url.

public Router::redirect ( $url = null, bool $absolute = true ): void

/* Alias */
redirect ( $url = null, bool $absolute = true ): void

url

La url a la cual será redirigida la página.

Los valores pueden ser:

1. Un array con los valores para construir la url con Router::getUrl.
2. El número 401 que redirige al Login.
3. El número 404 que redirige a una página de error.
4. Una cadena con la url.

absolute

Crea una URL absoluta en lugar de una relativa.

Routes

Routes::route

Registra una uri, la cual quedará asociada con la tarea de un controlador.

public Routes::route ( string $uri, string|array $callback, string $id = '' )

uri

La uri a registrar. La uri puede estar precedida por los métodos válidos.

callback

La función de retorno. Si es una cadena, será el nombre del método del controlador por defecto. Si es un array, será un callable.

id

Una Id con la cual identificar la uri.

Ejemplos

$routes->route('/articles', 'list', '#list');
$routes->route('/articles/{id:int}', 'show', '#show');
$routes->route('DELETE /articles/{id:int}', 'delete');

Routes::routeWith

La función es similar a Router::route, sólo que la uri será valida si además contiene los parámetros pasados en el arreglo $paramNames.

public Routes::routeWith ( string $uri, array $paramNames, string|array $callback, string $id = '' )

Session

Implementa las sesiones de PHP.

Entre las ventajas del uso de la librería, tenemos:

• El uso de las configuraciones;
• La verificación del navegador y de la IP del usuario;
• La destrucción segura de la sesión;
• La obtensión de un hash de seguridad.

Uso de una fachada

Se recomienda utilizar la fachada session().

Métodos

Session::get

Obtiene un valor de la sesión.

public Session::get( string $key ): mixed

key

La clave de la entrada a obtener.

Session::set

Guarda un valor en la sesión.

public Session::get( string $key, mixed $value = null ): void

key

La clave con la que se guardará la entrada.

value

El valor a guardar.

Session::unset

Elimina una entrada de la sesión. Retorna el valor de la entrada eliminada.

public Session::unset( string $key): mixed

key

La clave con la que se guardará la entrada.

Session::destroy

Destruye de modo seguro la sesión actual.

public Session::destroy( ): void

Session::getHash

Retorna un hash que representa a la sesión actual.

public Session::getHash( ): string

Session::getBrowser

Parsea un encabezado User-Agent. Devuelve un arreglo con información relevante.

public Session::getBrowser( string $user_agent = null ): array

user_agent

Un cadena con un formato de encabezado User-Agent. Por defecto, utilizará el encabezado de la consulta en ejecución.

Session::isSafeToContinue

Verifica que la sesión actual esté hecha con la misma ip y/o con el mismo navegador con el que fue inicilizada en su momento.

Para el caso del navegador, tiene en cuenta que la versión del mismo sea la misma o superior.

public Session::isSafeToContinue( ): bool

System

System::__construct

Inicializa el sistema. Actualmente, solo activa el buffer de salida ob_start, inicializa la codificación utf-8 y define el timezone.

public System::__construct( )

public System::isDemo( ): bool

Plugins

Incluye y ejecuta una o más funciones a pedido.

Plugins::get

Devuelve un objeto Plugins o null en caso de no hallar al menos una función para ejecutar.

static Plugins::get ( string $name, string $hook, string|array $plugins ): object 

Descripción y parámetros

Para el framework, un plugin es un archivo que devuelve una función. El plugin, una vez incluido, queda listo para ser ejecutado. Para incluir un plugin, deben definirse todos los parámetros, los que convinados darán una ruta de inclusión.

El nombre identifica al plugin de forma única para todo el framework. Dentro de un plugin puede haber muchas funciones, cada una de ellas será un gancho diferente. Por último, una extensión puede tener varias alternativas para el mismo nombre de plugin, por eso, una extentensión puede llamar a sus plugins de la siguiente manera:

{extension_alias}                // plugin por defecto
{extension_alias}.{alter_plugin} // plugin alternativo

La ruta de inclusión se define por:

cms/plugins/{extension_alias}/{plugin_name}/{alter_plugin}/{plugin_name}.{plugin_hook}.php

Plugins::run

Ejecuta las funciones listadas. El primer parámetro se llama por referencia y será el que las funciones podrán modificar. Opcionalmente, podrán pasarse otros parámetros.

Plugins::run ( mixed &$ref [, ...]): void

Ejemplo

$plugins = Plugins::get('plugin_name', 'plugin_hook', ['extension','extension.alter']);
$output  = $plugins?->run($output);

Plugin

Incluye y ejecuta una función a pedido. Funciona de manera similar a Plugins, solo que el resultado lo retorna, en lugar de modificar la variable referenciada.

Plugin::get

static Plugin::get ( string $name, string $hook, string $plugin ): object 

Plugins::run

Ejecuta el plugin. Esto dependerá de que exista el plugin y se haya obtenido.

public Plugins::run( [mixed ...] ): mixed

Ejemplo

$plugin = Plugin::get('plugin_name', 'plugin_hook', 'extension');
$output = $plugin?->run();

Snippets

Crea un objeto que renderiza el html.

Snippets::get,

snippet

Devuelve una clase para renderizar html. Si no encuentra el snippet pasado como argumento, devolverá uno por defecto o lanzará un error.

Se recomienda utilizar la fachada snippet().

static Snippets::get ( string $extension, string $snippet, [, ... $arg ] ): object 

Ejemplo

$snippet = snippet('extension', 'default');