Лучший способ инициализации класса в плагине WordPress

Прибыв сюда ровно через 2 года после того, как был задан оригинальный вопрос, хочу отметить несколько моментов. (Не просите меня отмечать много моментов, никогда).

Правильный хук

Для инициализации класса плагина следует использовать правильный хук. Универсального правила нет, так как это зависит от функционала класса.

Использование очень раннего хука, такого как "plugins_loaded", часто не имеет смысла, потому что он срабатывает для админки, фронтенда и AJAX-запросов. Но зачастую лучше использовать более поздний хук, который позволяет инициализировать классы плагина только когда это действительно необходимо.

Например, класс, работающий с шаблонами, можно инициализировать на хуке "template_redirect".

Вообще говоря, очень редко классу требуется инициализация до срабатывания хука "wp_loaded".

Нет "Божественному классу"

Большинство примеров классов в старых ответах используют названия вроде "Prefix_Example_Plugin" или "My_Plugin"... Это указывает на наличие главного класса для плагина.

Что ж, если плагин не состоит всего из одного класса (в этом случае именование по названию плагина абсолютно оправдано), создание класса, управляющего всем плагином (например, добавляющего все необходимые хуки или инициализирующего все остальные классы плагина) можно считать плохой практикой, примером божественного объекта.

В объектно-ориентированном программировании код должен стремиться к S.O.L.I.D., где "S" означает "Принцип единственной ответственности".

Это значит, что каждый класс должен выполнять одну задачу. В разработке плагинов для WordPress это означает, что разработчикам следует избегать использования одного хука для инициализации главного класса плагина. Вместо этого, разные хуки должны использоваться для инициализации разных классов в соответствии с их ответственностью.

Избегайте хуков в конструкторе

Этот аргумент уже был упомянут в других ответах, но я хочу подчеркнуть эту концепцию и сослаться на этот другой ответ, где она была довольно подробно объяснена в контексте unit-тестирования.

Почти 2015: PHP 5.2 для зомби

С 14 августа 2014 года поддержка PHP 5.3 прекращена. Он окончательно мертв. PHP 5.4 будет поддерживаться весь 2015 год, то есть еще год на момент написания.

Однако WordPress по-прежнему поддерживает PHP 5.2, но никто не должен писать ни строчки кода, поддерживающей эту версию, особенно если код ООП.

Есть несколько причин:

• PHP 5.2 умер давно, для него не выпускаются исправления безопасности, значит он небезопасен
• PHP 5.3 добавил множество возможностей, анонимные функции и пространства имен über alles
• новые версии PHP намного быстрее. PHP бесплатен. Обновление бесплатно. Зачем использовать медленную, небезопасную версию, если можно бесплатно перейти на быструю и безопасную?

Если не хотите использовать PHP 5.4+, используйте хотя бы 5.3+

Пример

Пришло время пересмотреть старые ответы с учетом сказанного.

Раз нам больше не нужно заботиться о 5.2, мы можем и должны использовать пространства имен.

Для лучшего объяснения принципа единственной ответственности, мой пример будет использовать 3 класса: один делает что-то во фронтенде, другой в админке, а третий используется в обоих случаях.

Класс для админки:

namespace GM\WPSE\Example;

class AdminStuff {

   private $tools;

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

   function setup() {
      // настройка класса, возможно добавление хуков
   }

}

Класс для фронтенда:

namespace GM\WPSE\Example;

class FrontStuff {

   private $tools;

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

   function setup() {
      // настройка класса, возможно добавление хуков
   }

}

Интерфейс Tools:

namespace GM\WPSE\Example;

interface ToolsInterface {

   function doSomething();

}

И класс Tools, используемый двумя другими:

namespace GM\WPSE\Example;

class Tools implements ToolsInterface {

   function doSomething() {
      return 'done';
   }

}

Имея эти классы, я могу инициализировать их с помощью подходящих хуков. Например:

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; // это не идеально, причина объяснена ниже
   $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; // это не идеально, причина объяснена ниже
   $front_stuff = new GM\WPSE\Example\FrontStuff( $tools );    
} );

Инверсия зависимостей и внедрение зависимостей

В примере выше я использовал пространства имен и анонимные функции для инициализации разных классов на разных хуках, применяя сказанное ранее.

Обратите внимание, как пространства имен позволяют называть классы без префиксов.

Я применил еще одну концепцию, косвенно упомянутую ранее: Внедрение зависимостей — это один из методов применения принципа инверсии зависимостей, "D" в аббревиатуре SOLID.

Класс Tools "внедряется" в два других класса при их инициализации, что позволяет разделить ответственность.

Кроме того, классы AdminStuff и FrontStuff используют указание типов для объявления, что им нужен класс, реализующий ToolsInterface.

Таким образом, мы или пользователи нашего кода могут использовать разные реализации одного интерфейса, делая наш код не связанным с конкретным классом, а с абстракцией: в этом и заключается принцип инверсии зависимостей.

Однако пример выше можно улучшить. Давайте посмотрим как.

Автозагрузка

Хороший способ писать более читаемый ООП-код — не смешивать определения типов (интерфейсы, классы) с другим кодом и размещать каждый тип в отдельном файле.

Это правило также является частью стандартов кодирования PSR-1¹.

Однако, следуя этому, перед использованием класса нужно подключить файл, в котором он находится.

Это может быть утомительно, но PHP предоставляет функции для автоматической загрузки класса, когда он требуется, используя callback, который загружает файл на основе его имени.

С пространствами имен это становится очень просто, потому что теперь можно сопоставить структуру папок со структурой пространств имен.

Это не только возможно, но и является еще одним стандартом PSR (точнее двумя: PSR-0, теперь устаревший, и PSR-4).

Следуя этим стандартам, можно использовать различные инструменты для автозагрузки, не создавая собственный автозагрузчик.

Должен сказать, что стандарты кодирования WordPress имеют другие правила для именования файлов.

Поэтому при написании кода для ядра WordPress разработчики должны следовать правилам WP, но при написании пользовательского кода это выбор разработчика. Однако использование стандартов PSR упрощает применение уже готовых инструментов².

Глобальный доступ, реестр и паттерн сервис-локатора.

Одна из главных проблем при инициализации классов плагина в WordPress — как получить к ним доступ из разных частей кода.

Сам WordPress использует глобальный подход: переменные сохраняются в глобальной области видимости, делая их доступными везде. Каждый разработчик WP тысячи раз печатал слово global в своей карьере.

Этот подход я использовал в примере выше, но он зло.

Этот ответ уже слишком длинный, чтобы позволить мне подробнее объяснить почему, но чтение первых результатов в поиске по "глобальные переменные зло" — хорошее начало.

Но как можно избежать глобальных переменных?

Есть несколько способов.

Некоторые старые ответы здесь используют подход статического экземпляра.

public static function instance() {

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

  return self::$instance;
}

Это просто и вполне нормально, но требует реализации паттерна для каждого класса, к которому нужен доступ.

Более того, часто этот подход ведет к проблеме божественного класса, потому что разработчики делают доступным главный класс этим методом, а затем используют его для доступа ко всем остальным классам.

Я уже объяснил, насколько плох божественный класс, поэтому подход со статическим экземпляром — хороший вариант, когда плагину нужно сделать доступным всего один-два класса.

Это не значит, что его можно использовать только для плагинов с парой классов. Фактически, при правильном использовании принципа внедрения зависимостей можно создавать довольно сложные приложения без необходимости делать глобально доступным большое количество объектов.

Однако иногда плагинам нужно сделать доступными несколько классов, и в этом случае подход со статическим экземпляром становится утомительным.

Другой возможный подход — использование паттерна реестра.

Вот очень простая его реализация:

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;
   }

}

Используя этот класс, можно хранить объекты в реестре по идентификатору, так что имея доступ к реестру, можно получить доступ ко всем объектам. Конечно, при первом создании объекта его нужно добавить в реестр.

Пример:

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' ) );

Пример выше показывает, что для полезности реестр должен быть глобально доступным. Одна глобальная переменная только для реестра не очень плохо, но для противников глобальных переменников можно реализовать подход статического экземпляра для реестра или функцию со статической переменной:

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

При первом вызове функция создаст реестр, при последующих — просто вернет его.

Еще один специфичный для WordPress метод сделать класс глобально доступным — возвращать экземпляр объекта из фильтра. Например:

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

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

После этого везде, где нужен реестр:

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

Еще один паттерн, который можно использовать — сервис-локатор. Он похож на реестр, но сервис-локаторы передаются в различные классы через внедрение зависимостей.

Главная проблема с этим паттерном в том, что он скрывает зависимости классов, делая код сложнее для поддержки и чтения.

DI-контейнеры

Независимо от метода, используемого для глобального доступа к реестру или сервис-локатору, объекты должны храниться там, а перед хранением их нужно инициализировать.

В сложных приложениях, где много классов и многие из них имеют несколько зависимостей, инициализация классов требует много кода, поэтому вероятность ошибок возрастает: код, которого нет, не может содержать ошибок.

В последние годы появились некоторые PHP-библиотеки, помогающие разработчикам легко инициализировать и хранить экземпляры объектов, автоматически разрешая их зависимости.

Эти библиотеки известны как контейнеры внедрения зависимостей, потому что они могут инициализировать классы, разрешая зависимости, а также хранить объекты и возвращать их при необходимости, действуя подобно реестру.

Обычно при использовании DI-контейнеров разработчики должны настраивать зависимости для каждого класса приложения, и тогда при первом запросе класса он инициализируется с нужными зависимостями, а тот же экземпляр возвращается при последующих запросах.

Некоторые DI-контейнеры также могут автоматически обнаруживать зависимости без конфигурации, используя рефлексию PHP.

Некоторые известные DI-контейнеры:

• Pimple
• Auryn
• Orno Di
• PHP DI

и многие другие.

Хочу отметить, что для простых плагинов с несколькими классами и небольшим количеством зависимостей, вероятно, не стоит использовать DI-контейнеры: подход со статическим экземпляром или глобально доступным реестром — хорошие решения. Но для сложных плагинов преимущества DI-контейнера становятся очевидными.

Конечно, даже объекты DI-контейнера должны быть доступны для использования в приложении, и для этого можно использовать один из уже рассмотренных методов: глобальная переменная, статическая переменная экземпляра, возврат объекта через фильтр и т.д.

Composer

Использование DI-контейнера часто означает использование стороннего кода. Сегодня в PHP просто скачивать внешние библиотеки (не только DI-контейнеры, но любой код, не являющийся частью приложения) и помещать их в папку приложения не считается хорошей практикой. Даже если мы авторы этого кода.

Разделение кода приложения от внешних зависимостей — признак лучшей организации, надежности и здравомыслия кода.

Composer — де-факто стандарт в PHP-сообществе для управления зависимостями. Далекий от того, чтобы быть мейнстримом в сообществе WP, это инструмент, который каждый PHP и WordPress разработчик должен хотя бы знать, если не использовать.

Этот ответ уже размером с книгу, чтобы позволить дальнейшее обсуждение, да и обсуждение Composer здесь, вероятно, не по теме. Он упомянут только для полноты.

Для получения дополнительной информации посетите сайт Composer, а также стоит прочитать этот мини-сайт, курируемый @Rarst.

¹ PSR — стандарты правил PHP, выпущенные PHP Framework Interop Group

² Composer (библиотека, которая будет упомянута в этом ответе) среди прочего также содержит утилиту автозагрузки.

Я использую следующую структуру:

Prefix_Example_Plugin::on_load();

/**
 * Пример начальной загрузки плагина на основе класса.
 */
class Prefix_Example_Plugin {

    /**
     * Инициализирует хуки (только init) и вызывает методы, которые должны выполниться сразу.
     */
    static function on_load() {

        // здесь можно добавить аварийный выключатель (если определена константа disable, то завершить выполнение)

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

    /**
     * Дальнейшая настройка хуков, загрузка файлов и т.д.
     *
     * Обратите внимание, что для методов-хуков имя обычно совпадает с названием хука (если возможно).
     */
    static function init(  ) {


    }
}

Примечания:

• имеет определенное место для методов, которые должны выполняться сразу
• легко отключить/переопределить для доработок (достаточно отцепить один метод init)
• я не думаю, что мне когда-либо требовался объект класса плагина - это требует его отслеживания и т.д.; по сути это фейковое пространство имен по задумке, а не ООП (в большинстве случаев)

Отказ от ответственности Я пока не использую unit-тесты (слишком много дел) и слышал, что статические методы могут быть менее предпочтительными для них. Проверьте этот момент самостоятельно, если вам нужно тестировать код.

Все зависит от функциональности.

Однажды я создал плагин, который регистрировал скрипты при вызове конструктора, поэтому мне пришлось подключить его к хуку wp_enqueue_scripts.

Если вы хотите вызвать его при загрузке файла functions.php, вы также можете создать экземпляр самостоятельно $class_instance = new ClassName();, как вы упомянули.

Возможно, стоит учитывать скорость и использование памяти. Я не знаю конкретных случаев, но могу представить, что в некоторых ситуациях есть неиспользуемые хуки. Создавая экземпляр на этом хуке, вы можете сэкономить некоторые ресурсы сервера.

Я знаю, что это уже пару лет как устарело, но тем временем php 5.3 поддерживает анонимные методы, поэтому я придумал вот такой вариант:

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

И почему-то он мне нравится больше всего. Я могу использовать обычные конструкторы и мне не нужно определять какие-либо методы "init" или "on_load", которые нарушают мои ООП-структуры.