Prácticas Objetivas Recomendadas para el Desarrollo de Plugins?

Cargar Scripts/CSS con wp_enqueue_script y wp_enqueue_style

Los plugins no deben cargar/intentar cargar versiones duplicadas de archivos JS/CSS, especialmente jQuery y otros archivos JS incluidos en el núcleo de WordPress.

Los plugins siempre deben usar wp_enqueue_script y wp_enqueue_style al vincular archivos JS y CSS, y nunca directamente mediante etiquetas <script>.

Relacionado

• Reutilizar funciones existentes

Soporte para I18n

Todas las cadenas de salida deben estar vinculadas a un dominio de texto apropiado para permitir la internacionalización por parte de interesados, incluso si el desarrollador no tiene interés en traducir su propio plugin.

Ten en cuenta que es muy importante cargar los archivos de idioma durante la acción init para que el usuario pueda engancharse a la acción.

Consulta el Codex: I18n para desarrolladores de WordPress

Y también este artículo: Cargando archivos de idioma de WP correctamente.

Desde WordPress 4.6+

WP 4.6 cambió el orden de carga y las ubicaciones verificadas, lo ha hecho mucho más fácil para desarrolladores y usuarios.

Considerando un plugin con un dominio de texto 'my-plugin', WordPress ahora PRIMERO buscará un archivo de traducción en:
/wp-content/languages/plugins/my-plugin-en_US.mo

Si no encuentra uno allí, entonces buscará donde el plugin le indique (usualmente en la carpeta 'language' del plugin si sigue el codex):
/wp-content/plugins/my-plugin/languages/my-plugin-en_US.mo

Por último, si no se encuentra ningún archivo de idioma, verificará la ubicación predeterminada de:
/wp-content/languages/my-plugin-en_US.mo

La primera verificación fue añadida en 4.6 y les da a los usuarios un lugar definido para añadir un archivo de idioma, ya que antes necesitaban saber dónde el desarrollador añadió el archivo de idioma, ahora el usuario solo necesita conocer el dominio de texto del plugin: /wp-content/languages/plugins/TEXTDOMAIN-LOCAL.mo

A continuación se muestra la forma antigua (No relevante desde WP 4.6+)

[...]
Finalmente, me gustaría señalar que es importante cargar archivos de idioma personalizados del usuario desde WP_LANG_DIR antes de cargar los archivos de idioma que vienen con el plugin. Cuando se cargan múltiples archivos .mo para el mismo dominio, se usará la primera traducción encontrada. De esta manera, los archivos de idioma proporcionados por el plugin servirán como respaldo para cadenas no traducidas por el usuario.

public function load_plugin_textdomain()
{
    $domain = 'my-plugin';
    // El filtro "plugin_locale" también se usa en load_plugin_textdomain()
    $locale = apply_filters( 'plugin_locale', get_locale(), $domain );

    load_textdomain( 
            $domain, 
            WP_LANG_DIR . '/my-plugin/' . $domain . '-' . $locale . '.mo' 
    );
    load_plugin_textdomain( 
            $domain, 
            FALSE, 
            dirname( plugin_basename(__FILE__) ) . '/languages/' 
    );
}

Asegúrate de que los Plugins No Generen Errores con WP_DEBUG

Siempre prueba tus plugins con WP_DEBUG activado y, idealmente, mantenlo activado durante todo tu proceso de desarrollo. Un plugin no debería generar NINGÚN error con WP_DEBUG activado. Esto incluye avisos de funciones obsoletas e índices no verificados.

Para activar el modo de depuración, edita tu archivo wp-config.php de modo que la constante WP_DEBUG esté establecida en true. Consulta la Guía de Depuración en el Codex para más detalles.

Primero Usa Funciones Existentes en el Núcleo de WordPress

Si puedes: usa funciones existentes incluidas en el núcleo de WordPress en lugar de escribir las tuyas propias. Solo desarrolla funciones PHP personalizadas cuando no exista una función apropiada preexistente en el núcleo de WordPress.

Un beneficio es que puedes usar "log deprecated notices" para monitorear fácilmente funciones que deberían ser reemplazadas. Otro beneficio es que los usuarios pueden ver la documentación de la función en el Codex y entender mejor lo que hace el plugin incluso si no son desarrolladores PHP experimentados.

Relacionado

• Soporte I18n
• Cargar Scripts/CSS con wp_enqueue_script y wp_enqueue_style
• Ofrecer Formularios Extensibles

La desinstalación debe eliminar todos los datos de un plugin

Al ser eliminado de una instalación de WordPress, un plugin debe borrar todos los archivos, carpetas, entradas de base de datos y tablas que haya creado, así como los valores de opciones que haya generado.

Los plugins pueden ofrecer una opción para exportar/importar configuraciones, de modo que los ajustes puedan guardarse fuera de WordPress antes de la eliminación.

Relacionado

• La desactivación no debe provocar pérdida de datos

Prevenir Inyección SQL con Datos de Entrada

Un plugin debería sanitizar toda la entrada de usuario obtenida directa o indirectamente (ej. vía $_POST o $_GET) antes de usar los valores de entrada para consultar la base de datos MySQL.

Ver: Formateo de sentencias SQL.

Usa una clase y código PHP orientado a objetos

No hay razón para no escribir código PHP limpio y orientado a objetos. PHP4 no es compatible desde 2008. Por supuesto, podrías prefijar todos tus nombres de funciones para terminar con nombres_de_funciones_interminablemente_largos_con_muchos_guiones_bajos, pero es mucho más fácil simplemente escribir una clase simple y agrupar todo allí. Además, coloca tu clase en un archivo separado y nómbralo adecuadamente para que puedas extenderlo y mantenerlo fácilmente:

// en functions.php
require 'inc/class-mi-plugin-genial.php';
new MiPluginGenial();

// en inc/class-mi-plugin-genial.php
class MiPluginGenial {
    function __construct() {
        // añadir filtros, wp_enqueue_script, etc.
        
        // Para asignar un método de tu clase a una función
        // de WP, haz algo como esto
        add_action('admin_menu', [$this, "admin"]);
    }
    
    public function admin() {
        // métodos públicos, para usar fuera de la clase
        // Nota que los métodos usados en otras funciones de WP
        // (como add_action) deben ser públicos
    }
    
    private function algo_mas() {
        // métodos que solo usas dentro de esta clase
    }
}

Prefijar todos los elementos del espacio de nombres global

Un plugin debe prefijar correctamente TODOS los elementos del espacio de nombres global (constantes, funciones, clases, variables, e incluso cosas como taxonomías personalizadas, tipos de post, widgets, etc.). Por ejemplo, no crees una función llamada init(); en su lugar, nómbrala algo como jpb_init().

Es común usar un prefijo de tres o cuatro letras delante de los nombres o hacer uso de la Función de Espacios de Nombres (Namespaces) de PHP. Compara: ¿Prefijo de una sola letra para constantes de clase en PHP?

Relacionado

• El espacio de nombres global es un recurso limitado

La desactivación no debe provocar pérdida de datos

Un plugin no debería eliminar ninguno de sus datos al desactivarse.

Relacionado

• La desinstalación debe eliminar todos los datos del plugin

Solo incluye archivos que necesites...

Si estás en el front-end, no incluyas código relacionado con el área de administración.

Anunciar Pérdida de Datos al Desinstalar un Plugin

Al desinstalar un plugin debería notificar al usuario que se eliminarán sus datos y recibir una confirmación de que el usuario está de acuerdo con la eliminación de los datos antes de proceder. Además, un plugin debería ofrecer al usuario la opción de conservar los datos durante la desinstalación. (Esta idea proviene de @EAMann.)

Relacionado

• La desinstalación debería eliminar todos los datos del plugin
• La desactivación no debería provocar pérdida de datos

Permitir que el nombre de la carpeta del plugin sea cambiado

/plugins/nombreplugin/{varios}

El "nombreplugin" utilizado para la carpeta siempre debería poder cambiarse.

Esto normalmente se maneja definiendo constantes y usándolas consistentemente a lo largo del plugin.

No hace falta decir que muchos plugins populares pecan en esto.

Relacionado:

• plugins_url() para enlazar fácilmente a recursos incluidos con el plugin.

Minimizar los Nombres Agregados al Espacio de Nombres Global

Un plugin debería reducir su impacto tanto como sea posible minimizando el número de nombres que agrega al espacio de nombres global.

Esto se puede lograr encapsulando las funciones del plugin en una clase o utilizando la característica de espacios de nombres de PHP. Prefijar todo también puede ayudar, pero no es tan flexible.

Además de funciones y clases, un plugin no debería introducir variables globales. El uso de clases normalmente las hace obsoletas y simplifica el mantenimiento del plugin.

Relacionado

• Prefijar Correctamente

Usa el manejo de errores integrado en WordPress

No simplemente hagas return; si algún dato del usuario está incorrecto. Proporciónales información sobre lo que salió mal.

function some_example_fn( $args = array() ) 
{
    // Si el valor no fue establecido, construye un mensaje de error
    if ( ! isset( $args['some_value'] ) )
        $error = new WP_Error( 'some_value', sprintf( __( 'Has olvidado especificar el %1$s para tu función. %2$s Error generado en %3$s, línea %4$s.', TEXTDOMAIN ), '$args[\'some_value\']', "\n", __FILE__, __LINE__ ) );

    // Finaliza e imprime el mensaje de error y código - ¡solo para administradores!
    if ( isset( $error ) && is_wp_error( $error ) && current_user_can( 'manage_options' ) ) 
        wp_die( $error->get_error_code(), 'Error del Tema: Argumento Faltante' );

    // Si no se generó ningún error, continúa...
}

Un objeto de error para todos

Puedes configurar un objeto de error global para tu tema o plugin durante el arranque:

function bootstrap_the_theme()
{
    global $prefix_error, $prefix_theme_name;
    // Toma el nombre del tema como ID de error:
    $theme_data = wp_get_theme();
    $prefix_theme_name = $theme_data->Name;
    $prefix_error = new WP_Error( $theme_data->Name );

    include // lo que sea, etc...
}
add_action( 'after_setup_theme', 'bootstrap_the_theme' );

Luego puedes añadir errores ilimitados bajo demanda:

function some_theme_fn( $args )
{
    global $prefix_error, $prefix_theme_name;
    $theme_data = wp_get_theme();
    if ( ! $args['whatever'] && current_user_can( 'manage_options' ) ) // algún valor requerido no establecido
        $prefix_error->add( $prefix_theme_name, sprintf( 'La función %1$s necesita el argumento %2$s establecido.', __FUNCTION__, '$args[\'whatever\']' ) );

    // continúa la función...
}

Luego puedes recuperarlos todos al final de tu tema. De esta manera no interrumpes la renderización de la página y aún puedes mostrar todos tus errores para desarrollo

function dump_theme_errors()
{
    global $prefix_error, $prefix_theme_name;

    // ¿No es administrador? O: ¿No hay error(es)?
    if ( ! current_user_can( 'manage_options' ) ! is_wp_error( $prefix_error ) )
        return;

    $theme_errors = $prefix_error->get_error_messages( $prefix_theme_name );
    echo '<h3>Errores del Tema</h3>';
    foreach ( $theme_errors as $error )
        echo "{$error}\n";
}
add_action( 'shutdown', 'dump_theme_errors' );

Puedes encontrar más información en esta pregunta. Un ticket relacionado para corregir el "funcionamiento conjunto" de WP_Error y wp_die() está enlazado desde allí y otro ticket seguirá. Comentarios, críticas y similares son apreciados.

Usa la API de Configuración antes que add_option

En lugar de agregar opciones a la base de datos mediante la función add_option, deberías almacenarlas como un array usando la API de Configuración que se encarga de todo por ti.

Usa la API de Modificaciones de Tema antes que add_option

La API de Modificaciones es una estructura bastante simple y una forma segura que permite agregar y recuperar opciones. Todo se guarda como valor serializado en tu base de datos. Fácil, seguro y simple.

Comentar usando PhpDoc

La mejor práctica es seguir el estilo de PhpDoc. Si no utilizas un IDE como "Eclipse", puedes echar un vistazo al Manual de PhpDoc.

No es necesario que sepas exactamente cómo funciona esto. Los desarrolladores profesionales pueden leer el código de todos modos y solo necesitan esto como un resumen. Los codificadores aficionados y los usuarios podrían apreciar la forma en que lo explicas al mismo nivel de conocimiento.

Proteger la Privacidad de los Usuarios del Plugin

(Anteriormente: Comunicación API Anónima)

Si un plugin se comunica con un sistema externo o API (por ejemplo, algún servicio web), debe hacerlo de forma anónima o proporcionar al usuario una opción anónima que garantice que no se filtren datos relacionados con el usuario del plugin a un tercero sin control.

Aloja plugins en WordPress.org

Utiliza el repositorio SVN proporcionado en WordPress.org para alojar plugins. Ofrece una mejor experiencia de usuario para las actualizaciones y, si nunca has usado SVN antes, te permite entenderlo al usarlo en un contexto que lo justifica.

Proporcionar control de acceso mediante permisos

En muchos casos, los usuarios pueden no querer que todos tengan acceso a las áreas creadas por tu plugin, especialmente con plugins que realizan múltiples operaciones complejas, una única verificación de capacidad codificada puede no ser suficiente.

Como mínimo, implementa verificaciones de capacidades apropiadas para todos los diferentes tipos de procedimientos para los que se puede utilizar tu plugin.

Organiza tu código

Siempre es difícil leer código que no está escrito en el orden en que se ejecuta. Primero los include/require, definiciones, wp_enqueue_style & _script, etc., luego las funciones que el plugin/theme necesita y al final el constructor (ej. pantalla de administración, cosas que se integran en el theme, etc.).

Intenta separar cosas como css y js en sus propias carpetas. También intenta hacer esto con funciones que son solo ayudantes, como aplanadores de arrays y similares. Mantener el archivo "principal" lo más limpio y fácil de leer posible es una forma que ayuda a los usuarios, desarrolladores y a ti mismo, cuando intentas actualizar en un año y no has visto el código durante mucho tiempo.

También es bueno tener una estructura que repitas a menudo, para que siempre encuentres tu camino. Desarrollar en una estructura conocida en diferentes proyectos te dará tiempo para mejorarla e incluso si tu cliente cambia a otro desarrollador, nunca escucharás "dejó un caos". Esto construye tu reputación y debería ser un objetivo a largo plazo.

Importar / Exportar Configuraciones del Plugin

No es muy común entre los plugins, pero si tu plugin tiene (algunas) configuraciones, debería proporcionar Importar/Exportar datos como configuración e información del usuario.

Importar/Exportar mejora la usabilidad de un plugin.

Un ejemplo de plugin que tiene esta funcionalidad de importación y exportación (y también un mecanismo de deshacer) es Breadcrumb NavXT (Plugin de WordPress) (transparencia total: hay algo de código mío ahí, aunque la mayoría fue hecho por mtekk).

Relacionado

• La desinstalación debería eliminar todos los datos del plugin
• La desactivación no debería provocar pérdida de datos

Morir con estilo

morir de manera adecuada Todas las funciones de los plugins (e incluso los temas) deberían utilizar wp_die() en lugares críticos para ofrecer al usuario un poco de información sobre lo que ha ocurrido. Los errores de PHP son molestos y wp_die puede dar al usuario un mensaje bien diseñado sobre lo que el plugin (o ellos) hicieron mal. Además, si el usuario tiene desactivado el modo de depuración, el plugin simplemente fallará.

Usar wp_die() también ayuda a que tus plugins/temas sean compatibles con el conjunto de pruebas de WordPress.

• Usar el manejo de errores de WP

Proporcionar pantallas de ayuda para los usuarios

Es mejor responder RTFM (haz clic en ayuda) que tener que contestar la misma pregunta una y otra vez.

/**
  * Añadir ayuda contextual para esta pantalla
  * 
  * @param $rtfm
  * @uses get_current_screen
  */ 
  function ContextualHelp( /*string*/ $rtfm) 
  { 
     $current_screen = get_current_screen();
     if ($current_screen->id == $this->_pageid) 
     {
        $rtfm .= '<h3>El Plugin de WordPress - Pantalla A</h3>';
        $rtfm .= '<p>Aquí hay algunos consejos: dona para mí ' .
     }
     return $rtfm; 
  }
add_action('contextual_help', array($this,'ContextualHelp'),1,1);

actualización / nota: (ver comentarios de kaiser): el ejemplo anterior debe usarse dentro de una clase

Ofrece Formularios Extensibles

Cuando un plugin ofrece la posibilidad de introducir datos, siempre debe incluir un hook al final, justo antes del botón de "enviar" y/o "reiniciar", para que los desarrolladores puedan extender fácilmente el formulario no solo con campos, sino también con botones.

Ver: API de Configuración

Relacionado

• Usar Acciones y Filtros
• Reutilizar funciones existentes
• Soporte para I18n

Incluye siempre las funciones mediante Hook, no directamente.

Ejemplo:

• No uses para incluir la clase del plugin via new sin hook

• Usa el Hook plugins_loaded

  // añade la clase a WP                                   
  function my_plugin_start() {                                                               
      new my_plugin();   
  }                                                        
  add_action( 'plugins_loaded', 'my_plugin_start' );
  

Actualización: un pequeño ejemplo en vivo: Plugin-svn-trunk-page y un ejemplo pseudo

//evita llamadas directas a este archivo donde no estén presentes los archivos core de WP
if (!function_exists ('add_action')) {
        header('Status: 403 Forbidden');
        header('HTTP/1.1 403 Forbidden');
        exit();
}

if ( !class_exists( 'plugin_class' ) ) {
    class plugin_class {

        function __construct() {
        }

    } // fin de la clase

    function plugin_start() {

        new plugin_class();
    }

    add_action( 'plugins_loaded', 'plugin_start' );
} // fin de class_exists

También puedes cargar via mu_plugins_loaded en instalaciones multisite, mira el codex para referencia de acciones: http://codex.wordpress.org/Plugin_API/Action_Reference Aquí también puedes ver cómo incluir WP con este hook: http://adambrown.info/p/wp_hooks/hook/plugins_loaded?version=2.1&file=wp-settings.php Yo uso esto muy a menudo y no es tan difícil y es temprano, mejor que un hard new class();

La descripción de tu plugin debe detallar con precisión las funciones del mismo. Existen 10 plugins de publicaciones destacadas. Todos ellos muestran publicaciones destacadas, pero muchos tienen características diferentes. Debería ser fácil comparar tu plugin con otros similares al leer la descripción.

Debes evitar presumir de lo simple que es tu plugin a menos que realmente sea muy básico. Debes incluir enlaces útiles en la descripción, como el enlace a la configuración.

Plugins con Licencia Compatible con GPL

Los plugins y temas deberían estar licenciados bajo una licencia compatible con WordPress. Esto permite que puedan ser redistribuidos con WordPress como un "programa". Una licencia recomendada es la GPL. Asegúrate de que todas las bibliotecas de código incluidas con el plugin sean compatibles con la misma licencia.

(Esto ha sido un problema y un serio punto de debate tanto en el pasado como en el presente.)

Minimizar los efectos secundarios de fuentes de datos remotos y servicios web

Un plugin debería cachear/proteger servicios web y/o solicitudes XMLRPC/SOAP a través de una capa de caché/proveedor de datos si los utiliza, para evitar que las solicitudes frontales esperen respuestas (lentas) del servicio web.

Esto incluye la descarga de feeds RSS y otras páginas. Diseña tus plugins para que soliciten datos en segundo plano.

Un posible PASO es (tomando como ejemplo el envío a ping.fm): Crear una tabla buffer, por ejemplo: ping_fm_buffer_post( fecha, hora, mensaje, tiempo_envio, estado )

1. Cada vez que quieras enviar una actualización a ping.fm, añádela a esta tabla.
2. Ahora, necesitamos crear un plugin para manejar estos datos. Este plugin se ejecutará mediante crontab para verificar cada actualización que aún no se haya enviado
3. Como tenemos esta tabla, también podemos listar todos los mensajes enviados a ping.fm y verificar el estado de cada publicación. En caso de que haya un problema en el lado de ping.fm, podemos reenviarlo.

Usa los Estándares de Codificación de WordPress

http://codex.wordpress.org/WordPress_Coding_Standards

¿Sabes lo mucho más fácil que es actualizar código en el que has trabajado versus el código que otra persona ha creado? Los estándares de codificación facilitan que cualquier desarrollador que trabaje en un proyecto pueda entender rápidamente lo que está pasando.

Sabemos que tu plugin o tema es tuyo, y la forma en que rompes tus líneas y añades tus llaves es una expresión de tu individualidad. Cada sangrado es una declaración cuidadosamente pensada. Pero con tu código personalizado, estás contribuyendo a WordPress, incluso si tu código no está en la aplicación principal. Los estándares de codificación ayudan a los desarrolladores a familiarizarse rápidamente con tu código.