Cómo crear – y por qué – un archivo uninstall.php en tu plugin WordPress

Los plugins WordPress que se limpian a sí mismos son oro puro. Si estás desarrollando un plugin que añada algún tipo de dato a la base de datos de WordPress es importante que el plugin elimine cualquier dato sin uso o indeseado cuando se desinstale el plugin.

Esta guía explica técnicas útiles para hacerlo usando el potencial del archivo uninstall.php.

Cómo funciona uninstall.php

Básicamente es añadir un archivo llamado uninstall.php al directorio principal (raíz) del plugin.

Por ejemplo, digamos que tienes un plugin llamado «Optimizar WordPress±, y que el directori principal es  /optimizar-wordpress/. Dentro de ese directorio es donde añadiremos el archivo uninstall.php tal que así:

A partir de ahora, cuando el plugin se desinstale (elimine) desde la pantalla de plugins del área de administración de WordPress, WordPress encontrará y ejecutará el archivo uninstall.php.

Este archivo es el que hará posible que el desarrollador del plugin (tú) limpie cualquier dato innecesario o indeseado de la base de datos.

En resumen así es como funciona. Los detalles completos están en el  Codex de WordPress.

Qué hay dentro del archivo uninstall.php

El archivo uninstall.php puede incluir cualquier código que sea necesario para gestionar la limpieza correcta y rutinas de desinstalación del plugin.

Al principio del mismo  hay que incluir siempre la protección frente a accesos indeseados. Se hace así:

Esas líneas deben estar al principio del archivo uninstall.php, antes de cualquier otro código.

Este código comprueba la constante WP_UNINSTALL_PLUGIN, que está definida por WordPress justo antes de cargar uninstall.php. Así que si algo que no sea WordPress trata de acceder al archivo el script se finalizará de inmediato.

Para que te hagas una idea más clara, aquí tienes un ejemplo de archivo uninstall.phpque elimina varios tipos de datos. Observa que la mayoría del código no está, para que lo veas más claro.

Por tanto, las técnicas de código que se añadan al archivo uninstall dependerá de los datos que haya que eliminar o modificar.

Variarán según el plugin, así que tendrás que saber exactamente qué datos tienen que eliminarse antes de añadir la técnica adecuada. En las siguientes secciones de esta guía veremos técnicas para quitar todo tipo de datos de la base de datos de WordPress

Importante: Añade únicamente las técnicas que sean necesarias, no todas. Tienes que ser cuidadoso y aplicar solo lo imprescindible

Borrar las opciones del plugin

Probablemente, la técnica de desinstalación más común es la de borrar las opciones del plugin, usando la función de WordPress delete_option(). Por ejemplo, para borrar la opción llamda miplugin_options, añade esto a uninstall.php:

Si  hay que borrar varias opciones lo haremos con un array:

Para usar este código, lógicamente,  renombra los elementos del array (p.ej., miplugin_option_1) con los nombres de las opciones de tu plugin que quieras borrar.

Truco Pro: Si estás usando las opciones del plugin para cualquier otra técnica de desinstalación NO borres las opciones hasta que hayas terminado de usarlas.

Borrar transients del plugin

Otra técnica habitual es eliminar los datos transitorios (transients) del plugin de la base de datos. Para hacerlo usaremos la función delete_transient():

De nuevo, si tenemos varios transients, tiramos de array:

Acuérdate de que el código es un ejemplo, tienes que poner los nombres de tus transients.

Borrar eventos Cron

La siguiente técnica es para cuando tengas que borrar eventos cron, y usaremos la función wp_unschedule_event(). Aquí el ejemplo:

El truco está en usar wp_next_scheduled() para obtener el  valor correcto del $timestamp del transient que quieras borrar.

Borrar tablas de la base de datos

Este es fundamental. Tienes que ser precavido con esta técnica. Asegúrate de que el nombre de la tabla sea el correcto. Aquí tienes un ejemplo en el que borraremos la tabla  miplugin_table:

Esta técnica utiliza la clase wpdb para definir la $table_name y luego borrar (drop) la tabla, si existe.

Más que nunca, es importante que recuerdes que el ejemplo usa nombres de ejemplo, en este caso miplugin_table, que deberás sustituir por el nombre de tu tabla. Siento ser tan pesado pero es vital.

Borrar entradas y páginas

Para borrar entradas y páginas que hayamos creado desde nuestro plugin  usaremos wp_trash_post(). Por ejemplo, para borrar un contenido con el ID 67:

El truco de esta técnica es determinar el ID correcto de la entrada/página.

Hay varias maneras de hacerlo, y probablemente la más fácil es grabar el ID de cualquier entrada o página creada por tu plugin.

Por ejemplo, si tu plugin añade 3 páginas cuando se activa por primera vez, podrías añadir los IDs de esas páginas a la base de datos como una opción.

De este modo puedes revisar las opciones para obtener los IDs correctos que tienes que borrar. Se haría así:

Como ves, hemos usado get_option() para obtener el array de los IDs de las páginas. Luego vamos al array y usamos wp_trash_post() para borrarlas.

Se puede usar la misma técnica para borrar entradas o páginas.

Importante: Solo debes borrar entradas y páginas si estás totalmente seguro de que el usuario no las querrá. Un modo de controlar esto es mediante una opción en los ajustes del plugin, en la que preguntarás al usuario qué entradas y/o páginas quiere borrar si desinstala el plugin.

Borrar tipos de contenido personalizados (CPTs)

Con esto me refiero a borrar ciertas entradas definidas como CPT, no a borrar en sí el CPT, que quede claro.

Para hacerlo usaremos la función wp_delete_post(). Y este sería un ejemplo de cómo borraríamos todas las entradas del CPT miplugin_cpt.

Como ves, hemos usado get_posts() para obtener las entradas del CPT miplugin_cpt. Luego hacemos loop en los resultados y usamos wp_delete_post() para borrar las entradas del CPT.

Lo único que tienes que cambiar es el nombre (slug) del CPT, en el ejemplo miplugin_cpt.

Y, de nuevo, recuerda asegurarte de que el usuario realmente quiera que se borren las entradas del CPT. Nunca está de más preguntar en una opción de los ajustes del plugin.

Nota: La técnica anterior usa wp_delete_post() para borrar las entradas del CPT. Entiende que esta función también borra todo lo que esté asociado a las entradas: comentarios, campos meta, términos, etc.
Nota: El  segundo parámetro de la función wp_delete_post() está establecido a false. Eso le dice a WordPress que envíe las entradas a la papelera, donde el usuario podrá más tarde borrarlas (o restaurarlas). Si prefieres borrarlas del todo cambia el parámetro a true.

Borrar user meta

Para borrar los metadatos de usuario vamos a utilizar la función delete_user_meta(). En el ejemplo vamos a borrar todos los metadatos de usuario de miplugin_user_meta, sería así:

Como ves, usamos get_users() para obtener el array de todos los usuarios. Luego vamos al array y usamos delete_user_meta para borrar todos los metadatos de miplugin_user_meta. Soy muy pesado, lo sé, pero recuerda cambiar el nombre miplugin_user_meta por los metadatos que TÚ  quieras borrar.

Nota: La técnica anterior borra los metadatos de todos los usuarios. Si solo quieres seleccionar una serie de usuarios puedes hacerlo pasando un array array de argumentos a get_users(). Tienes toda la información en WP_User_Query::prepare_query().

Borrar post meta

Si tu plugin añade algún metadato a las entradas puedes eliminarlo usando delete_post_meta(). Este sería un ejemplo de cómo eliminar los post meta llamados  miplugin_post_meta.

De nuevo, usamos get_posts() para obtener todas las entradas. Luego vamos a las entradas y borramos todos los datos meta llamados miplugin_post_meta. ¿Te he dicho ya que siempre cambies los nombres de los ejemplos por los tuyos? ¿ah sí?, pues entonces no te lo digo más veces (creo).

Limitar el borrado de metas a un CPT

Un truco adicional para eliminar post meta, si quieres borrarlos solo de un CPT concreto, es reemplazar el valor de $miplugin_post_args en el código anterior por lo siguiente:

Así, añadimos el parámetro post_type para get_posts(). Recuerda, cambia el nombre … ah, perdona, ya lo sabes.

Método alternativo usando delete_metadata()

Un modo alternativo, y equivalente, de eliminar todos los meta es usar la función delete_metadata(). Lo más chulo de este método oes que esta función se puede usar para borrar todos los meta de comentarios, entradas, términos o usuarios.

El ejemplo de rigor, borrando todos los post meta llamados miplugin_meta_key:

Esta técnica usa varios parámetros. Son cinco:

  • $meta_type — Tipo de objeto (entrada, comentario, término o usuario)
  • $object_id — ID del objeto o para todos
  • $meta_key — Nombre de los meta datos
  • $meta_value — Valor de los meta datos
  • $delete_all — Borrar todos los meta datos

Por tanto, para la técnica de arriba, pasaremos los siguientes argumentos de estos cinco parámetros:

  • post — Queremos seleccionar objetos de entradas
  • 0 — Usamos cero para seleccionar todas las entradas
  • miplugin_meta_key — El nombre de nuestros metadatos
  • (empty) — Déjar en blanco para seleccionar tod
  • true — Importante establecer a true para borrar todos los resultados

Como puedes imaginar, delete_metadata() es flexible y potente, y permite el borrado de cualquier metadato que exista en la base de datos de WordPress.

Archivo uninstall.php de ejemplo completo

Bueno, ya está casi completo. Este código a continuación incluye la mayoría de los ejemplos que hemos visto en la guía. No incluye todos, solo un fragmento de cada técnica. Las técnicas avanzadas o alternativas no están incluidas.

Solo tendrías que añadir este código a tu archivo uninstall.php vacío, por supuesto cambiando todos los nombres por los de tu plugin, y solo las técnicas que necesites

Advertencias finales

Siendo tan útil como es un archivo uninstall.php, es importante ser muy precavido a la hora de borrar cualquier dato de la base de datos.

Por ejemplo, en al gunos casos, los usuarios pueden desinstalar accidentalmente o temporalmente un plugin. Con lo que todo lo que el usuario haya configurado del plugin se perdería.

Para ayudar a evitar este tipo de accidentes puede ser una buena idea ofrecer la opción y preguntar a los usuarios qué quieren eliminar cuando se desinstale el plugin.

Un buen ejemplo sería una casilla obligatoria en el archivo  uninstall.php, antes de que se elimine ningún dato. Sería algo tan simple como añadir esta línea:

De ese modo puedes comprobar si el usuario realmente quiere eliminar los datos cuando se desinstale el plugin.

Conclusión: Es tú responsabilidad como desarrollador de plugins asegurarte de que se eliminen y/o restauren los datos adecuados cuando se desinstale tu plugin. Un archivo uninstall.php es un modo sencillo y fiable de conseguirlo.

VALORA Y COMPARTE ESTE ARTÍCULO PARA MEJORAR LA CALIDAD DEL BLOG…
(3 votos, promedio: 5)
¿Te gustó este artículo? ¡No sabes lo que te estás perdiendo en YouTube!

Autor: Fernando Tellado

Fernando Tellado, apasionado de WordPress, profesor, consultor y ponente. Maquero cansino, padre de tres hijos y de una perrita Beagle, Bilbaíno de nacimiento, Español de corazón y ciudadano de donde me quieran.Mi último libro es WordPress - La guía completa. Mi blog personal es Navegando con red, donde he crecido como escritor en la red y ofrezco mis visiones acerca de la Web 2.0 y la blogosfera.Sigue a @fernandot en Twitter

Comparte esta entrada en
468 ad
Ir al contenido