Logo de islavisual
Isotipo de islavisual IslaVisual
imagen de sección

Ultima revisión 14/11/2012

Clase de PHP para MySQL de Islavisual

Hace tiempo que estoy desarrollando sistemas web para todo tipo de clientes y, cada vez más, dispongo de menos tiempo para hacer todo lo que necito. Además, ahora con el auge que han tenido las metodologías ágiles, todavía se vuelve aún más necesario disponer de "herramientas" para acelerar los diseños o desarrollos.

Hoy os voy a presentar la clase que yo habitualmente uso para manejar, desde PHP, las conexiones con las BBDD con MySQL.

Con esta sencilla pero completa clase de PHP podéis desde realizar consultas simples como adquirir un único valor, hasta exportar la BBDD a un archivo de texto comprimido o sin comprimir con varias ventajas añadidas como por ejemplo, que en todo momento, podemos conocer el número de filas o tuplas seleccionadas, borradas o actualizadas y el tiempo de ejecución de la consulta y, todo ello, con instrucciones muy simples.

Descarga

la podéis descargar pinchando en el siguiente enlace: mySql.class.1.0b

Instalación y Uso

Primero, descomprimir los archivos en tu carpeta favorita.

Por último, copiamos los archivos PHP la carpeta dónde se quiera tener y para usarla incluir las siguientes 2 instrucciones, cambiando la ruta por la legida y el nombre de la variable si así se desea.

include "clases/MySQL/mySql.class.php" ;
$mysql = new mySQL;

Luego ya es cuestión de realizar las llamadas a las funciones que se quieran usar como una clase de PHP cualquiera. Por ejemplo:

$mysql->connect();

Variables de Conexión

Lo primero de todo es configurar el usuario, contraseña y base de datos asociada a la clase. La clase puede manejar automáticamente los entornos de desarrollo y producción únicamente cambiando los valores de las siguientes constantes:

IdentificadorTipoExplicación
Constante El nombre de la base de datos de desarrollo.
Constante El nombre usuario a utilizar en el entorno de desarrollo.
Constante La contaseña asociada al usuario referenciado por _USER_DEVELOPMENT.
Constante El nombre de la base de datos de producción.
Constante El nombre usuario a utilizar en el entorno de producción.
Constante La contaseña asociada al usuario referenciado por _USER_PRODUCTION.

Variables para gestión de TOKENS.

IdentificadorTipoExplicación
Constante Es una función o contante que toma para crear un token único. Por defecto contiene 'date("Y-m-d H:i:s", $_SERVER["REQUEST_TIME"]);'.
Variable Contiene el útimo token generado.

Variables para la gestión del LOG.

La clase puede controlar los eventos automáticamente sobre todo lo que ocurre en la base de datos. Las variables en relación con el LOG de eventos son:

IdentificadorTipoExplicación
Variable Si está TRUE se guarda en la base de datos una entrada de log que cada página a la que se acceda en la que se guardan, entre otros, los campos fecha, nombre del navegador y versión, sistema operativo utilizado, ip, página desde dónde se ha hecho la llamada y el evento. Si es FALSE, no hace nada. Por defecto está a true;
Variable Indica si hay que crear la tabla automáticamente en la base de datos en el momento de la llamada o ejecución, si ésta, no fue creada con anterioridad. Por defecto está establecida a true.
Variable Es el nombre de la tabla que se quiere asociar al LOG.
Variable Tamaño del LOG en días. Si se establece a CERO se entiende que no se quiere eliminar ninguna entrada del log. Por defecto es 30 días.
Variable Si está establecido a TRUE, se guardan todas las consultas que envíen a MySQL automáticamente. Si es FALSE, sólo guarda los eventos que se soliciten directamente a través de la función insertEntryLog(...). Por defecto está a false.
Variable Es la declaración para crear la tabla de Log's. No se recomienda modificar.

Variables generales.

IdentificadorTipoExplicación
Variable Lista de Nº de error de MySQL separados por coma que se manejarán de manera especial. Para manejar los errores consultar la página http://dev.mysql.com/doc/refman/5.0/es/error-handling.html. Por defecto sólo ignora el Error 1062 (DUPLICATE ENTRY).
Variable Color de los errores de tipo WARNING. Por defecto es 'orange'.
Variable Color de los errores de tipo ERROR. Por defecto es 'red'.
Variable Si esta establecida a TRUE se muestran los mensajes WARNING. Por defecto está true.
Variable Si está a FALSE No se mostrarán los mensajes ignorados. Si está establecido a TRUE se mostrarán por pantalla al igual que los demás. Por defecto está a false.
Variable Si esta establecida a TRUE se muestran los mensajes de ERROR. Por defecto está establecida a true.
Variable Para la ejecución de la página si está establecida a TRUE. Por defecto está a false.
Constante Es Separador para la ejecución de múltiples sentencias. Si, en un momento dado, queremos ejecutar varios INSERT o varios UPDATE, podemos reunirlos todos en una variable de tipo string anidándolas por el contenido de esta variable y, cuando se llame a la función que ejecuta las instrucciones, se separarán y ejecutarán una a una. Por defecto está establecido a ";\n".
Variable Es el formato de fecha que tiene configurada la BBDD cuando tiene hora asignada. Se configura con los mismos parámetros de la instrucción date() de PHP. Por defecto configurada a FORMATO AMERICANO "Y-m-d H:i:s" que se correspondería, por ejemplo, con 1970-01-01 01:00:00.
Variable Es el formato de fecha que tiene configurada la BBDD sin horas. Se configura con los mismos parámetros de la instrucción date() de PHP. Por defecto configurada a FORMATO AMERICANO "Y-m-d" que se correspondería, por ejemplo, con 1970-01-01.
Variable Es el formato de fecha que se quiere por defecto en el framework o clase cuando tiene hora asignada. Se configura con los mismos parámetros de la instrucción date() de PHP. Por defecto configurada a FORMATO ESPAÑOL "d-m-Y H:i:s" que se correspondería, por ejemplo, con 31-12-1970 00:00:00..
Variable Es el formato de fecha que se quiere por defecto en el framework o clase sin horas. Se configura con los mismos parámetros de la instrucción date() de PHP. Por defecto configurada a FORMATO ESPAÑOL "d-m-Y" que se correspondería, por ejemplo, con 1970-01-01.
Variable Si la query no da ningún resultado se devolverá el valor establecido por esta variable. Normamente será NULL o "". Por defecto está establecido a "" (vacío).
Variable Si está establecida a TRUE los resultados extraidos de MySQL se analizarán intentando detectar si son UTF8 y si no lo son, se convertirán. Si está establecida a FALSE no no hace nada. Por defecto está establecida a true.

Variables de Control

Una vez ya configuradas las variables de la clase podemos consultar varias cosas que se realizan intrinseca e independientemente a todo lo demás. Son por ejemplo, el número de filas seleccionadas, afectadas o el tiempo de ejecución de la consulta. Por ello, las siguientes variables SÓLO pueden ser consultadas en tiempo de ejecución:

IdentificadorTipoExplicación
Variable Es el número de filas o tuplas seleccionadas para un select dado.
Variable Es el número de filas o tuplas afectadas que producen las instrucciones UPDATE, INSERT o DELETE. Si se solicita ejecutar varias instrucciones devuelve el número total de afectados en su conjunto, no de la última instrucción que se ejecutó, como hace PHP.
Variable Es el último ID insertado en la base de datos.
Variable Contiene la última query que se ejecutó.
Variable Contiene el último código de error que dió MySQL. Va asociado a $last_error_msg.
Variable Contiene el último mensaje de error que dió MySQL. Va asociado a $last_error_id.
Variable Guarda el tiempo en milisegundos transcurrido en la ejecución de la query o queries.
Variable Es para el uso de $completedIn. Guarda la hora de inicio (en milisegundos) de la ejecución de la query o queries.
Variable Es para el uso de $completedIn. Guardan la hora de finalización (en milisegundos) de la ejecución de la query o queries

Listado de Funciones

Ahora paso a listar las funciones disponibles en la clase, la cual, puede que vaya aumentando con el tiempo ya que continúo desarrollando nuevas funcionalidades.

FunciónExplicación
Función para codificar o crear Tokens. Se basa en la constante _TOKEN_KEY para codificar la cadena enviada.

Ejemplo: 
$mysql->encodeToken("Éxito. SELECT * FROM blog_tags WHERE 1;");
Función para decodificar Tokens.

Ejemplo: 
$mysql->decodeToken("jHd8dnWBUVtNd4Nvf1CcnKKhlKTlJsgn1GflpKMm6qblJRamKigUBqqlqWgTQ==");
Función que compara el Token enviado por $token con el Token creado a partir de $string.

Se basa en la constante _TOKEN_KEY para codificar la cadena enviada.

Devuelve true si son iguales. En cualquier otro caso devuelve false.

Ejemplo: 
$mysql->checkToken("Esto es una prueba", "6qblJRamKigUBqqlqWgTQ==");
Función que compara 2 Tokens.

SI $token2 es vacío toma para comparar el devuelto por la variable _ENCODED_TOKEN.

Devuelve true si son iguales. En cualquier otro caso devuelve false.

Ejemplo: 
$mysql->compareTokens("6qblJRamKigUBqqlqWgTQ==");
Función que recupera los datos del cliente que accede a la página.

Ejemplo: 
$mysql->getInfo();
Fuención que crea la tabla de LOG's.

Ejemplo: 
$mysql->createTableLog();
Función que inserta el evento pasado por $event en la tabla de LOG's. También guarda el Browser o navegador, la IP, el sistema operativo y la fecha, entre otros.

Ejemplo: 
$mysql->insertEntryLog("Accede a");
Convierte una cadena de tipo fecha con el formato enviado por $format a un Array. Los parámetros de $format son los mismos parámetros de la instrucción date() de PHP.

Ejemplo: 
@extract($this->time2Array($value,"Y-m-d"));
Convierte una cadena de tipo fecha con el formato enviado por $format a formato UNIX. Los parámetros de $format son los mismos parámetros de la instrucción date() de PHP.

Si $format es VACÍO se tomarán como formatos por defecto, primero _FORMAT_DATETIME_FRMWRK y, si no da resultado, _FORMAT_DATE_FRMWRK.

Los valores de cadena SÓLO NÚMEROS o SÓLO LETRAS causan ERROR por no ser considerados fechas.

Hay que tener cuidado ya que tiene comportamientos creados a conciencia.

Notas:
  • Si la cadena es "2012/33" siendo 2012 el año y 33 el día, nos devuelve el 02-02-2012 en formato UNIXStamp.
  • Si la cadena es "oct-01" o "01-oct" siendo oct el mes (Octubre) y 01 el día devuelve 01-10-2012 en formato UNIXStamp.
  • Si la cadena es "2012-oct o "oct-2012" siendo 2012 el año y oct el mes (Octubre), devuelve 01-10-2012 en formato UNIXStamp.

Ejemplos: 
$mysql->mkTimeFormat(date("d-m-Y H:i:s"), "d-m-Y H:i:s");
Convierte una cadena de tipo fecha con el formato enviado por $format_source al formato enviado por $format. Los parámetros de $format y $format_source son los mismos parámetros de la instrucción date() de PHP.

Si $format_source es VACÍO se tomará por defecto el formato de _FORMAT_DATETIME_DB.

Si $format es VACÍO se tomarán como formatos por defecto, primero _FORMAT_DATETIME_FRMWRK y, si no da resultado, _FORMAT_DATE_FRMWRK.

Los valores de cadena SÓLO NÚMEROS o SÓLO LETRAS causan ERROR por no ser considerados fechas.

Hay que tener cuidado ya que tiene comportamientos creados a conciencia.

Ejemplos: 
$mysql->mkTimeFormat("2010-12-31", "d-m-Y H:i:s"); // Devuelve 31-12-2010
$mysql->toDateFormat("2010-12-31", "Y-m-d", "d-m-Y H:i:s"); // Devuelve 31-12-2010
$mysql->toDateFormat("2010-12-31", "", "d-m-Y H:i:s"); // Devuelve 31-12-2010
$mysql->toDateFormat("05-11-2011"); // Devuelve 2011-11-05
$mysql->toDateFormat("oct-01", "m-d")    // Devuelve 2012-10-01 (AÑO ACTUAL)
$mysql->toDateFormat("17-octubre/2012")    // Devuelve 2012-10-17
Comprueba si la cadena introducida es de tipo Fecha. Se le debe pasar el formato de la fecha aunque se puede omitir siempre y cuando la fecha tenga el formato o bien de _FORMAT_DATETIME_FRMWRK o bien, _FORMAT_DATE_FRMWRK.

Los parámetros de $format son los mismos parámetros de la instrucción date() de PHP.

Ejemplos: 
$mysql->isDate("2012/33", "Y/d") // Devolvería 02-02-2012 y por eso, devuelve true
$mysql->isDate("oct-01", "m-d") // Devolvería 01-10-2012 y por eso, devuelve true
$mysql->isDate("oct", "m") // Devolvería error y por eso, devuelve false
$mysql->isDate("31", "d") // Devolvería error y por eso, devuelve false
$mysql->isDate("31/10/2012", '') // Tomaría los formatos por defecto por lo que, devuelve true
$mysql->isDate("17-octubre/2012") // Tomaría los formatos por defecto por lo que, devuelve true
Comprueba de $value es un número.
Comprueba de $value es una cadena
Función que resta 2 fechas y devuelve el número de días, horas, minutos y segundos que han pasado entre ellas.

Los parámetros $dInit_format y $dEnd_format son opcionales. Si se envía uno o ambos vacíos se tomarán como formatos por defecto, primero _FORMAT_DATETIME_FRMWRK y, si no da resultado, _FORMAT_DATE_FRMWRK.

La función devolverá un ARRAY con el formato array("d" => DIFERENCIA_DIAS, "h" => DIFERENCIA_HORAS, "m" => DIFERENCIA_MINUTOS, "s" => DIFERENCIA_SEGUNDOS) en dónde cada inicial de la clave del array indica la medida de tiempo.

Ejemplo: 
echo print_r($mysql->elapsedTime("2012/11/03",'',"05/10/2012",''));
echo print_r($mysql->elapsedTime("2012/10/03 22:10:45",'',"05/10/2012 22:56:12",''));
echo print_r($mysql->elapsedTime("2012/10/03 12:10:45",'',"05/10/2012 22:56:12",''));
Realiza la conexión a la base de datos.

Ejemplo: 
$mysql->connect();
Cierra la conexión a la base de datos.

Ejemplo: 
$mysql->disconnect();
Libera toda la memoria asociada a $this->resource (el identificador de enlace con MySQL). Solo necesita ser llamado si se está preocupado por la cantidad de memoria que está siendo usada por las consultas que devuelven conjuntos de resultados grandes. Toda la memoria de resultados asociada se liberará automaticamente al finalizar la ejecución del script.

Ejemplo: 
$mysql->free();
Ejecuta las sentencias o instrcciones que haya contenidas en $query. Si hay más de una query dentro de $query, deben de estar separadas por el contenido de _SEPARADOR_SQL, que normalmente es ";\n". Una vez realizada(s) la(s) consulta(s) tendremos acceso a las variables de control arriba mencionadas.

Hay que tener en cuenta:
  • Si _SHOW_CONTROL_MESSAGES está establecido a true, se muestran los mensajes de tipo ERROR en pantalla. Sólo para depuración de errores.
  • Si _SHOW_WARNING_ERROR está establecido a true, se muestran los mensajes de tipo WARNING en pantalla. Sólo para depuración de errores.
  • Si _STOP_WARNING_ERROR está establecido a true, se parará la ejecución como si un ERROR se tratase. Sólo para depuración de errores.

Ejemplo: 
$result = $mysql->query("SELECT * FROM blog_tags WHERE 1;");
while($row = $mysql->fetchArray()){
    echo $row['id']." ".$mysql->utf8($row['name']);
}
Función que muestra los mensajes de error generados en la clase.
Además actualiza las variables de error last_error_id, y last_error_msg, lo que permite tener siempre disponible el último código y mensaje de error generado.

Ejemplo: 
$mysql->showError();
Es únicamente para consultas en las que solicita un único dato y una única coincidencia.

Realiza la consulta a la base de datos enviada en $sentence y devuelve el valor del campo solicitado.

Si no hay coincidencias devuelve el valor por defecto establecido por _EMPTY_FIELD_BY_DEFAULT

Ejemplo:
$mysql->getValue("SELECT name FROM clientes WHERE id = 1;");
Realiza la consulta a la base de datos enviada en $sentence y devuelve una lista con los valores de los campos solicitados.

La lista es un arrat que despues se puede recuperar con la instrucción list() de PHP, o tratarlo como un array cualquiera de PHP.

Si no hay coincidencias devuelve el valor por defecto establecido por _EMPTY_FIELD_BY_DEFAULT.


Ejemplo: Si tenemos que realizar la consulta SELECT id, name FROM blog_tags WHERE id = 112; la forma más fácil será escribir algo como:

list($id, $name) = $this->getValues('SELECT id, name FROM blog_tags WHERE id = 112;');
y después, recuperarlo mediante:
echo "id = ".$id.", name = ".$name;
Elimina todas las filas o tuplas de la tabla $table que cumplan la condición $cond. La condición $cond será todo lo que vaya detrás del WHERE de la cláusula DELETE de MySQL.
Ejemplo:

$mysql->delete("blog_tags", "id = 112");
Recupera los resultados referenciados por $this->resource (el identificador de enlace con MySQL) como un array asociativo de números, nombres o ambos.

La variable $type indica cómo se hará la asociación. Sus valores pueden ser MYSQL_NUM, MYSQL_ASSOC o MYSQL_BOTH.

Por defecto es MYSQL_BOTH.

Ejemplo:
$result = $mysql->query("SELECT * FROM blog_tags WHERE 1;");
while($row = $mysql->fetchArray()){
    echo $row[0]." ".$mysql->utf8($row['name']);
}
Recupera los resultados referenciados por $this->resource (el identificador de enlace con MySQL) como objetos.

La variable $class es el nombre de la clase dónde instanciar, configurar las propiedades y devolver. Dicho de otro modo, indica a que nombre clase se transferirá el objeto resultado de la consulta.

Ejemplos:
$result = $mysql->query("SELECT * FROM blog_tags WHERE 1;");
while ($row = mysql_fetch_object($result)) {
    echo $row->id;
    echo $row->name;
}
$result = $mysql->query("SELECT * FROM blog_tags WHERE 1;");
while ($row = mysql_fetch_object($result, 'tags')) {
    echo $tags->id;
    echo $tags->name;
}
Función para exportar la base de datos por tablas o completa.

$exportfilename:
Es el nómbre del archivo destino. Es el único obligatorio

$exporttables:
Es opcional. Array que contiene las tablas de la base de datos que seran resguardadas. Puede especificarse un valor false para indicar que se exporten todas las tablas de la base de datos especificada por _DATABASE_NAME_DEVELOPMENT ó _DATABASE_NAME_PRODUCTION. Su valor por defecto es false.

$exportcompresion:
Es opcional. Indica cómo se enviará el archivo con los datos exportados. Puede ser false, GZ ó BZ2. Su valor por defecto es false.

$exportdrop:
Es opcional. Indica si se añadirá DROP antes de la creación de cada tabla. Su valor por defecto es false.


Ejemplos:
$mysql->export("isv_bbdd.txt");
$mysql->export("isv_bbdd.txt", true);
$mysql->export("isv_bbdd.txt", false, 'blog_log,blog_tags', 'bz2');

Sobre el autor

Imagen de Pablo Enrique Fernández Casado
Pablo Enrique Fernández Casado

CEO de IslaVisual, Manager, Full Stack Analyst Developer y formador por cuenta ajena con más de 25 años de experiencia en el campo de la programación y más de 10 en el campo del diseño, UX, usabilidad web y accesibilidad web. También es escritor y compositor de música, además de presentar múltiples soft kills como la escucha activa, el trabajo en equipo, la creatividad, la resiliencia o la capacidad de aprendizaje, entre otras.

Especializado en proveer soluciones integrales de bajo coste y actividades de consultoría de Usabilidad, Accesibilidad y Experiencia de Usuario (UX), además de ofrecer asesoramiento en SEO, optimización de sistemas y páginas web, entre otras habilidades.