Aprende a crear un Plugin de WordPress usando Programación Orientada a Objetos y PHP. Veremos como incluir Hooks, Funciones, Objetos y cómo realizar las llamadas (callbacks) a los métodos de una clase.
En este HowTo vamos a aprender es a crear un Plugin desde cero utilizando Programación Orientada a Objetos (OOP), por lo que vamos a empezar con los puntos que vamos a tratar para su creación.
- Localización y Estructura.
- Información y registro del Plugin.
- Objetos (Creando la clase PHP).
- Activación, desactivación y borrado de Plugins.
- Creación y borrado de Tablas en WordPress.
- Menús y Submenús en el área de administración.
- Funciones para incluir en otros menús.
- Incluir scripts y otros recursos.
- Descarga del Plugin.
Localización y Estructura
Todos los Plugins en WordPress están localizados en la carpeta wp-content/plugins/ por lo que partiendo de esa carpeta vamos a crear la siguiente estructura de directorios y ficheros.
|
1 2 3 4 5 6 7 8 9 10 11 12 |
|- miPrimerPlugin/ |- assets/ |- js/ |- css/ |- img/ |- inc/ |- miPrimerPlugin.class.php |- admin/ |- dashboard.php |- index.php |- miPrimerPlugin.php |- uninstall.php |
Empezaremos creando la carpeta miPrimerPlugin/ donde ubicaremos todos los componentes de nuestro Plugin y dentro de estarán ubicados los siguientes directorios y ficheros:
- Un directorio de assets/ donde ubicaremos todos los recursos (scripts, hojas de estilos e imágenes) de nuestro Plugin.
- Un fichero index.php por seguridad para proteger el acceso a la carpeta de accesos indeseados.
- El fichero miPrimerPlugin.php que contiene la información para registrar nuestro Plugin y todas las llamadas a clases, funciones y hooks.
- El fichero uninstall.php se encargará de borrar las tablas del Plugin.
- En la carpeta inc/ tendremos nuestra clase miPrimerPlugin.class.php y todos los métodos necesarios para activar el plugin, crear tablas, incluir menús, scripts, etc …
Información y registro del Plugin
Incluir la Información del Plugin es un requisito imprescindible cuando lo creamos por primera vez, ya que dicha información permite que este sea reconocido por WordPress.
Esta información la incluimos tan sólo una vez y para hacerlo empleamos la sintaxis de comentarios ampliados de PHP /* … */
Veamos que tipo de información podemos incluir y cual es la función de cada una de ellas:
- Plugin Name – El Nombre del Plugin
- Plugin URI – Página web del Plugin, en caso de tenerla.
- Description – Una breve descripción.
- Author – Autor del Plugin.
- Author URI – Página web del creador.
- Version – Versión actual del Plugin
- Date – Fecha de actualización o creación.
- License – Tipo de licencia del Plugin (GPLv2 si es código abierto)
- Text Domain – Para poder incluir traducciones.
Por lo que vamos a incluir en el fichero miPrimerPlugin.php la información inicial de nuestro Plugin:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
<?php /** * Plugin Name: Mi primer Plugin de WordPress * Plugin URI: https://wwww.artegrafico.net * Description: Aprendiendo a crear Plugins con WordPress * Author: José Luis Rojo Sánchez * Author URI: https://wwww.artegrafico.net * Version: 1.0 * Date: 2019-07-01 * License: GPLv2 * Text Domain: miPrimerPlugin */ |
Por lo que si ahora vamos a nuestro gestor de WordPress y listamos nuestros Plugins veremos que este ha sido incluido correctamente.
Creación de la Clase que gestiona nuestro Plugin
Una vez tenemos la información básica de nuestro Plugin vamos a crear la clase que se encargará de gestionar y hacer funcionar nuestro Plugin.
Para ello vamos a crear un directorio al que llamaremos inc/ y dentro de este crearemos el fichero miPrimerPlugin.class.php. Le incluimos la palabra clave class para poder identificar que contiene una clase PHP.
Por lo que el contenido inicial de esta clase será el siguiente.
|
1 2 3 4 5 6 7 8 9 10 11 |
<?php /** * MiPrimerPlugin * Clase de ejemplo que gestiona el Plugin de WordPress "MiPrimerPlugin" * * @author José Luis R. */ class miPrimerPlugin { } |
Ahora necesitamos volver a modificar el fichero que contiene la información del Plugin e incluir la llamada a esta clase de PHP que acabamos de crear.
También vamos a incluir una serie de constantes y unas funciones para realizar comprobaciones de ejecución del Plugin:
- Definimos unas constantes que luego necesitaremos para localizar el directorio del Plugin y la url del Plugin que usaremos más adelante para incluir scripts y estilos.
- is_admin() nos permite determinar si la petición es realizada desde la interfaz administrativa de WordPress.
- WP_CLI determina si la herramienta de gestión de línea de comandos está activada (por lo que nos permite realizar tareas para insertar, actualizar y eliminar datos).
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
// ubicación y url del plugin de mi plugin define ('_MY_PLUGIN_DIR', plugin_dir_path(__FILE__)); define ( '_MY_PLUGIN_DIR_URL', plugin_dir_url(__FILE__) ); if ( is_admin() || ( defined( 'WP_CLI' ) && WP_CLI ) ) { require_once( _MY_PLUGIN_DIR . 'inc/miPrimerPlugin.class.php' ); $miPrimerPlugin = new miPrimerPlugin(); // aquí funciones de activación // menús de administración // scripts } |
Activación, desactivación y borrado de Plugins
Aunque el plugin ya se pueda activar y desactivar, este no va realizar ninguna acción.
Para inyectar código en WordPress necesitamos hacer uso de Hooks y los primeros que necesitamos conocer son los siguientes:
- register_activation_hook() – nos permite realizar acciones cuando el usuario activa el Plugin.
- register_deactivation_hook() se usa habitualmente para opciones de limpieza de cache, rehacer enlaces permanentes o mostrar alertas al usuario.
- register_uninstall_hook() se usa para realizar tareas de desinstalación pero en cuando necesitamos incluir código estas tareas podrían no ejecutarse correctamente por lo que WordPress provee un método alternativo ubicando un fichero llamado uninstall.php en el directorio raíz de nuestro Plugin.
En nuestro fichero miPrimerPlugin.php vamos a incluir el primer hook y el callback que llamará al método de la clase que hemos creado en el paso anterior:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
require_once( plugin_dir_path( __FILE__ ) . 'inc/miPrimerPlugin.class.php' ); $miPrimerPlugin = new miPrimerPlugin(); // comprobación inicial if ( is_admin() || ( defined( 'WP_CLI' ) && WP_CLI ) ) { require_once( _MY_PLUGIN_DIR . 'inc/miPrimerPlugin.class.php' ); $miPrimerPlugin = new miPrimerPlugin(); // activación de plugin register_activation_hook( __FILE__, [ $miPrimerPlugin, 'activation' ] ); } |
Una vez hemos incluido register_activation_hook() el siguiente paso es incluir en nuestra clase miPrimerPlugin.class.php el método con el código que se va a ejecutar cuando el plugin es activado.
|
1 2 3 4 5 6 |
<?php class miPrimerPlugin { public function activation() { // en el siguiente paso veremos que podemos incluir aquí } } |
Creando y borrando tablas en WordPress
Ahora veremos como crear tablas en la Base de Datos y para ello vamos a incluir el siguiente código dentro de nuestro método activation() en nuestra clase miPrimerPlugin.
Cuando el Plugin es activado a través de la función register_activation_hook() este llama a nuestro método activation() el cual realiza una comprobación de la existencia de la tabla en la base de datos y en caso de no existir procede a su creación.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
public function activation() { global $wpdb; $table = $wpdb->prefix . 'miPrimerPlugin'; $sql = 'CREATE TABLE IF NOT EXISTS '.$table.' ( `id` int(9) NOT NULL AUTO_INCREMENT, `creation_date` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP, `nombre` varchar(50) DEFAULT NULL, `description` text, PRIMARY KEY (`id`), KEY nombre (nombre) ) COLLATE '.$wpdb->collate; // usado para crear tablas y bases de datos require_once( ABSPATH . 'wp-admin/includes/upgrade.php' ); dbDelta( $sql ); } |
En este caso la función dbDelta() es la encargada de realizar las funciones de creación de la tabla en la base de datos. dbDelta() es bastante exigente y los requisitos para escribir código SQL los podéis ver en este enlace.
Ya sabemos como crear tablas personalizadas para nuestro plugin, pero también necesitamos saber como borrarlas cuando el usuario decide eliminar el plugin.
Para ello vamos a crear el fichero de desinstalación al que llamaremos uninstall.php el cual es ejecutado siempre que el usuario borre el Plugin y tendrá prioridad sobre register_uninstall_hook().
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
<?php // si este fichero no es ejecutado por Wordpress, exit() if (!defined('WP_UNINSTALL_PLUGIN')) { die; } // borrar opciones si fuera necesario //$option_name = 'nombre'; //delete_option($option_name); // borrar opcion wordpress //delete_site_option($option_name); // borrar opciones para multisites de wordpress // drop a custom database table global $wpdb; $table = $wpdb->prefix . 'miPrimerPlugin'; $sql = 'DROP TABLE IF EXISTS '.$table; $wpdb->query($sql); |
Creando Menús (administración)
Un Plugin no siempre tiene que disponer de un menú de administración personalizado por lo que lo crearemos siempre que lo consideremos necesario y siempre que no tenga cabida su configuración en ningún otro menú.
Volviendo a nuestro fichero miPrimerPlugin.php vamos a incluir un método init() donde vamos para poder inicializar los procesos de creación de menus, scripts, etc …
|
1 2 3 4 5 6 7 8 9 10 11 12 |
if ( is_admin() || ( defined( 'WP_CLI' ) && WP_CLI ) ) { require_once( _MY_PLUGIN_DIR . 'inc/miPrimerPlugin.class.php' ); $miPrimerPlugin = new miPrimerPlugin(); // inicializar procesos (menus, scripts, etc ...) $miPrimerPlugin->init(); // activation de plugin register_activation_hook( __FILE__, [ $miPrimerPlugin, 'activation' ] ); } |
Este método init() contiene un action hook que nos permite inyectar código en partes especificas en el core de WordPress. Lo crearemos en nuestra clase miPrimerPlugin y tendría el siguiente aspecto:
|
1 2 3 4 5 6 7 8 9 |
public function init() { // crear menús de administración add_action( 'admin_menu', [ $this, 'addAdminMenu' ] ); // scripts backend // más adelante } |
En este caso le estamos diciendo que en en el menú de administración (admin_menu) inyecte el método addAdminMenu() de nuestra clase miPrimerPlugin.
Una vez lo hemos incluido el siguiente paso es crear el método addAdminMenu() en nuestra clase y donde vamos a incluir la función add_menu_page() que es la encargada de incluir un menú padre en el panel de administración.
|
1 2 3 4 5 6 |
public function addAdminMenu() { // main menu add_menu_page('Mi Plugin', 'Mi Plugin', 'manage_options', 'mi-plugin', [ $this, 'pageDashboard' ], 'dashicons-visibility'); } |
Los parámetros de la función add_menu_page() por orden de prioridad son los siguientes:
- Título del menú (obligatorio) – que será visualizado en el atributo title del menú cuando este sea seleccionado.
- Nombre del menú (obligatorio) – es el nombre del menú y visible para el usuario.
- Competencia (obligatorio) – la competencia (capability) para el menú.
- slug (obligatorio) – la url amigable para este menú.
- función o callback (opcional) – la función o callback que será ejecutada.
- icono (opcional) – puede contener la url del icono, el nombre del icono usando la fuente de iconos dashicons de WordPress.
- Posición (opcional) – la posición que ocupará en el menú.
Por lo que vamos a incluir un nuevo método al que vamos a llamar pageDashboard() que se va a encargar de abrir esta página.
|
1 2 3 |
public function pageDashboard() { include _MY_PLUGIN_DIR.'admin/dashboard.php'; } |
Cómo incluir submenús
Los submenús se incluyen usando la función add_submenu_page() y los parámetros que utiliza son los siguientes.
- slug (obligatorio) – La url amigable del menú padre.
- Título del menú (obligatorio) – que será visualizado en el atributo title cuando este sea seleccionado.
- Nombre (obligatorio) – El nombre del submenú y que será visible al usuario.
- Competencia – La competencia (capability) para el submenú.
- slug – url amigable para el submenú.
- funcion o callback (opcional) – la función o callback que será ejecutada cuando se llame al submenú.
Por lo que vamos a incluir un par de submenús a continuación del menú para comprobar su funcionamiento.
|
1 2 3 4 5 6 7 8 9 |
public function addAdminMenu() { // main menu add_menu_page('Mi Plugin', 'Mi Plugin', 'manage_options', 'mi-plugin', [ $this, 'pageDashboard' ], 'dashicons-visibility'); // submenus add_submenu_page('mi-plugin', 'SubMenu 1', 'SubMenu 1', 'manage_options', "submenu-1", [ $this, 'pageMenu1' ] ); add_submenu_page('mi-plugin', 'SubMenu 2', 'SubMenu 2', 'manage_options', "submenu-2", [ $this, 'oageMenu2' ] ); } |
Incluir páginas a otros apartados del menú
Existen otras funciones interesantes para poder incluir páginas en los diferentes menús que ofrece WordPress. Siguen un patrón de configuración muy parecido que add_menu_page() y add_submenu_page() y se pueden consultar sus parámetros en la siguiente página.
- add_dashboard_page() – incluye un submenú al menú de escritorio
- add_posts_page() – – incluye un submenú al menú entradas
- add_media_page() – – incluye un submenú al menú medios
- add_pages_page() – incluye un submenú al menú páginas
- add_comments_page() – incluye un submenú al menú comentarios
- add_theme_page() – incluye un submenú al menú a Apariencias
- add_plugins_page() – incluye un submenú al menú Plugins
- add_users_page() – incluye un submenú al menú usuarios
- add_management_page() – incluye un submenú al menú herramientas
- add_options_page() – incluye un submenú a menú de opciones
Incluir scripts y otros recursos
Nuestros Plugins van a necesitar la inclusión de scripts por lo que para ello los vamos a incluir en el directorio assets/ que creamos inicicialmente, donde vamos a poder incluir tanto scripts, css adicional y otros recursos.
Haciendo uso de nuevo de add_action() y admin_enqueue_scripts vamos a indicar que se inyecte código durante la inclusión de scripts a la página. LLamaremos a nuestro método addScripts() de la clase miPrimerPlugin y este será el encargado de incluirlos.
|
1 2 3 4 5 6 7 8 9 |
public function init() { // crear menús de administración add_action( 'admin_menu', [ $this, 'addAdminMenu' ] ); // scripts backend add_action( 'admin_enqueue_scripts', [ $this, 'addScripts' ] ); } |
Y como en pasos anteriores procedemos a crear el método addScripts()
- Crearemos un array con los slugs del plugin que van a permitir la inclusión de estos scripts.
- De esta manera tanto los estilos incluidos mediante wp_enqueue_style() como los scripts incluidos con wp_enqueue_script() sólo serán activados en las páginas de nuestro Plugin.
- Esto evitará que interfieran con otros Plugins.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
public function addScripts() { $_pages = [ 'mi-plugin', 'mi-plugin-submenu-1', 'mi-plugin-submenu-2' ]; // cargar scripts sólo en las páginas de nuestro plugin if ( in_array(FILTER_INPUT(INPUT_GET, 'page'), $_pages )) { wp_enqueue_style( 'mi-plugin-css', _MY_PLUGIN_DIR_URL . 'assets/css/style.css', [], null, false ); wp_enqueue_script( 'mi-plugin-js', _MY_PLUGIN_DIR_URL . 'assets/js/test.js', [], null, false ); } } |
Descarga del plugin
El Plugin se puede descargar desde GitHub
