Modelos y Constructor de Consultas
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.
En el Modelo podemos definir los campos que podrán ser insertables, actualizables, visibles y ocultos de la siguiente manera.
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.
Los 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.
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.
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.
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.
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.
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.
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.
#2 Relación Uno a Muchos.
Vamos a relacionar el modelo Usuario con el modelo Tema, asumiendo que un usuario tiene muchos temas.
Para obtener los datos de esta relación Uno a Muchos, lo hacemos de la siguiente manera.
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.
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.
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.
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.
Para obtener los datos de esta relación inversa de Uno a Uno y Uno a Muchos lo hacemos de la siguiente manera.
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.
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.
#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.
Para obtener los datos de esta relación Muchos a Muchos lo hacemos de la siguiente manera.
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) esté 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.
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.
De la misma manera, podemos omitir estas convenciones para la relación inversa de Muchos a Muchos en el modelo Role.
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 21 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. |
| obtenerActualizables | Obtiene los campos del modelo que pueden ser modificados mediante actualización. |
| obtenerActualizadoEn | Obtiene el nombre del campo establecido para el registro del tiempo de actualización. |
| obtenerConexion | Obtiene la conexión activa a la base de datos utilizada por el modelo. |
| obtenerCreadoEn | Obtiene el nombre del campo establecido para el registro del tiempo de creación. |
| obtenerEliminacionSuave | Obtiene un booleano indicando si el modelo está habilitado para eliminación suave. |
| obtenerEliminadoEn | Obtiene el nombre del campo establecido para el registro del tiempo de eliminación. |
| obtenerInsertables | Obtiene los campos del modelo que pueden ser modificados mediante inserción. |
| obtenerLlavePrimaria | Obtiene el nombre del campo de la llave primaria. |
| obtenerOcultos | Obtiene los campos del modelo que no se deben exponer en la obtención de registros. |
| obtenerPerteneceAMuchos | Obtiene la relación perteneceAMuchos relacionada al modelo. |
| obtenerPerteneceAUno | Obtiene la relación perteneceAUno relacionada al modelo. |
| obtenerPropiedadesModelo | Obtiene las propiedades definidas en el modelo. |
| obtenerRegistroTiempo | Obtiene un booleano indicando si el modelo está habilitado para el registro del tiempo. |
| obtenerTabla | Obtiene el nombre de la tabla de la base de datos relacionada al modelo. |
| obtenerTieneMuchos | Obtiene la relación tieneMuchos relacionada al modelo. |
| obtenerTieneUno | Obtiene la relación tieneUno relacionada al modelo. |
| obtenerVisibles | Obtiene los campos del modelo que se pueden exponer en la obtención de registros. |
| 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 10 métodos disponibles únicamente en el Constructor de Consultas PIPE para estructurar sentencias SQL.
| Método | Descripción |
|---|---|
| confirmar | Confirma una transacción SQL. |
| consulta | Realiza una consulta SQL en español. |
| consultaNativa | Realiza una consulta SQL nativa. |
| iniciarTransaccion | Inicia una transacción SQL. |
| obtenerPDO | Obtiene la instancia de PDO. |
| revertir | Revierte una transacción SQL. |
| 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. |
| transaccion | Procesa SQL de forma transaccional. |
A continuación, se muestra un listado de los 53 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. |
| conexion | Establece la conexión según el nombre definido. |
| 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 con cláusula where y operador and en la consulta SQL. |
| dondeColumna | Establece una condición con cláusula where y operador and en la consulta SQL. |
| dondeCrudo | Establece una condición personalizada con cláusula where en la consulta SQL. |
| dondeEn | Establece una condición con cláusula where y operador and in en la consulta SQL. |
| dondeEntre | Establece una condición con cláusula where y operador and between en la consulta SQL. |
| dondeNo | Establece una condición con cláusula where y operador and not en la consulta SQL. |
| dondeNoEn | Establece una condición con cláusula where y operador and not in en la consulta SQL. |
| dondeNoEntre | Establece una condición con cláusula where y operador and not between en la consulta SQL. |
| dondeNoNulo | Establece una condición con cláusula where y operador and not null en la consulta SQL. |
| dondeNulo | Establece una condición con cláusula where y operador and null 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. |
| extraer | Extrae el valor de la clave seleccionada. |
| 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. |
| oDonde | Establece una condición con cláusula where y operador or en la consulta SQL. |
| oDondeColumna | Establece una condición con cláusula where y operador or en la consulta SQL. |
| oDondeEn | Establece una condición con cláusula where y operador or in en la consulta SQL. |
| oDondeEntre | Establece una condición con cláusula where y operador or between en la consulta SQL. |
| oDondeNo | Establece una condición con cláusula where y operador or not en la consulta SQL. |
| oDondeNoEn | Establece una condición con cláusula where y operador or not in en la consulta SQL. |
| oDondeNoEntre | Establece una condición con cláusula where y operador or not between en la consulta SQL. |
| oDondeNoNulo | Establece una condición con cláusula where y operador or not null en la consulta SQL. |
| oDondeNulo | Establece una condición con cláusula where y operador or null en la consulta SQL. |
| obtener | Obtiene el resultado de una consulta SQL. |
| obtenerClave | Obtiene los datos asignando una o varias claves personalizadas. |
| 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.