Iniciar una wiki comunitaria para recopilar las mejores prácticas objetivas para el desarrollo de complementos. Esta pregunta se inspiró en los comentarios de @ EAMann sobre wp-hackers .

La idea es colaborar en cuáles son las mejores prácticas objetivas para que eventualmente podamos usarlas en algún proceso de revisión de colaboración comunitaria.

ACTUALIZACIÓN: Después de ver las primeras respuestas, queda claro que necesitamos tener solo una idea / sugerencia / práctica recomendada por respuesta y las personas deben revisar la lista para asegurarse de que no haya duplicados antes de publicarla.

Usar acciones y filtros

Si cree que a la gente le gustaría agregar o alterar algunos datos: proporcione apply_filters () antes de regresar .

PD: Una cosa que encuentro un poco decepcionante y que su pregunta es el porcentaje de complementos que están diseñados solo para usuarios finales, es decir, que no tienen ganchos propios. ¿Imagina si WordPress fuera diseñado como la mayoría de los complementos? Sería inflexible y una solución muy específica.

¿Quizás las cosas serían diferentes si WordPress tuviera la capacidad de instalar automáticamente complementos de los que dependían otros complementos? Por lo general, tengo que escribir una gran cantidad de la funcionalidad que necesito desde cero porque los clientes quieren las cosas de cierta manera y los complementos disponibles, mientras que el 90% allí, no me permiten la flexibilidad para actualizar el 10% restante.

Realmente deseo que los líderes de la comunidad de WordPress identifiquen una forma de garantizar que los complementos sean recompensados ​​por seguir las mejores prácticas (como agregar ganchos para otros desarrolladores) de la misma manera que las buenas respuestas se recompensan en un sitio de StackExchange.

Tomemos un ejemplo de otra pregunta :

Ejemplo: quiero hacer algo en mi complemento cuando alguien retuitea un artículo. Si hubiera un enlace personalizado en cualquier complemento de retweet popular que pudiera conectar y disparar, sería genial. No lo hay, así que puedo modificar su complemento para incluirlo, pero eso solo funciona para mi copia, y no quiero intentar redistribuirlo.

Relacionado

• Ofrecer formularios extensibles

Cargar scripts / CSS con wp_enqueue_scriptywp_enqueue_style

Los complementos no deben cargar / intentar cargar versiones duplicadas de archivos JS / CSS, especialmente jQuery y otros archivos JS incluidos en WP Core.

Los complementos siempre deben usarse wp_enqueue_scripty wp_enqueue_styleal vincular archivos JS y CSS y nunca directamente a través de <script>etiquetas.

Relacionado

• Reutilizar funciones existentes

Soporte I18n

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

Tenga en cuenta que es muy importante cargar los archivos de idioma durante la initacción para que el usuario pueda conectarse a la acción.

Vea el Codex: I18n para desarrolladores de WordPress

Y también este artículo: Carga de archivos de idioma 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 los desarrolladores y usuarios.

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

Si no puede encontrar uno allí, buscará uno donde el complemento le indique que busque (generalmente en la carpeta 'language' de los complementos si sigue el códice):
/ 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 se agregó en 4.6 y brinda a los usuarios un lugar definido para agregar un archivo de idioma, ya que antes necesitaban saber dónde el desarrollador agregó el archivo de idioma, ahora el usuario solo necesita saber el dominio de texto del complemento: / wp-content / idiomas / complementos / TEXTDOMAIN-LOCAL.mo

A continuación se muestra el método anterior (no relevante desde WP 4.6+)

[...]
Finalmente, me gustaría señalar que es importante cargar archivos de idioma de usuario personalizados desde WP_LANG_DIR antes de cargar los archivos de idioma que se envían con el complemento . Cuando se cargan varios archivos mo para el mismo dominio, se utilizará la primera traducción encontrada. De esta forma, los archivos de idioma proporcionados por el complemento servirán de respaldo para las cadenas que el usuario no traduzca.

public function load_plugin_textdomain()
{
    $domain = 'my-plugin';
    // The "plugin_locale" filter is also used in 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úrese de que los complementos no generen errores con WP_DEBUG

Siempre pruebe sus complementos con WP_DEBUGactivado e idealmente hágalo durante todo su proceso de desarrollo. Un complemento no debe arrojar CUALQUIER error con WP_DEBUGactivado. Esto incluye avisos obsoletos e índices no verificados.

Para activar la depuración, edite su wp-config.phparchivo para que la WP_DEBUGconstante se establezca en true. Vea el Codex sobre depuración para más detalles.

Primer uso de las funciones existentes en WordPress Core

Si puede: use las funciones existentes incluidas en el núcleo de WordPress en lugar de escribir las suyas propias. Solo desarrolle funciones PHP personalizadas cuando no haya una función preexistente apropiada en el núcleo de WordPress.

Una ventaja es que puede usar "avisos obsoletos de registro" para monitorear fácilmente las funciones que deben reemplazarse. Otro beneficio es que los usuarios pueden ver la documentación de la función en el Codex y comprender mejor lo que hace el complemento, incluso si no son un desarrollador PHP experimentado.

Relacionado

• Soporte I18n
• Cargue scripts / CSS con wp_enqueue_script y wp_enqueue_style
• Ofrecer formularios extensibles

La desinstalación debería eliminar todos los datos de un complemento

Al ser eliminado de una instalación de WordPress, un complemento debe eliminar todos los archivos, carpetas, entradas de la base de datos y tablas que creó, así como los valores de las opciones que creó.

Los complementos pueden ofrecer una opción para exportar / importar configuraciones, de modo que las configuraciones se puedan guardar fuera de WordPress antes de eliminarlas.

Relacionado

• La desactivación no debería provocar la pérdida de datos

Prevenir la inyección de SQL con datos de entrada

Un complemento debe desinfectar todas las entradas del usuario recuperadas directa o indirectamente (por ejemplo, a través de $_POSTo$_GET ) antes de usar los valores de entrada para consultar la base de datos MySQL.

Ver: Formateo de sentencias SQL .

Prefijar todos los elementos del espacio de nombres global

Un complemento debe anteponer correctamente TODOS los elementos del espacio de nombres global (constantes, funciones, clases, variables, incluso cosas como taxonomías personalizadas, tipos de publicaciones, widgets, etc.). Por ejemplo, no cree una función llamada init(); en su lugar, nómbralo como algo así 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 espacio de nombres PHP . Compare: ¿ Prefijo de una letra para constantes de clase PHP?

Relacionado

• El espacio de nombres global es un recurso limitado

Use un código PHP5 orientado a clases y objetos

No hay razón para no escribir código PHP5 limpio y orientado a objetos. El soporte de PHP4 se eliminará gradualmente después de la próxima versión (WP 3.1). Por supuesto, puede prefijar todos los nombres de sus funciones para terminar con interminablemente nombres_función_con_lotes_de_colecciones, pero es mucho más fácil escribir una clase simple y agrupar todo en eso. Además, coloque su clase en un archivo separado y asígnele el nombre correspondiente para que pueda ampliarla y mantenerla fácilmente:

// in functions.php
require 'inc/class-my-cool-plugin.php';
new MyCoolPlugin();

// in inc/class-my-cool-plugin.php
class MyCoolPlugin {
    function __construct() {
        // add filter hooks, wp_enqueue_script, etc.

        // To assign a method from your class to a WP 
        // function do something like this
        add_action('admin_menu', array($this, "admin"));
    }

    public function admin() {
        // public methods, for use outside of the class
        // Note that methods used in other WP functions 
        // (such as add_action) should be public
    }

    private function somethingelse() {
        // methods you only use inside this class
    }
}

La desactivación no debería provocar la pérdida de datos

Un complemento no debe eliminar ninguno de sus datos tras la desactivación .

Relacionado

• La desinstalación debería eliminar todos los datos del complemento

Solo incluya los archivos que necesita ...

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

Anuncie la pérdida de datos en la desinstalación del complemento

Tras la desinstalación, un complemento debe indicar al usuario que eliminará sus datos y recibir una confirmación de que el usuario está de acuerdo con eliminar los datos antes de hacerlo, y un complemento también debe permitirle al usuario la opción de conservar los datos después de la desinstalación. (Esta idea de @EAMann.)

Relacionado

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

Deje que se cambie el nombre de la carpeta del complemento

/ plugins / pluginname / {varios}

El "nombre del complemento" utilizado para la carpeta siempre debe ser modificable.

Esto normalmente se maneja definiendo constantes y usándolas consistentemente en todo el complemento.

No hace falta decir que muchos complementos populares son pecadores.

Relacionado:

• plugins_url() para un enlace fácil a los recursos, incluido con el complemento.

Utilice WordPress (integrado) Manejo de errores

No solo return;si alguna entrada del usuario fue incorrecta. Entregarles algo de información se hizo mal.

function some_example_fn( $args = array() ) 
{
    // If value was not set, build an error message
    if ( ! isset( $args['some_value'] ) )
        $error = new WP_Error( 'some_value', sprintf( __( 'You have forgotten to specify the %1$s for your function. %2$s Error triggered inside %3$s on line %4$s.', TEXTDOMAIN ), '$args[\'some_value\']', "\n", __FILE__, __LINE__ ) );

    // die & print error message & code - for admins only!
    if ( isset( $error ) && is_wp_error( $error ) && current_user_can( 'manage_options' ) ) 
        wp_die( $error->get_error_code(), 'Theme Error: Missing Argument' );

    // Elseif no error was triggered continue...
}

Un error (objeto) para todos

Puede configurar un objeto de error global para su tema o complemento durante el arranque:

function bootstrap_the_theme()
{
    global $prefix_error, $prefix_theme_name;
    // Take the theme name as error ID:
    $theme_data = wp_get_theme();
    $prefix_theme_name = $theme_data->Name;
    $prefix_error = new WP_Error( $theme_data->Name );

    include // whatever, etc...
}
add_action( 'after_setup_theme', 'bootstrap_the_theme' );

Más tarde, puede agregar errores ilimitados a pedido:

function some_theme_fn( $args )
{
    global $prefix_error, $prefix_theme_name;
    $theme_data = wp_get_theme();
    if ( ! $args['whatever'] && current_user_can( 'manage_options' ) ) // some required value not set
        $prefix_error->add( $prefix_theme_name, sprintf( 'The function %1$s needs the argument %2$s set.', __FUNCTION__, '$args[\'whatever\']' ) );

    // continue function...
}

Luego puedes buscarlos todos al final de tu tema. De esta manera, no interrumpe el procesamiento de la página y aún puede generar todos sus errores para desarrollar

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

    // Not an admin? OR: No error(s)?
    if ( ! current_user_can( 'manage_options' ) ! is_wp_error( $prefix_error ) )
        return;

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

Puede encontrar más información en este Q . Un ticket relacionado para arreglar el "trabajo conjunto" de WP_Errory wp_die()está vinculado desde allí y seguirá otro ticket. Comentarios, críticas y tal es apreciado.

Minimice los nombres agregados al espacio de nombres global

Un complemento debe reducir su impacto tanto como sea posible al minimizar la cantidad de nombres que agrega al espacio de nombres global .

Esto se puede hacer encapsulando las funciones del complemento en una clase o usando la función de espacios de nombres PHP . Prefijar todo también puede ayudar, pero no es tan flexible.

Junto a las funciones y clases, un complemento no debe introducir variables globales. El uso de clases normalmente las deja obsoletas y simplifica el mantenimiento del complemento.

Relacionado

• Prefijar correctamente

Comenta usando PhpDoc

La mejor práctica está cerca del estilo PhpDoc. Si no utiliza un IDE como "Eclipse", puede consultar el Manual de PhpDoc .

No tiene que saber exactamente cómo funciona esto. Los desarrolladores profesionales pueden leer el código de todos modos y solo lo necesitan como resumen. Los codificadores y usuarios aficionados pueden apreciar la forma en que lo explica en el mismo nivel de conocimiento.

Use la API de configuración antes de add_option

En lugar de agregar opciones a la base de datos a través de la función add_option, debe almacenarlas como una matriz con el uso de la API de configuración que se encarga de todo por usted.

Use la API de modificaciones de tema antes de add_option

La API de modificaciones es una construcción bastante simple y una forma segura que permite agregar y recuperar opciones. Todo se guarda como valor serializado en su base de datos. Fácil, seguro y simple.

Proteger la privacidad de los usuarios del complemento

(Anteriormente: Comunicación API anónima)

Si un complemento se comunica con un sistema externo o API (p. Ej., Algunos servicios web), debe hacerlo de forma anónima o proporcionar al usuario una opción anónima que garantice que ningún dato relacionado con el usuario del complemento se filtre a una segunda parte sin control.

Complementos de host en WordPress.org

Use el repositorio SVN provisto en WordPress.org para alojar complementos. Facilita la actualización de la experiencia del usuario y, si nunca antes ha usado SVN, puede comprenderlo al usarlo en un contexto que lo justifique.

Proporcionar control de acceso mediante el uso de permisos

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

Como mínimo, realice comprobaciones de capacidad adecuadas para todos los diferentes tipos de procedimientos para los que se puede utilizar su complemento.

Importar / Exportar configuración del complemento

No es tan común en todos los complementos, pero si su complemento tiene (algunas) configuraciones, debería proporcionar Importar / Exportar datos como la configuración y la entrada del usuario .

Importar / Exportar mejora la usabilidad de un complemento.

Un complemento de ejemplo que tiene una funcionalidad de importación y exportación (y también un mecanismo de deshacer) es Breadcrumb NavXT (Plugin de Wordpress) (divulgación completa: algún pequeño código realizado por mí, la mayoría lo ha hecho mtekk).

Relacionado

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

Organiza tu código

Siempre es difícil leer el código que no está escrito en el orden en que se ejecuta. Primero incluya / require, define, wp_enqueue_style & _script, etc., luego las funciones que necesita el complemento / tema y, por último, el generador (por ejemplo, pantalla de administración, material que se integra en el tema, etc.).

Intenta separar cosas como css y js en sus propias carpetas. También intente hacer esto con funciones que son solo auxiliares, como los aplanadores de matriz y similares. Mantener el archivo "principal" tan limpio y fácil de leer como sea posible es una forma de ayudar a los usuarios, desarrolladores y a usted, cuando intenta actualizar en un año y no ha visto el código por más tiempo.

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

Morir con estilo

morir de manera decente Todas las funciones de complementos (e incluso temas) deberían usarse wp_die()en lugares críticos para ofrecer al usuario un poco de información sobre lo que sucedió. Los errores de php son molestos y wp_diepueden dar al usuario un mensaje agradable sobre lo que el plugin (o ellos) hicieron mal. Además, si el usuario tiene la depuración desactivada, el complemento simplemente se romperá.

El uso wp_die()también ayuda a que sus complementos / temas sean compatibles con el conjunto de pruebas de WordPress .

• Utilice el manejo de errores de WP

Proporcionar pantallas de ayuda para los usuarios

Es mejor decir RTFM (haga clic en ayuda) como respuesta que tener que responder la pregunta una y otra vez.

/**
  * Add contextual help for this screen
  * 
  * @param $rtfm
  * @uses get_current_screen
  */ 
  function ContextualHelp( /*string*/ $rtfm) 
  { 
     $current_screen = get_current_screen();
     if ($current_screen->id == $this->_pageid) 
     {
        $rtfm .= '<h3>The WordPress Plugin - Screen A</h3>';
        $rtfm .= '<p>Here are some tips: donate to me ' .
     }
     return $rtfm; 
  }
add_action('contextual_help', array($this,'ContextualHelp'),1,1);

actualización / nota: (ver comentarios de kaiser): el ejemplo anterior se utilizará en una clase

Ofrecer formularios extensibles

Cuando un complemento ofrece la posibilidad de ingresar datos, siempre debe tener un gancho al final, justo antes del botón "enviar" y / o "restablecer", 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 I18n

incluir la función siempre a través de Hook, no directamente.

Ejemplo:

• No utilice para incluir la clase del complemento a través de nuevo sin gancho

• Usa los complementos Hook_loaded

  // add the class to 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 pseudoejemplo

//avoid direct calls to this file where wp core files not present
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() {
        }

    } // end class

    function plugin_start() {

        new plugin_class();
    }

    add_action( 'plugins_loaded', 'plugin_start' );
} // end class_exists

También puede cargar a través de mu_plugins_loaded en multisite-install, consulte el códice para referencia de acción: http://codex.wordpress.org/Plugin_API/Action_Reference También aquí puede ver cómo incluir wP con este gancho: http: // adambrown. info / p / wp_hooks / hook / plugins_loaded? version = 2.1 & file = wp-settings.php Lo uso muy a menudo y no es tan difícil y temprano, mejor como una nueva clase dura ();

Complementos de licencia bajo una licencia compatible con GPL

Los complementos y los temas deben tener una licencia compatible con WordPress. Esto les permite redistribuirse con WordPress como un "programa". Una licencia recomendada es la GPL . Tenga cuidado de que todas las bibliotecas de códigos incluidas con el complemento sean compatibles con la misma licencia.

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

La descripción de su complemento debe detallar con precisión las funciones de su complemento. Hay 10 complementos de publicación destacados. Todos ellos muestran publicaciones destacadas, pero muchos tienen características diferentes. Debería ser fácil comparar su complemento con complementos similares leyendo la descripción.

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

Minimice los efectos secundarios de fuentes de datos remotas y servicios web

Un plugin debe Caché / Escudo de servicio web y / o XMLRPC / peticiones SOAP a través de una capa /-proveedor de datos de almacenamiento en caché si se utilizan de manera a no hacer front-solicitudes en espera de respuesta de servicio web (lento).

Eso incluye la descarga de RSS y otras páginas. Diseñe sus complementos para que soliciten datos en segundo plano.

Un posible PASO es (Tome la publicación en ping.fm como ejemplo): cree una tabla de almacenamiento intermedio, digamos: ping_fm_buffer_post (fecha, hora, mensaje, tiempo_enviado, estado)

1. Por cada vez que desee enviar una actualización a ping.fm, agréguela a esta tabla.
2. Ahora, necesitamos crear un complemento para manejar estos datos. Este complemento se ejecutará a través de crontab para verificar cada actualización que aún no se haya enviado.
3. Debido a que tenemos esta tabla, también podemos enumerar cada mensaje enviado a ping.fm y verificar el estado de cada publicación. En caso de que haya un problema por parte de ping.fm, podemos volver a enviarlo.

Prueba tu plugin

Definitivamente deberíamos tener algunas herramientas de prueba en nuestro entorno de desarrollo de complementos.

Según esta respuesta de Ethan Seifert a una pregunta de prueba, estas son buenas prácticas a seguir:

• Las pruebas unitarias deben probar la menor cantidad de comportamiento que una clase puede realizar.
• Cuando llegue al nivel de prueba funcional, aquí es donde puede probar su código con las dependencias de Wordpress.
• Dependiendo de lo que haga su complemento, considere usar pruebas basadas en Selenium que prueban la presencia de datos en el DOM mediante ID.