WordPress Plugin Saving Data to Database

Plugin personalizado de WordPress que guarda en la base de datos los datos enviados por los visitantes del sitio parte 1

En la publicación anterior, creamos un plugin de WordPress que añadía una aplicación JavaScript al sitio. Nuestra aplicación podía funcionar como una parte integral de una página de WordPress. Hoy iremos un paso más allá: escribiremos un plugin que guarde en la base de datos de WordPress los datos enviados por los usuarios.

Por supuesto, el repositorio de plugins de WordPress contiene muchas soluciones ya listas para este propósito, como el muy popular Contact Form 7 o el ligeramente más avanzado Forminator. Sin embargo, en esta ocasión quiero centrarme en el mecanismo subyacente de cómo funciona un formulario en un sitio de WordPress. El ejemplo presentado será muy sencillo, pero el mismo enfoque puede ampliarse a aplicaciones mucho más complejas. Sin mucha dificultad, podrías crear un sistema de reservas o cualquier otro sistema que funcione de manera similar con datos enviados por los usuarios.

Eso es suficiente introducción; ahora, manos a la obra.

Imaginemos que necesitamos un formulario sencillo que permita a los usuarios registrarse en un evento que estamos organizando. Como antes, creamos un directorio cuyo nombre coincida con el nombre de nuestro plugin. En este caso, será event-list-plugin. Dentro de este directorio, creamos un archivo PHP cuyo nombre (importante) sea idéntico al nombre del directorio. Así, creamos el archivo event-list-plugin.php.

<?php
/*
Plugin Name: Event List Plugin
*/

Como puedes ver, estos son los detalles básicos de nuestro plugin. Según la documentación de WordPress, esta información puede presentarse en una forma más ampliada. Sin embargo, para los fines de este tutorial, utilizaremos el siguiente formato para el encabezado de nuestro plugin:

<?php
/*
Plugin Name: Event List Plugin
Description: A custom form for event submission
Version: 1.0
Author: Your Name
*/

En teoría, todo el código de un plugin de WordPress podría estar contenido en un solo archivo, y dicho plugin funcionaría correctamente. El principal problema de este enfoque es que, a medida que aumenta el número de funcionalidades, el código crecerá rápidamente. Como resultado, será cada vez más difícil de leer y mantener.

Por lo tanto, adoptemos una estructura de directorios y archivos que nos ayude a gestionar el código, al menos hasta cierto punto. La organización de archivos en un plugin de WordPress es un tema bastante amplio, y distintos desarrolladores pueden abordarlo de diferentes maneras. Sin embargo, para los fines de nuestro ejemplo, adoptaremos una estructura de directorios y archivos muy sencilla:

>includes
>templates
event-list-plugin.php

En el directorio /includes colocaremos la lógica responsable de crear una nueva tabla en la base de datos. Mientras tanto, el directorio /templates contendrá las plantillas del formulario para los usuarios, la lista de usuarios registrados que se mostrará en el panel de administración de WordPress y la hoja de estilos CSS.

Volvamos ahora brevemente a nuestro archivo event-list-plugin.php:

<?php
/*
Plugin Name: Event List Plugin
Description: A custom form for event submission
Version: 1.0
Author: Your Name
*/

register_activation_hook(__FILE__, 'elp_activate');

function elp_activate()
{
    // Tutaj umieścimy kod tworzący nowe tabele bazy danych
    
}

cuando un plugin se activa. Acepta dos argumentos:

  • una cadena que contiene el nombre del archivo del plugin junto con su ruta completa,
  • una función de devolución de llamada (callback) que se ejecutará al activarse.

La constante __FILE__ que utilizamos devuelve el nombre del archivo del plugin junto con su ruta completa. La función epl_activate() será la responsable de crear una nueva tabla en la base de datos.

Podríamos colocar el código de creación de la tabla directamente dentro de esta función; sin embargo, teniendo en cuenta la estructura del plugin que definimos anteriormente, separaremos esta lógica en su propio archivo. Lo colocaremos en el directorio /includes y lo llamaremos elp-database-setup.php.

Dentro de este archivo, incluyamos el siguiente código:

<?php
function elp_create_table()
{
    global $wpdb;
    $table_name = $wpdb->prefix . 'event_list';
    $charset_collate = $wpdb->get_charset_collate();

    $sql = "CREATE TABLE $table_name (
        id mediumint(9) NOT NULL AUTO_INCREMENT,
        user_name tinytext NOT NULL,
        user_email varchar(100) NOT NULL,
        status varchar(20) DEFAULT 'pending' NOT NULL,
        PRIMARY KEY (id)
    ) $charset_collate;";

    require_once(ABSPATH . 'wp-admin/includes/upgrade.php');
    dbDelta($sql);
}

Veamos con más detalle esta función PHP. La instrucción global $wpdb proporciona acceso a una instancia del objeto wpdb, que es el responsable de comunicarse con la base de datos de WordPress.

La línea $table_name = $wpdb->prefix . 'event_list'; define el nombre de nuestra tabla en la base de datos, incluyendo el prefijo de tablas de WordPress. De manera similar, $charset_collate = $wpdb->get_charset_collate();

garantiza (en una explicación simplificada) que los caracteres de texto se almacenen de forma correcta y coherente en la base de datos, de acuerdo con la configuración de WordPress.

A continuación, creamos una consulta SQL que añade las siguientes columnas a la base de datos:

  • id – la clave primaria,
  • user_name – el nombre del usuario,
  • user_email – la dirección de correo electrónico del usuario,
  • status – una columna con el valor predeterminado "pending".

La función dbDelta( $sql ) ejecuta la consulta SQL preparada y crea una nueva tabla donde almacenaremos los datos de los usuarios registrados para nuestro evento.

Por último, solo necesitamos llamar a esta función en el archivo principal del plugin, event-list-plugin.php. Después de realizar los cambios, el archivo queda de la siguiente manera:

<?php
/*
Plugin Name: Event List Plugin
Description: A custom form for event submission
Version: 1.0
Author: Your Name
*/

register_activation_hook(__FILE__, 'elp_activate');

function elp_activate()
{
    require_once plugin_dir_path(__FILE__) . 'includes/elp-database-setup.php';
    elp_create_table();
}

Si activaste el plugin inmediatamente después de crearlo, puede que te sorprenda que el cambio anterior no haya creado una nueva tabla en la base de datos. Puede parecer que nuestro código no está funcionando. Para crear la tabla, necesitas desactivar y luego volver a activar el plugin.

La función register_activation_hook() se ejecuta únicamente en el momento de la activación del plugin, razón por la cual la función elp_create_table() se ejecutará en ese instante. Después de reactivar el plugin, debería aparecer en la base de datos una nueva tabla llamada prefix_event_list (por defecto wp_event_list).

Ahora es el momento del siguiente paso. Creemos una plantilla de formulario que los usuarios puedan utilizar para registrarse en el evento. En el directorio /templates, creamos el archivo sign-form1.php:

<?php
if (! defined('ABSPATH')) {
    exit; // Exit if accessed directly
}
?>

<div class="mrp-reservation-form-container">
    <h2>Event registration</h2>
    <form action="<?php echo esc_url(admin_url('admin-post.php')); ?>" method="POST" class="mrp-form">
        <!-- Security Nonce Field -->
        <?php wp_nonce_field('elp_submit_reservation_action', 'elp_reservation_nonce'); ?>

        <!-- Hidden field to tell admin-post.php which action to fire -->
        <input type="hidden" name="action" value="elp_submit_reservation">

        <div class="mrp-form-group">
            <label for="user_name">Full Name:</label>
            <input type="text" id="user_name" name="user_name" required>
        </div>

        <div class="mrp-form-group">
            <label for="user_email">Email Address:</label>
            <input type="email" id="user_email" name="user_email" required>
        </div>
        <button type="submit" class="mrp-submit-btn">Register</button>
    </form>
</div>

Ahora necesitamos registrar nuestra plantilla en el archivo principal del plugin, event-list-plugin.php. Para añadirla a una página, utilizaremos el mecanismo de shortcodes de WordPress, con el que nos familiarizamos en la publicación anterior.

<?php
/*
Plugin Name: Event List Plugin
Description: A custom form for event submission
Version: 1.0
Author: Your Name
*/

register_activation_hook(__FILE__, 'elp_activate');

function elp_activate()
{
    require_once plugin_dir_path(__FILE__) . 'includes/elp-database-setup.php';
    elp_create_table();
}

function elp_render_reservation_form()
{
    ob_start(); // Start output buffering

    // Include the form template
    include plugin_dir_path(__FILE__) . 'templates/sign-form1.php';

    return ob_get_clean(); // Return the form HTML
}

add_shortcode('sign_form_1', 'elp_render_reservation_form');

Nuestro shortcode, que utilizaremos para añadir el formulario a una página, será [sign_form_1]. La función ob_start() inicia el buffering de salida HTML, mientras que ob_get_clean() devuelve el contenido de ese buffer.

Si hemos añadido el shortcode a una de las páginas, el formulario debería ser visible ahora. Sin embargo, al hacer clic en el botón “Registrarse” aún no se ejecuta ninguna acción. Ahora manejaremos el envío del formulario.

Queremos que los datos ingresados en el formulario se guarden en la base de datos cuando se haga clic en el botón “Registrarse”. Para ello, crearemos una función responsable de guardar estos datos.

Una pequeña nota: muchos desarrolladores moverían esta función a un archivo separado. Sin embargo, para los fines de este tutorial, la colocaré en el archivo principal del plugin, ya que creo que esto será más fácil de seguir para los principiantes.

Después de agregar la función elp_handle_reservation_submission(), el archivo event-list-plugin.php queda de la siguiente manera:

<?php
/*
Plugin Name: Event List Plugin
Description: A custom form for event submission
Version: 1.0
Author: Your Name
*/

register_activation_hook(__FILE__, 'elp_activate');

function elp_activate()
{
    require_once plugin_dir_path(__FILE__) . 'includes/elp-database-setup.php';
    elp_create_table();
}

function elp_render_reservation_form()
{
    ob_start(); // Start output buffering

    // Include the form template
    include plugin_dir_path(__FILE__) . 'templates/sign-form1.php';

    return ob_get_clean(); // Return the form HTML
}

add_shortcode('sign_form_1', 'elp_render_reservation_form');

function elp_handle_reservation_submission()
{
    // Verify nonce for security
    if (! isset($_POST['elp_reservation_nonce']) || ! wp_verify_nonce($_POST['elp_reservation_nonce'], 'elp_submit_reservation_action')) {
        wp_die('Security check failed');
    }

    // Sanitize and validate form data
    $user_name = sanitize_text_field($_POST['user_name']);
    $user_email = sanitize_email($_POST['user_email']);

    // Save to database
    global $wpdb;
    $table_name = $wpdb->prefix . 'event_list';

    $wpdb->insert(
        $table_name,
        array(
            'user_name' => $user_name,
            'user_email' => $user_email,
        )
    );
    // Redirect user after submission
    wp_redirect(home_url('/thank-you-page/')); // Create a thank you page first
    exit;
}

add_action('admin_post_elp_submit_reservation', 'elp_handle_reservation_submission');

En resumen, esta función obtiene el contenido de los campos del formulario y, después de validar y sanear los datos usando sanitize_text_field() y sanitize_email(), utiliza el método $wpdb->insert() para guardar los valores de user_name y user_email en la tabla de la base de datos creada previamente.

El valor de id se añade automáticamente (lo definimos como AUTO_INCREMENT), mientras que el campo status se establece por defecto en "pending".

La función add_action(), a través de su primer parámetro admin_post_elp_submit_reservation, vincula la acción de envío del formulario (el campo action en el formulario) con la función responsable de guardar los datos en la base de datos.

Ahora que nuestros datos se almacenan en la base de datos, sería útil añadir la posibilidad de visualizarlos en el panel de administración de WordPress. Cubriremos esto en la siguiente parte del tutorial.