¿Cuál es la mejor manera de iniciar una clase en un plugin de WordPress?

Llegando aquí exactamente 2 años después de que se hiciera la pregunta original, hay algunas cosas que quiero señalar. (No me pidas que señale muchas cosas, nunca).

Hook adecuado

Para instanciar una clase de plugin, se debe usar el hook adecuado. No hay una regla general sobre cuál es, porque depende de lo que haga la clase.

Usar un hook muy temprano como "plugins_loaded" a menudo no tiene sentido porque un hook como ese se dispara para solicitudes de admin, frontend y AJAX, pero muy frecuentemente un hook posterior es mucho mejor porque permite instanciar clases de plugin solo cuando se necesitan.

Ejemplo: una clase que hace cosas para plantillas puede instanciarse en "template_redirect".

En términos generales, es muy raro que una clase necesite ser instanciada antes de que se haya disparado "wp_loaded".

No a la Clase Dios

La mayoría de las clases usadas como ejemplos en respuestas antiguas usan una clase llamada algo como "Prefix_Example_Plugin" o "My_Plugin"... Esto indica que probablemente hay una clase principal para el plugin.

Bueno, a menos que un plugin esté hecho por una sola clase (en cuyo caso nombrarla como el plugin es absolutamente razonable), crear una clase que gestione todo el plugin (ej. añadiendo todos los hooks que necesita un plugin o instanciando todas las demás clases del plugin) puede considerarse una mala práctica, como ejemplo de un objeto dios.

En programación orientada a objetos, el código debería tender a ser S.O.L.I.D. donde la "S" significa "Principio de responsabilidad única".

Significa que cada clase debería hacer una sola cosa. En el desarrollo de plugins para WordPress significa que los desarrolladores deberían evitar usar un solo hook para instanciar una clase principal del plugin, sino que se deberían usar diferentes hooks para instanciar diferentes clases, según la responsabilidad de la clase.

Evitar hooks en el constructor

Este argumento se ha introducido en otras respuestas aquí, sin embargo quiero remarcar este concepto y enlazar esta otra respuesta donde se ha explicado bastante ampliamente en el contexto de pruebas unitarias.

Casi 2015: PHP 5.2 es para zombis

Desde el 14 de agosto de 2014, PHP 5.3 alcanzó su fin de vida. Definitivamente está muerto. PHP 5.4 va a ser soportado durante todo 2015, lo que significa otro año en el momento en que escribo.

Sin embargo, WordPress todavía soporta PHP 5.2, pero nadie debería escribir una sola línea de código que soporte esa versión, especialmente si el código es POO.

Hay diferentes razones:

• PHP 5.2 murió hace mucho tiempo, no se lanzan correcciones de seguridad para él, lo que significa que no es seguro
• PHP 5.3 añadió muchas características a PHP, funciones anónimas y espacios de nombres über alles
• las versiones más nuevas de PHP son mucho más rápidas. PHP es gratis. Actualizarlo es gratis. ¿Por qué usar una versión más lenta e insegura si puedes usar una más rápida y segura gratis?

Si no quieres usar código PHP 5.4+, usa al menos 5.3+

Ejemplo

En este punto es hora de revisar respuestas antiguas basándonos en lo que he dicho hasta aquí.

Una vez que no tenemos que preocuparnos por 5.2, podemos y debemos usar espacios de nombres.

Para explicar mejor el principio de responsabilidad única, mi ejemplo usará 3 clases, una que hace algo en el frontend, una en el backend y una tercera usada en ambos casos.

Clase de admin:

namespace GM\WPSE\Example;

class AdminStuff {

   private $tools;

   function __construct( ToolsInterface $tools ) {
     $this->tools = $tools;
   }

   function setup() {
      // configurar clase, quizá añadir hooks
   }

}

Clase de frontend:

namespace GM\WPSE\Example;

class FrontStuff {

   private $tools;

   function __construct( ToolsInterface $tools ) {
     $this->tools = $tools;
   }

   function setup() {
      // configurar clase, quizá añadir hooks
   }

}

Interfaz Tools:

namespace GM\WPSE\Example;

interface ToolsInterface {

   function doSomething();

}

Y una clase Tools, usada por las otras dos:

namespace GM\WPSE\Example;

class Tools implements ToolsInterface {

   function doSomething() {
      return 'done';
   }

}

Teniendo estas clases, puedo instanciarlas usando hooks adecuados. Algo como:

require_once plugin_dir_path( __FILE__ ) . 'src/ToolsInterface.php';
require_once plugin_dir_path( __FILE__ ) . 'src/Tools.php';

add_action( 'admin_init', function() {

   require_once plugin_dir_path( __FILE__ ) . 'src/AdminStuff.php';
   $tools = new GM\WPSE\Example\Tools;
   global $admin_stuff; // esto no es ideal, la razón se explica abajo
   $admin_stuff = new GM\WPSE\Example\AdminStuff( $tools ); 
} );

add_action( 'template_redirect', function() {

   require_once plugin_dir_path( __FILE__ ) . 'src/FrontStuff.php';
   $tools = new GM\WPSE\Example\Tools;
   global $front_stuff; // esto no es ideal, la razón se explica abajo
   $front_stuff = new GM\WPSE\Example\FrontStuff( $tools );    
} );

Inversión de Dependencias & Inyección de Dependencias

En el ejemplo anterior usé espacios de nombres y funciones anónimas para instanciar diferentes clases en diferentes hooks, poniendo en práctica lo dicho anteriormente.

Nota cómo los espacios de nombres permiten crear clases nombradas sin ningún prefijo.

Apliqué otro concepto que se mencionó indirectamente arriba: Inyección de Dependencias, es un método para aplicar el Principio de Inversión de Dependencias, la "D" en el acrónimo SOLID.

La clase Tools se "inyecta" en las otras dos clases cuando se instancian, así es posible separar responsabilidades.

Además, las clases AdminStuff y FrontStuff usan type hinting para declarar que necesitan una clase que implemente ToolsInterface.

De esta manera nosotros o los usuarios que usen nuestro código pueden usar diferentes implementaciones de la misma interfaz, haciendo que nuestro código no esté acoplado a una clase concreta sino a una abstracción: de eso se trata exactamente el Principio de Inversión de Dependencias.

Sin embargo, el ejemplo anterior puede mejorarse aún más. Veamos cómo.

Autoloader

Una buena forma de escribir código POO más legible es no mezclar definiciones de tipos (Interfaces, Clases) con otro código, y poner cada tipo en su propio archivo.

Esta regla es también uno de los estándares de codificación PSR-1¹.

Sin embargo, haciendo esto, antes de poder usar una clase hay que requerir el archivo que la contiene.

Esto puede ser abrumador, pero PHP proporciona funciones de utilidad para cargar automáticamente una clase cuando se necesita, usando un callback que carga un archivo basado en su nombre.

Usando espacios de nombres se vuelve muy fácil, porque ahora es posible hacer coincidir la estructura de carpetas con la estructura de espacios de nombres.

Eso no solo es posible, sino que también es otro estándar PSR (o mejor 2: PSR-0 ahora obsoleto, y PSR-4).

Siguiendo esos estándares es posible usar diferentes herramientas que manejan autoload, sin tener que codificar un autoloader personalizado.

Tengo que decir que los estándares de codificación de WordPress tienen reglas diferentes para nombrar archivos.

Así que al escribir código para el núcleo de WordPress, los desarrolladores tienen que seguir las reglas de WP, pero al escribir código personalizado es elección del desarrollador, aunque usar estándares PSR es más fácil para usar herramientas ya escritas².

Acceso Global, Patrón Registry y Patrón Service Locator.

Uno de los mayores problemas al instanciar clases de plugins en WordPress, es cómo acceder a ellas desde varias partes del código.

WordPress mismo usa el enfoque global: las variables se guardan en el ámbito global, haciéndolas accesibles en todas partes. Todo desarrollador de WP escribe la palabra global miles de veces en su carrera.

Este es también el enfoque que usé para el ejemplo anterior, pero es malvado.

Esta respuesta ya es demasiado larga para permitirme explicar más por qué, pero leer los primeros resultados en el SERP para "variables globales malvadas" es un buen punto de partida.

¿Pero cómo es posible evitar variables globales?

Hay diferentes formas.

Algunas de las respuestas antiguas aquí usan el enfoque de instancia estática.

public static function instance() {

  if ( is_null( self::$instance ) ) {
    self::$instance = new self;
  }

  return self::$instance;
}

Es fácil y bastante bien, pero obliga a implementar el patrón para cada clase a la que queramos acceder.

Además, muchas veces este enfoque lleva a caer en el problema de la clase dios, porque los desarrolladores hacen accesible una clase principal usando este método, y luego la usan para acceder a todas las demás clases.

Ya expliqué lo mala que es una clase dios, así que el enfoque de instancia estática es una buena forma de proceder cuando un plugin solo necesita hacer accesible una o dos clases.

Esto no significa que solo se pueda usar para plugins con solo un par de clases, de hecho, cuando se usa correctamente el principio de inyección de dependencias, es posible crear aplicaciones bastante complejas sin necesidad de hacer accesible globalmente un gran número de objetos.

Sin embargo, a veces los plugins necesitan hacer accesibles algunas clases, y en ese caso el enfoque de instancia estática es abrumador.

Otro enfoque posible es usar el patrón registry.

Esta es una implementación muy simple del mismo:

namespace GM\WPSE\Example;

class Registry {

   private $storage = array();

   function add( $id, $class ) {
     $this->storage[$id] = $class;
   }

   function get( $id ) {
      return array_key_exists( $id, $this->storage ) ? $this->storage[$id] : NULL;
   }

}

Usando esta clase es posible almacenar objetos en el objeto registry mediante un id, así que teniendo acceso a un registry es posible tener acceso a todos los objetos. Por supuesto cuando un objeto se crea por primera vez hay que añadirlo al registry.

Ejemplo:

global $registry;

if ( is_null( $registry->get( 'tools' ) ) ) {
  $tools = new GM\WPSE\Example\Tools;
  $registry->add( 'tools', $tools );
}

if ( is_null( $registry->get( 'front' ) ) ) {
  $front_stuff = new GM\WPSE\Example\FrontStuff( $registry->get( 'tools' ) );    
  $registry->add( 'front', front_stuff );
}

add_action( 'wp', array( $registry->get( 'front' ), 'wp' ) );

El ejemplo anterior deja claro que para ser útil el registry necesita ser accesible globalmente. Una variable global solo para el registry no es muy mala, sin embargo para los puristas no globales es posible implementar el enfoque de instancia estática para un registry, o quizá una función con una variable estática:

function gm_wpse_example_registry() {
  static $registry = NULL;
  if ( is_null( $registry ) ) {
    $registry = new GM\WPSE\Example\Registry;
  }
  return $registry;
}

La primera vez que se llama a la función instanciará el registry, en llamadas posteriores simplemente lo devolverá.

Otro método específico de WordPress para hacer una clase accesible globalmente es devolver una instancia de objeto desde un filtro. Algo así:

$registry = new GM\WPSE\Example\Registry;

add_filter( 'gm_wpse_example_registry', function() use( $registry ) {
  return $registry;
} );

Después de eso, donde sea que se necesite el registry:

$registry = apply_filters( 'gm_wpse_example_registry', NULL );

Otro patrón que se puede usar es el patrón service locator. Es similar al patrón registry, pero los service locators se pasan a varias clases usando inyección de dependencias.

El principal problema con este patrón es que oculta las dependencias de las clases haciendo el código más difícil de mantener y leer.

Contenedores DI

No importa el método usado para hacer accesible globalmente el registry o el service locator, los objetos tienen que almacenarse allí, y antes de almacenarse necesitan instanciarse.

En aplicaciones complejas, donde hay bastantes clases y muchas de ellas tienen varias dependencias, instanciar clases requiere mucho código, así que aumenta la posibilidad de bugs: el código que no existe no puede tener bugs.

En los últimos años han aparecido algunas bibliotecas PHP que ayudan a los desarrolladores PHP a instanciar y almacenar instancias de objetos fácilmente, resolviendo automáticamente sus dependencias.

Estas bibliotecas se conocen como Contenedores de Inyección de Dependencias porque son capaces de instanciar clases resolviendo dependencias y también de almacenar objetos y devolverlos cuando se necesitan, actuando de forma similar a un objeto registry.

Usualmente, al usar contenedores DI, los desarrolladores tienen que configurar las dependencias para cada clase de la aplicación, y luego la primera vez que una clase se necesita en el código se instancia con las dependencias adecuadas y la misma instancia se devuelve una y otra vez en solicitudes posteriores.

Algunos contenedores DI también son capaces de descubrir dependencias automáticamente sin configuración, pero usando reflexión PHP.

Algunos contenedores DI bien conocidos son:

• Pimple
• Auryn
• Orno Di
• PHP DI

y muchos otros.

Quiero señalar que para plugins simples, que involucran pocas clases y las clases no tienen muchas dependencias, probablemente no vale la pena usar contenedores DI: el método de instancia estática o un registry accesible globalmente son buenas soluciones, pero para plugins complejos los beneficios de un contenedor DI se vuelven evidentes.

Por supuesto, incluso los objetos contenedor DI tienen que ser accesibles para usarse en la aplicación y para ese propósito es posible usar uno de los métodos vistos arriba, variable global, variable de instancia estática, devolver objeto via filtro y así.

Composer

Usar contenedor DI a menudo significa usar código de terceros. Hoy en día, en PHP, cuando necesitamos usar una librería externa (así que no solo contenedores DI, sino cualquier código que no sea parte de la aplicación), simplemente descargarla y ponerla en nuestra carpeta de aplicación no se considera una buena práctica. Incluso si somos los autores de ese otro trozo de código.

Desacoplar el código de una aplicación de dependencias externas es señal de mejor organización, mejor fiabilidad y mejor cordura del código.

Composer, es el estándar de facto en la comunidad PHP para gestionar dependencias PHP. Lejos de ser mainstream también en la comunidad WP, es una herramienta que todo desarrollador PHP y WordPress debería al menos conocer, si no usar.

Esta respuesta ya tiene tamaño de libro para permitir más discusión, y también discutir Composer aquí probablemente está fuera de tema, solo se mencionó por completitud.

Para más información visita el sitio de Composer y también vale la pena leer este minisitio curado por @Rarst.

¹ PSR son estándares de reglas PHP publicados por el PHP Framework Interop Group

² Composer (una librería que se mencionará en esta respuesta) entre otras cosas también contiene una utilidad de autoloader.

Utilizo la siguiente estructura:

Prefix_Example_Plugin::on_load();

/**
 * Ejemplo de carga inicial de plugin basado en clases.
 */
class Prefix_Example_Plugin {

    /**
     * Engancha init (nada más) y llama a cosas que necesitan ejecutarse inmediatamente.
     */
    static function on_load() {

        // si es necesario, el interruptor de apagado va aquí (si la constante de deshabilitar está definida, entonces retorna)

        add_action( 'init', array( __CLASS__, 'init' ) );
    }

    /**
     * Configuración adicional de hooks, carga de archivos, etc.
     *
     * Nota que para métodos enganchados, el nombre iguala al hook (cuando es posible).
     */
    static function init(  ) {


    }
}

Notas:

• Tiene un lugar definido para cosas que necesitan ejecutarse inmediatamente
• Deshabilitar/anular para ajustes es fácil (desenganchar un método init)
• No creo haber usado/necesitado nunca un objeto de la clase del plugin - requiere llevar un seguimiento del mismo, etc; esto es realmente un falso namespace por propósito, no OOP (la mayoría del tiempo)

Aviso legal No uso pruebas unitarias todavía (tantas cosas en mi plato) y escuché que lo estático puede ser menos preferible para ellas. Haz tu investigación sobre esto si necesitas hacer pruebas unitarias.

Todo depende de la funcionalidad.

Una vez hice un plugin que registraba scripts cuando se llamaba al constructor, así que tuve que engancharlo al hook wp_enqueue_scripts.

Si quieres llamarlo cuando se carga tu archivo functions.php, también podrías crear una instancia tú mismo $class_instance = new ClassName(); como mencionaste.

Podrías considerar la velocidad y el uso de memoria. No conozco ningún caso, pero puedo imaginar que hay hooks no llamados en algunas situaciones. Al crear tu instancia en ese hook podrías ahorrar algunos recursos del servidor.

Sé que esto tiene un par de años, pero mientras tanto php 5.3 soporta métodos anónimos, así que se me ocurrió esto:

add_action( 'plugins_loaded', function() { new My_Plugin(); } );

y de alguna manera es el que más me gusta. Puedo usar constructores regulares y no necesito definir ningún método "init" o "on_load" que desordene mis estructuras de POO.