Para interactuar con los datos de la base de datos, PIPE proporciona dos métodos para acceder a ellos, el primero es por medio de Modelos referenciados a las tablas de la base de datos, y el segundo es por medio del Constructor de Consultas PIPE.
Veamos algunos ejemplos.
Creación de un Modelo.
PIPE automáticamente importa los modelos que han sido ubicados en la ruta especificada por medio de la constante RUTA_MODELOS al inicializar la configuración.
Creamos el archivo Usuario.php y lo guardamos en la ruta que hemos especificado en la constante RUTA_MODELOS.
<?php
namespace Modelos;
use PIPE\Clases\Modelo;
class Usuario extends Modelo
{
// Todo tu código aquí.
}
En el Modelo podemos definir los campos que podrán ser insertables, actualizables, visibles y ocultos de la siguiente manera.
<?php
namespace Modelos;
use PIPE\Clases\Modelo;
class Usuario extends Modelo
{
public $insertables = ['nombres', 'apellidos', 'contrasena'];
public $actualizables = ['nombres', 'apellidos', 'contrasena'];
public $visibles = ['nombres', 'apellidos']; // Estos campos se mostrarán en la consulta SQL.
public $ocultos = ['contrasena']; // Este campo no se mostrará en la consulta SQL.
}
El Modelo permite modificar los datos antes de su creación y actualización, o después de su obtención, esto es posible por medio de Mutadores.
El nombre de los métodos mutadores deben ser creados con la siguiente convención: como prefijo, se debe iniciar con la palabra mutar, seguido del nombre del campo a modificar, ejemplo: nombres. Finalmente, se debe especificar la acción a realizar, asignar u obtener. Para este ejemplo, el nombre del método quedaría de la siguiente manera: mutarNombresAsignar o mutarNombresObtener.
Vamos a modificar el nombre del usuario antes de su creación en la base de datos.
<?php
namespace Modelos;
use PIPE\Clases\Modelo;
class Usuario extends Modelo
{
public function mutarNombresAsignar($nombres)
{
return ucfirst($nombres);
}
}
Vamos a modificar los campos del registro del tiempo por una instancia de la clase DateTime, después de su obtención en la base de datos.
<?php
namespace Modelos;
use DateTime;
use PIPE\Clases\Modelo;
class Usuario extends Modelo
{
public function mutarCreadoEnObtener($creadoEn)
{
return new DateTime($creadoEn);
}
public function mutarActualizadoEnObtener($actualizadoEn)
{
return new DateTime($actualizadoEn);
}
}
PIPE soporta 3 tipos de relaciones. Uno a Uno, Uno a Muchos y Muchos a Muchos.
#1 Relación Uno a Uno.
Vamos a relacionar el modelo Usuario con el modelo Documento, asumiendo que un usuario tiene un documento.
<?php
namespace Modelos;
use Modelos\Documento;
use PIPE\Clases\Modelo;
class Usuario extends Modelo
{
public $tieneUno = Documento::class;
}
Para obtener los datos de esta relación Uno a Uno, lo hacemos de la siguiente manera.
Nota: El método relacionar(), permite recibir múltiples parámetros correspondientes a los nombres de relaciones que tengamos definidas en el modelo.
<?php
$documento = Usuario::encontrar(1)
->relacionar('documentos')
->documentos;
PIPE por defecto determina el nombre de la relación en función del nombre de la tabla del modelo a relacionar. Podemos definir un nombre personalizado para nuestra relación de la siguiente manera.
<?php
public $tieneUno = [
Documento::class => [
'nombre' => 'documento_relacion'
]
...
];
// Obtenemos los datos de la relación de la siguiente manera.
$documento = Usuario::encontrar(1)
->relacionar('documento_relacion')
->documento_relacion;
PIPE por defecto determina la llave foránea en función del nombre del modelo a relacionar, debido a esto, se asume que la llave foránea del modelo Documento es usuario_id. Si deseamos omitir esta convención, podemos hacerlo de la siguiente manera.
<?php
public $tieneUno = [
Documento::class => [
'llaveForanea' => 'id_usuario'
]
...
];
PIPE por defecto determina que el valor de la llave foránea en el modelo Documento coincida con el valor de la llave primaria en el modelo Usuario, sin embargo, podemos definir una llave personalizada en el modelo Usuario de la siguiente manera.
<?php
public $tieneUno = [
Documento::class => [
'llavePrincipal' => 'idusuario'
]
...
];
#2 Relación Uno a Muchos.
Vamos a relacionar el modelo Usuario con el modelo Tema, asumiendo que un usuario tiene muchos temas.
<?php
namespace Modelos;
use Modelos\Tema;
use PIPE\Clases\Modelo;
class Usuario extends Modelo
{
public $tieneMuchos = Tema::class;
}
Para obtener los datos de esta relación Uno a Muchos, lo hacemos de la siguiente manera.
<?php
$temas = Usuario::encontrar(1)
->relacionar('temas')
->temas;
Como vimos anteriormente, PIPE por defecto determina el nombre de la relación en función del nombre de la tabla del modelo a relacionar. Podemos definir un nombre personalizado para nuestra relación de la siguiente manera.
<?php
public $tieneMuchos = [
Tema::class => [
'nombre' => 'temas_relacion'
]
...
];
// Obtenemos los datos de la relación de la siguiente manera.
$temas = Usuario::encontrar(1)
->relacionar('temas_relacion')
->temas_relacion;
Como vimos anteriormente, PIPE por defecto determina la llave foránea en función del nombre del modelo a relacionar, debido a esto, se asume que la llave foránea del modelo Tema es usuario_id. Si deseamos omitir esta convención podemos hacerlo de la siguiente manera.
<?php
public $tieneMuchos = [
Tema::class => [
'llaveForanea' => 'id_usuario'
]
...
];
Como vimos anteriormente, PIPE por defecto determina que el valor de la llave foránea en el modelo Tema coincida con el valor de la llave primaria en el modelo Usuario, sin embargo, podemos definir una llave personalizada en el modelo Usuario de la siguiente manera.
<?php
public $tieneMuchos = [
Tema::class => [
'llavePrincipal' => 'idusuario'
]
...
];
Relación inversa de Uno a Uno y Uno a Muchos.
Podemos acceder a los datos relacionados en los modelos Documento y Tema usando el atributo perteneceAUno.
<?php
public $perteneceAUno = Usuario::class;
Para obtener los datos de esta relación inversa de Uno a Uno y Uno a Muchos lo hacemos de la siguiente manera.
<?php
$usuario = Documento::encontrar(1)->relacionar('usuarios')->usuarios;
$usuario = Tema::encontrar(1)->relacionar('usuarios')->usuarios;
Nota: El atributo perteneceAUno también permite definir el nombre de relación personalizado.
PIPE por defecto determina la llave foránea en función del nombre del modelo a relacionar, debido a esto, se asume que la llave foránea de los modelos Documento y Tema son usuario_id. Si deseamos omitir esta convención, podemos hacerlo de la siguiente manera.
<?php
public $perteneceAUno = [
Usuario::class => [
'llaveForanea' => 'id_usuario'
]
...
];
PIPE por defecto determina que el valor de la llave foránea en los modelos Documento y Tema coincida con el valor de la llave primaria en el modelo Usuario, sin embargo, podemos definir una llave personalizada en el modelo Usuario de la siguiente manera.
<?php
public $perteneceAUno = [
Usuario::class => [
'llavePrincipal' => 'idusuario'
]
...
];
#3 Relación Muchos a Muchos.
Para definir la relación de Muchos a Muchos se necesitan tres tablas. Para nuestro ejemplo vamos a utilizar la tabla usuarios, roles y role_usuario.
Vamos a relacionar el modelo Usuario con el modelo Role en una relación de Muchos a Muchos, asumiendo que un usuario tiene muchos roles y un rol pertenece a muchos usuarios.
<?php
namespace Modelos;
use Modelos\Role;
use PIPE\Clases\Modelo;
class Usuario extends Modelo
{
public $perteneceAMuchos = Role::class;
}
Para obtener los datos de esta relación Muchos a Muchos lo hacemos de la siguiente manera.
<?php
$roles = Usuario::encontrar(1)->relacionar('role_usuario')->role_usuario;
Nota: El atributo perteneceAMuchos también permite definir el nombre de relación personalizado.
PIPE por defecto determina que el nombre de la tercera tabla (tabla de unión) este compuesto por los nombres en orden alfabético de los modelos relacionados, debido a esto, se asume que el nombre de la tercera tabla sea role_usuario. Si deseamos omitir esta convención, podemos hacerlo de la siguiente manera.
<?php
public $perteneceAMuchos = [
Role::class => [
'tablaUnion' => 'usuarios_roles'
]
...
];
PIPE por defecto determina que los nombres de las llaves foráneas en la tabla role_usuario (tabla de unión) sean role_id y usuario_id. Si deseamos omitir esta convención, podemos hacerlo de la siguiente manera.
<?php
public $perteneceAMuchos = [
Role::class => [
'llaveForaneaLocal' => 'id_usuario',
'llaveForaneaUnion' => 'id_role'
]
...
];
De la misma manera, podemos omitir estas convenciones para la relación inversa de Muchos a Muchos en el modelo Role.
<?php
public $perteneceAMuchos = [
Usuario::class => [
'tablaUnion' => 'usuarios_roles',
'llaveForaneaLocal' => 'id_role',
'llaveForaneaUnion' => 'id_usuario'
]
...
];
El Modelo y el Constructor de Consultas PIPE nos permiten estructurar sentencias SQL por medio de métodos.
A continuación, se muestra un listado de los 4 métodos disponibles únicamente en el Modelo para estructurar sentencias SQL.
| Método | Descripción |
|---|---|
| crear() | Crea uno o múltiples registros en la base de datos y retorna las instancias de los registros insertados. |
| destruir() | Destruye uno y múltiples registros en la base de datos y retorna las instancias de los registros destruidos. |
| editar() | Edita uno múltiples registros en la base de datos y retorna las instancias de los registros editados. |
| relaciones() | Establece los datos relacionados a un modelo que se obtendrán junto a los resultados de la consulta SQL. |
A continuación, se muestra un listado de los 7 métodos disponibles únicamente en el Constructor de Consultas PIPE para estructurar sentencias SQL.
| Método | Descripción |
|---|---|
| conexion() | Establece la conexión según el nombre definido. |
| consulta() | Realiza una consulta SQL en español. |
| consultaNativa() | Realiza una consulta SQL nativa. |
| obtenerPDO() | Obtiene la instancia de PDO. |
| sentencia() | Realiza una sentencia SQL en español. |
| sentenciaNativa() | Realiza una sentencia SQL nativa. |
| tabla() | Establece el nombre de la tabla en el Constructor de Consultas. |
A continuación, se muestra un listado de los 32 métodos disponibles en el Modelo y el Constructor de Consultas PIPE para estructurar sentencias SQL.
| Método | Descripción |
|---|---|
| actualizar() | Actualiza un registro en la base de datos. |
| actualizarOInsertar() | Actualiza o inserta un nuevo registro en la base de datos. |
| agruparPor() | Agrupa registros que tienen los mismos valores. |
| alias() | Establece un alias al nombre de la tabla. |
| contar() | Obtiene la cantidad general o especifica de registros retornados. |
| decrementar() | Decrementa el valor del campo especificado. |
| distinto() | Elimina duplicados del conjunto de resultados. |
| donde() | Establece una condición en la consulta SQL. |
| eliminar() | Elimina un registro en la base de datos. |
| encontrar() | Obtiene una instancia del Constructor de Consultas con los datos asociados a la llave primaria. |
| existe() | Verifica que la consulta SQL ha retornado un resultado. |
| incrementar() | Incrementa el valor del campo especificado. |
| insertar() | Inserta un nuevo registro en la base de datos. |
| insertarObtenerId() | Inserta un nuevo registro en la base de datos y obtiene el último id generado. |
| limite() | Limita el número de registros retornados en la consulta SQL. |
| maximo() | Obtiene el valor máximo del campo especificado. |
| minimo() | Obtiene el valor mínino del campo especificado. |
| noExiste() | Verifica que la consulta SQL no ha retornado un resultado. |
| obtener() | Obtiene el resultado de una consulta SQL. |
| ordenarPor() | Ordena el resultado de la consulta SQL. |
| primero() | Obtiene los primeros registros retornados en la consulta SQL. |
| promedio() | Obtiene el valor promedio del campo especificado. |
| relacionar() | Establece los datos relacionados a un modelo. |
| seleccionar() | Establece los campos que serán seleccionados. |
| suma() | Obtiene la suma del campo especificado. |
| teniendo() | Establece una condición a una función de agregación. |
| todo() | Obtiene todos los datos de la tabla seleccionada. |
| ultimo() | Obtiene los últimos registros retornados en la consulta SQL. |
| unir() | Combina registros de una o más tablas relacionadas. |
| unirDerecha() | Combina registros de una o más tablas relacionadas obteniendo todos los registros de la tabla de la derecha. |
| unirIzquierda() | Combina registros de una o más tablas relacionadas obteniendo todos los registros de la tabla de la izquierda. |
| vaciar() | Elimina todos los registros en la tabla y reinicia el contador auto incrementable. |
La clase PIPE, proporciona constantes que permiten obtener información del ORM PIPE.
A continuación, se muestra un listado de las 7 constantes disponibles en la clase PIPE.
| Constante | Descripción |
|---|---|
| PIPE::ARREGLO | Indica el retorno de resultados de una consulta SQL como un arreglo. |
| PIPE::AUTOR | Indica el autor del ORM PIPE. |
| PIPE::CLASE | Indica el retorno de resultados de una consulta SQL como una clase. |
| PIPE::JSON | Indica el retorno de resultados de una consulta SQL como una cadena de json. |
| PIPE::OBJETO | Indica el retorno de resultados de una consulta SQL como un objeto. |
| PIPE::SQL | Indica el retorno de la consulta SQL generada. |
| PIPE::VERSION | Indica la versión actual del ORM PIPE. |
Si utilizas el Modelo para interactuar con los datos de la base de datos, tendrás la ventaja de poder omitir las convenciones que tiene el ORM PIPE y adaptarse a la estructura que tenga tu tabla en la base de datos, ya que el Constructor de Consultas se adapta por defecto a las convenciones.