Как добавить поддержку WP-CLI в любой плагин WordPress

Настройка плагина под нужды пользователя — одна из основных задач, которой должен следовать каждый владелец плагина. Для слайдера на главной странице это означает больше палитр цветов, шрифтов и подобных визуальных опций. Однако, если вы обслуживаете разработчиков, администраторов и других опытных пользователей, рано или поздно им понадобится поддержка CLI. Они захотят отказаться от мыши и работать только с клавиатурой. Благодаря проекту WP-CLI добавление поддержки CLI в ваш плагин стало проще простого.

Вечная битва GUI против CLI

Давайте уточним: GUI (графический интерфейс пользователя) не лучше, чем CLI (интерфейс командной строки), и наоборот: CLI не лучше, чем GUI. Люди предпочитают одно другому. Это вопрос личных предпочтений или привычки. «Они одинаковые, взаимозаменяемые?» С некоторыми компромиссами, да, они могут быть, но никто не любит выбирать цвета в черно-белом интерфейсе командной строки. Это просто контрпродуктивно. Каждый из них служит определенной цели.

«Так зачем нам и то, и другое? Разве WP больше не ориентирован на графический интерфейс?» Это так, WP больше ориентирован на графический интерфейс. Но не для всех пользователей. Некоторые люди используют WP таким образом, который больше подходит для CLI, и это позволяет им работать с ним намного быстрее. Более того, почему бы не иметь и то, и другое? Ничего не мешает и не мешает.

Итак, WP-CLI — это плагин, верно?

Нет, это не плагин. Вам не нужно ничего добавлять в установку WordPress, чтобы WP-CLI работал. Вам нужен только WP-CLI на вашей ОС. WP-CLI написан на PHP и упакован в phar. Это способ поместить все PHP-приложение в один файл, «phar» (PHP-архив) для легкого распространения и установки в различных операционных системах. Процесс установки зависит от вашей операционной системы, но он прост и хорошо задокументирован в руководстве по WP-CLI — или, если вам больше нравятся видео, вот один из способов установки WP-CLI в Windows.

Я не буду повторять ни один из вышеперечисленных материалов. Он достаточно подробен и поможет вам приступить к работе с WP-CLI за считанные минуты. Когда он у вас запущен, измените свой рабочий каталог на установку WP, с которой вы планируете работать, и запустите wp option get home , чтобы убедиться, что вы находитесь в правильной установке WP и что WP-CLI работает.

Это проще, чем кажется

Во-первых, нам нужна функция, сообщающая нам, взаимодействует ли пользователь с WP через CLI или нет. Это полезно для многих вещей, таких как отказ от отправки каких-либо HTTP-заголовков в CLI и не включение функций CLI в «обычные» вызовы. Это также дает нам возможность повторно использовать старые функции, изначально написанные для графического интерфейса, с небольшими изменениями.

function is_cli_running() {
  return defined( 'WP_CLI' ) && WP_CLI;
}

Следующий шаг — придумать имя для вашей команды CLI. Есть около 40 встроенных команд. Таким образом, вы не можете использовать ни одно из этих названий, и вам следует держаться подальше от любых торговых марок, таких как «google», поскольку вы, вероятно, не являетесь владельцем Google. В идеале это должно быть имя вашего плагина или общее имя для набора функций, которые он выполняет, чтобы вы могли поместить все команды в него, чтобы не загрязнять основное пространство имен. Это здравый смысл, как и в любом фрагменте кода. Давайте воспользуемся site-info и создадим несколько функций, которые возвращают различную информацию о сайте.

Чтобы все было аккуратно и аккуратно, поместите весь код, связанный с WP-CLI, в новый файл — custom-wp-cli-commands.php . Мы включим этот файл только тогда, когда это необходимо и когда будет доступен весь код, связанный с интерфейсом командной строки. Для этого воспользуемся только что созданной функцией. Для тестирования и обучения поместите файл в папку вашей активной темы, а затем добавьте его в файл functions.php темы.

if ( is_cli_running() ) {
  require_once 'custom-wp-cli-commands.php';
}

Затем поместите это в custom-wp-cli-commands.php ;

/**
 * Just a few sample commands to learn how WP-CLI works
 */
class cli_site_info extends WP_CLI_Command {
  /**
   * Display version information.
   * ## OPTIONS
   *
   * [--wponly]
   * : Shows only WP version info, omitting the plugin one.
   */
  function version( $args, $assoc_args ) {
    if ( !empty( $assoc_args['wponly'] ) ) {
      WP_CLI::line( 'Version of WordPress is ' . get_bloginfo( 'version' ) . '.' );
    } else {
      WP_CLI::line( 'Version of this plugin is 0.1-beta, and version of WordPress ' . get_bloginfo( 'version' ) . '.' );
    }
  }
    
    
  /**
   * Display the number of plugins.
   */
  function plugins() {
    WP_CLI::line( 'There are a total of ' . sizeof( get_plugins() ) . ' plugins on this site.' );
  }
}

WP_CLI::add_command( 'site-info', 'cli_site_info' );

Если вы откроете сайт, домашнюю страницу или админку, в браузере ничего не произойдет. Это хорошо. Чтобы протестировать новую команду CLI, вернитесь в окно командной строки, запустите wp site-info version , и вы получите версию плагина и сайта. Или запустите wp site-info plugins , и вы получите общее количество плагинов на сайте. Легко, верно? Давайте пройдемся по коду.

Так же просто, как расширить класс PHP

Наш класс cli_site_info расширяет класс WP_CLI_Command ; там ничего фантастического. Вы можете называть класс как угодно. Что важно, так это код в последней строке файла — WP_CLI::add_command( 'site-info', 'cli_site_info' ) . Он регистрирует нашу команду верхнего уровня и привязывает к ней наш класс. Если вы хотите изменить команду site-info на что-то другое, это самое подходящее место.

Каждый общедоступный метод (функция) в классе является подкомандой в WP-CLI. Обязательно ознакомьтесь с анатомией команды, чтобы выучить правильный жаргон WP-CLI. Метод не нужно нигде «прописывать» или делать что-то лишнее. Как мы делали для plugins() и version() — создайте стандартную функцию, и все. WP-CLI будет знать, что с этим делать.

Оказавшись в методе, вы можете запустить любой код, который вам нужен. Однако взаимодействие с CLI потребует некоторых пользовательских функций, поскольку такие вещи, как echo , не будут работать должным образом. Вместо echo есть WP_CLI::line() . Внутренний API WP-CLI охватывает все, что вам нужно, и все функции хорошо документированы, а также разделены на вход, выход, разное, систему и другие категории, что делает их очень простыми для поиска.

Помимо печати текста, вы, вероятно, захотите использовать (ассоциативные) аргументы команды, чтобы вы могли вызывать такие вещи, как wp site-info version --wponly (попробуйте), которая выводит только информацию о версии WP. Ассоциативные аргументы хранятся во втором аргументе функции метода. В нашем случае он называется $assoc_args . Осталось только проверить ключ массива на конкретное значение и соответствующим образом скорректировать код, как мы это сделали в function version( $args, $assoc_args ) .

Документация и справка в CLI

WP-CLI имеет встроенную справочную систему. Это очень удобно. Никакая внешняя документация для команды никогда не понадобится, если разработчик потратит немного времени на описание команды в своем коде. Документация не будет написана сама (к сожалению), но если вы вложите минимум средств при создании своих команд, пользователи будут бесконечно благодарны, поскольку вы поместите всю документацию под одну крышу.

Вы пишете документы в своем классе в виде комментариев, используя формат PHPDoc. Для более глубокого изучения обратитесь к CLI Handbook. wp help site-info , вы получите список и описание наших подкоманд, и если вы посмотрите в код, вы увидите, откуда они взялись. Очень понятно. Для получения более подробной информации о подкоманде версии запустите wp help site-info version , и вы также получите подробную информацию о параметрах.

Сделайте своих пользователей счастливыми

Конечно, если вы разрабатываете погодный виджет, добавление поддержки WP-CLI не кажется правильным шагом. Тем не менее, любой инструмент, используемый упорными разработчиками и администраторами, такой как WP Reset, получит большую пользу от WP-CLI. Пользователи смогут объединять команды, писать bash-скрипты и, как правило, выполнять больше задач быстрее и проще. Это приводит к лучшим отзывам, более счастливым пользователям, большему количеству пользователей и, в конечном итоге, к большему количеству денег для вас, независимо от используемой вами модели монетизации.