Cómo dar actualizaciones automáticas a tus plugins de WordPress

Hiciste un plugin de WordPress para un cliente o para tu propio sitio y ahora te toca lo incómodo: cada vez que corriges algo, tienes que entrar a cada instalación, subir el ZIP a mano y cruzar los dedos. Los plugins del directorio oficial se actualizan con un clic desde el escritorio de WordPress, pero los tuyos no.

Plugin Update Checker resuelve justo eso. Es una librería gratuita que le da a tu plugin (o tema) el mismo aviso de “Hay una nueva versión disponible” y el botón de actualizar, sin tener que publicarlo en WordPress.org.

¿Qué es?

Es una librería en PHP, es decir, un conjunto de archivos que metes dentro de tu plugin para agregarle una función. La creó y la mantiene el desarrollador Jānis Elsts (YahnisElsts en GitHub), autor de plugins como Admin Menu Editor.

• Licencia: MIT, así que puedes usarla en proyectos comerciales.
• Versión actual: 5.7, publicada el 26 de mayo de 2026.
• Actividad: más de 2,500 estrellas en GitHub y cambios recientes en el código (el último, a finales de septiembre de 2026).
• Funciona con: plugins y temas, aunque el nombre solo diga plugins.

Cada 12 horas, la librería pregunta a un servidor si hay una versión nueva. Si la hay, WordPress muestra el aviso en la pantalla de Plugins y el administrador actualiza con un clic, igual que con cualquier plugin oficial.

¿Para qué te sirve?

• Plugins para clientes: desarrollas algo a la medida y lo instalas en varios sitios. Publicas la corrección una vez y todos la reciben.
• Plugins de pago: vendes tu plugin por tu cuenta y quieres que tus clientes reciban las mejoras sin mandarles un ZIP por correo.
• Proyectos privados en GitHub, GitLab o Bitbucket: tu código ya vive en un repositorio. La librería puede leer de ahí las versiones nuevas, sin montar un servidor aparte.
• Temas propios: lo mismo aplica si mantienes un tema personalizado.

Cómo empezar

Tienes dos caminos: servir las actualizaciones desde tu propio servidor con un archivo JSON, o conectarla directo a tu repositorio. Los dos empiezan igual.

Paso 1: agrega la librería a tu plugin

1. Descarga la última versión desde la página de releases.
2. Copia la carpeta plugin-update-checker dentro de la carpeta de tu plugin.
3. Si usas Composer (el gestor de paquetes de PHP), también puedes instalarla con composer require yahnis-elsts/plugin-update-checker.

Opción A: tu propio servidor con un archivo JSON

Crea un archivo, por ejemplo mi-plugin.json, y súbelo a una dirección pública de tu servidor. Le dice a WordPress cuál es la versión más reciente y de dónde descargarla:

{
    "name": "Mi Plugin",
    "version": "1.1.0",
    "download_url": "https://tusitio.com/descargas/mi-plugin-1.1.0.zip",
    "sections": {
        "description": "Qué hace mi plugin.",
        "changelog": "1.1.0: corrige el error del formulario."
    }
}

Después, en el archivo principal de tu plugin (el que tiene la cabecera con Plugin Name y Version), agrega estas líneas:

require __DIR__ . '/plugin-update-checker/plugin-update-checker.php';
use YahnisElsts\PluginUpdateChecker\v5\PucFactory;

$miActualizador = PucFactory::buildUpdateChecker(
    'https://tusitio.com/descargas/mi-plugin.json',
    __FILE__,
    'mi-plugin'
);

El tercer dato, mi-plugin, es el slug: el nombre corto de tu plugin, que normalmente coincide con el de su carpeta. Es opcional, pero conviene ponerlo.

Para lanzar una actualización: subes el ZIP nuevo, cambias version y download_url en el JSON, y subes el número de versión en la cabecera del plugin dentro del ZIP. Listo.

Opción B: directo desde GitHub

Si tu plugin ya está en GitHub, no necesitas el JSON. Le pasas la dirección del repositorio:

require __DIR__ . '/plugin-update-checker/plugin-update-checker.php';
use YahnisElsts\PluginUpdateChecker\v5\PucFactory;

$miActualizador = PucFactory::buildUpdateChecker(
    'https://github.com/tu-usuario/mi-plugin/',
    __FILE__,
    'mi-plugin'
);

// Opcional: la rama de donde salen las versiones estables
$miActualizador->setBranch('main');

// Opcional: descargar el ZIP que adjuntas a cada release
$miActualizador->getVcsApi()->enableReleaseAssets();

La librería busca la versión nueva en este orden: primero los releases de GitHub, luego las etiquetas (tags) como v1.1.0 y, al final, la rama que indicaste. La forma más ordenada es crear un release por cada versión y adjuntarle el ZIP ya listo.

Si el repositorio es privado, agrega un token de acceso con $miActualizador->setAuthentication('tu-token');. Usa un token con permisos solo de lectura.

Con GitLab y Bitbucket funciona casi igual: cambias la dirección del repositorio y, si es privado, das tu token. En la versión 5.7, Bitbucket usa tokens de API en lugar del antiguo OAuth 1.

Paso final: pruébalo

1. Instala tu plugin en un sitio de prueba con una versión vieja, por ejemplo la 1.0.0.
2. Publica la 1.1.0 en tu servidor o en GitHub.
3. En el escritorio de WordPress, ve a Plugins. Debajo de tu plugin aparece un enlace para buscar actualizaciones manualmente, así no esperas las 12 horas.
4. Da clic en Actualizar ahora y revisa que todo siga funcionando.

Lo que debes saber

• El número de versión manda. Si olvidas subirlo en la cabecera del plugin, WordPress creerá que sigue desactualizado y volverá a ofrecer la actualización.
• Cuida la carpeta del ZIP. Dentro del ZIP debe venir una carpeta con el mismo nombre que la del plugin instalado. Los ZIP que genera GitHub automáticamente traen nombres como mi-plugin-1.1.0; la librería intenta corregirlo, pero adjuntar tu propio ZIP en el release evita sorpresas.
• No trae sistema de licencias. Si vendes tu plugin y quieres dar actualizaciones solo a quien pagó, tienes que programar esa validación. La librería te da ganchos como addQueryArgFilter() para mandar la clave de licencia en cada consulta.
• Protege tus tokens. Un token escrito dentro del plugin viaja a cada sitio donde lo instalas. Dale solo permiso de lectura y, si puedes, usa un repositorio dedicado.
• Si vienes de la versión 4: cambiaron los nombres de las clases. Puc_v4_Factory ahora es YahnisElsts\PluginUpdateChecker\v5\PucFactory.
• Carga la librería temprano: fuera de cualquier gancho o durante plugins_loaded, como recomienda su autor.

¿Alternativas? Si tu plugin es gratuito y abierto, publicarlo en el directorio oficial de WordPress.org te da las actualizaciones sin nada extra. Si lo vendes, servicios como Freemius o Easy Digital Downloads con su módulo de licencias resuelven actualizaciones y cobros juntos, a cambio de una comisión. Plugin Update Checker es la opción ligera y gratuita cuando quieres el control completo.

Puedes ver la documentación completa y más ejemplos en el repositorio de Plugin Update Checker en GitHub.