Modelos

Los objetos de modelo son la representación de un registro de una base de datos como un objeto PHP.

El Framework ofrece una clase llamada OModel que permite mapear el diseño de una tabla de una base de datos a un objeto, de modo que permite obtener un único registro como una variable.

Los archivos de modelo son archivos PHP ubicados en la carpeta app/model en el que cada archivo tiene el nombre de la tabla a la que representa y su contenido es este, por ejemplo:


<?php declare(strict_types=1);

namespace OsumiFramework\App\Model;

use OsumiFramework\OFW\DB\OModel;

class Tag extends OModel {
	/**
	 * Configures current model object based on data-base table structure
	 */
	function __construct() {
		$table_name  = 'tag';
		$model = [
			'id' => [
				'type'    => OModel::PK,
				'comment' => 'Unique Id for each tag'
			],
			'name' => [
				'type'     => OModel::TEXT,
				'size'     => 20,
				'nullable' => false,
				'comment'  => 'Tag name'
			],
			'id_user' => [
				'type'     => OModel::NUM,
				'nullable' => true,
				'default'  => null,
				'comment'  => 'User Id',
				'ref'      => 'user.id'
			],
			'created_at' => [
				'type'    => OModel::CREATED,
				'comment' => 'Register creation date'
			],
			'updated_at' => [
				'type'    => OModel::UPDATED,
				'comment' => 'Last date register was modified'
			]
		];

		parent::load($table_name, $model);
	}

	/**
	 * Get tag's name
	 */
	public function __toString() {
		return $this->get('name');
	}
}

El archivo contiene una clase con el nombre de la tabla que representa y hereda de la clase OModel.

En su interior, la función __construct tiene dos variables:

$table_name: El nombre de la tabla a la que representa.
$model: El diseño de la tabla.

Con estas dos variables se llama a la función load ofrecida por OModel que se encarga de inicializar el objeto.

Esta clase puede tener tantas funciones auxiliares como se necesiten, en el ejemplo se ha incluido __toString, de modo que si se intenta usar una variable creada con esta clase, se devolverá el nombre de la etiqueta a la que representa.

Definición del modelo

La variable $model es un array donde cada elemento corresponde a una columna de la tabla. Es un array relacional donde el nombre del elemento representa el nombre de la columna y el valor es un array con propiedades que definen sus características.

Para definir una columna se usan las siguientes opciones:

Campo	Valor por defecto	Explicación del campo
type	(no tiene)	Este es el único campo obligatorio. Las opciones son las siguientes: `OModel::PK`: Clave primaria de tipo numérico. `OModel::PK_STR`: Clave primaria de tipo texto. `OModel::CREATED`: Campo de tipo DATETIME que se rellena automáticamente con la fecha de creación del registro. `OModel::UPDATED`: Campo de tipo DATETIME que se rellena automáticamente con la fecha de la última modificación del registro. `OModel::NUM`: Campo de tipo INT, un número entero. `OModel::FLOAT`: Campo de tipo FLOAT, un número que admite decimales. `OModel::TEXT`: Campo de tipo VARCHAR, un texto. Admite un tamaño máximo de 255 caracteres, se define con el campo `size` `OModel::LONGTEXT`: Campo de tipo TEXT, un texto largo. Admite un tamaño máximo de 65.535 caracteres. `OModel::DATE`: Campo de tipo DATETIME, para almacenar fechas y horas. `OModel::BOOL`: Campo de tipo booleano para valores verdadero/falso. En la base de datos se representa como un TINYINT de valores 0/1. Es obligatorio tener un campo de tipo `CREATED` y un campo de tipo `UPDATED`. Se pueden indicar tantas claves primarias como se necesite.
comment	(no tiene)	Este campo no es obligatorio. Sirve como ayuda para explicar en que consiste el campo. Al usar la tarea `generateModel`, el contenido de este campo se asignará como comentario a la columna de la base de datos.
nullable	false	Indica si el valor del campo puede ser `NULL`. En caso de querer guardar un valor `NULL` y este campo esté a `true`, producirá un error.
default	(no tiene)	Valor por defecto para el campo en caso de que no se use. En el ejemplo, si se crea una nueva `Tag`, pero no se indica su `id_user`, por defecto se guardará el valor `NULL` indicado aquí.
size	(no tiene)	Tamaño máximo de caracteres para campos de tipo texto. En caso de querer guardar una cadena de texto con un tamaño superior al aquí indicado, se cortará tras el número de caracteres marcado.
ref	(no tiene)	Referencia a otro campo de otro modelo/tabla. La sintaxis es "tabla.campo", por ejemplo "user.id" para referirnos a la tabla "user" y dentro de esta, al campo "id". Sirve para crear claves de tipo FOREIGN KEY al crear la base de datos.

Métodos de los modelos

Las clases de modelo al heredar de la clase OModel tienen una serie de métodos que permiten crear, modificar o borrar estos registros.

Estos son los métodos disponibles:

Método	Parámetros	Explicación del método
load	`$table_name (string)` Nombre de la tabla a la que hace referencia el modelo. `$model (array)` Definición de la tabla usando los campos antes descritos.	Este método solo se utiliza en la inicialización de una clase de modelo. Sirve para definir la tabla a la que hace referencia y los campos que tiene cada registro. Ambos parámetros son obligatorios.
getModel	`$key (string)` Nombre del campo.	Este método obtiene la definición que se ha hecho de un campo concreto, los datos definidos para un campo al llamar a la función `load`. Por ejemplo: `$name_definition = $tag->getModel('name');`
set	`$key (string)` Nombre del campo. `$value (mixto)` Valor del campo.	Función para asignar un valor a una columna de un registro. Por ejemplo: `$tag->set('name', 'Nombre de la tag');`
get	`$key (string)` Nombre del campo. `$extra (string \| int)` Opcional, modifica el valor devuelto.	Obtiene el valor de un campo concreto. Por ejemplo: `$tag_name = $tag->get('name');` El segundo parámetro `$extra` modifica el resultado de obtener el valor, sirve para campos de tipo texto o para fechas. En el caso de un texto, si se pasa como segundo parámetro un número, el resultado se cortará tras ese número de caracteres. Por ejemplo: $name = $tag->get('name'); // Devuelve 'Nombre de la tag' $name = $tag->get('name', 4); // Devuelve 'Nomb' En el caso de los campos de tipo fecha, si se omite el segundo parámetro se obtiene la fecha con el formato nativo de la base de datos usada. Si se indica un patrón (como el pasado a la función date de PHP), el resultado se formatea: $date = $tag->get('created_at'); // Devuelve '2022-01-14 23:12:59' $date = $tag->get('created_at', 'd/m/Y'); // Devuelve '14/01/2022'
getPks	(no tiene)	Obtiene un array con los nombre de los campos que componen la clave primaria. Por ejemplo: $pks = $tag->getPks(); // Devuelve ['id']
save	(no tiene)	Guarda el objeto de modelo en la base de datos. En el caso de ser un objeto nuevo, se ejecuta el comando `INSERT` correspondiente mediante una `prepared statement`. En el caso de ser una modificación, se ejecutará el comando `UPDATE` que actualizará solo los campos que se hayan modificado. Al guardar un registro, si se trata de un nuevo campo, automáticamente se guardará la fecha actual en el campo `created_at`. Si se trata de una actualización, la fecha actual se guardará en el campo `updated_at`. De este modo es posible saber exactamente cuando se creó un registro y cuando fue modificado por última vez.
find	`$opt (array)` Registro a buscar.	Sirve para buscar un registro concreto por uno o más campos. Hay que pasar por parámetro un array de pares clave/valor que compondrán la consulta a realizar. Devuelve `true` o `false` con el resultado de la busqueda. En caso de ser exitosa la búsqueda, el objeto usado para realizar la busqueda se actualizará con los valores del resultado. Por ejemplo: $tag = new Tag(); // Nuevo objeto en blanco if ($tag->find(['id' => 1])) { // Buscamos tag cuyo campo 'id' sea 1 $name = $tag->get('name'); // Devuelve 'Nombre de la tag', ya que al ser una búsqueda exitosa el objeto se ha actualizado con los valores del resultado }
update	`$res (array)` Array con pares clave/valor	Esta función permite actualizar un objeto de modelo a partir de un array de pares clave/valor. Pasándole un array cuyas claves sean los nombre de los campos, se actualizará el objeto. Por ejemplo: $data = [ 'id' => 1, 'name' => 'Nombre de la tag', 'id_user' => 123, 'created_at' => '2022-01-14 23:12:59', 'updated_at' => '2022-01-15 12:08:36' ]; $tag = new Tag(); // Nuevo objeto en blanco $tag->update($data); // Actualizo el objeto con los datos del array $name = $tag->get('name'); // Devuelve 'Nombre de la tag'
delete	(no tiene)	Borra el registro de la base de datos asociado al objeto de modelo.
generate	`$type (string)` Tipo: sql, json, array. `$exclude (array)` Campos a excluir del resultado. `$empty (array)` Campos a devolver vacíos.	Este método devuelve una representación del modelo. Tiene tres opciones: `sql`: Devuelve el código SQL necesario para generar la tabla a partir de los campos definidos. `json`: Devuelve el objeto de modelo cargado actualmente como un objeto JSON, pares clave/valor. `array`: Devuelve el objeto de modelo cargado actualmente como un array nativo de PHP, pares clave/valor. Los parametros `$exclude` y `$empty` sirven para los tipos `json` y `array`. En el caso de incluir nombres de campos en el array `$exclude`, estos no aparecerán en el resultado obtenido. Por el contrario, en el caso de incluir nombres de campos en el array `$empty`, estos campos si que se devolverán en el resultado, pero su valor estará vacío.
generateRefs	(no tiene)	Devuelve el código SQL necesario para generar las claves `FOREIGN KEY` del modelo.
cleanValue	`$value (string \| int)` Valor a limpiar.	Devuelve el valor que se le pase sanitizado: `Valor NULL`: Devuelve "null" como cadena de texto. `Número`: Devuelve el valor directamente ya que es un valor "seguro". `Texto`: Devuelve los saltos de línea como un carácter "\n", las comillas como comillas escapadas (" -> \") y el resultado entre comillas dobles.
__toString	(no tiene)	Si se intenta mostrar un objeto de modelo como un string, se devuelve su representación como `JSON`, con los valores sanitizados. En el caso de que se defina una función `__toString` personalizada en la clase, tendrá prioridad sobre el método por defecto.

Modulos DTO