Jak dodać obsługę WP-CLI do dowolnej wtyczki WordPress?

Dostosowanie wtyczki do potrzeb użytkownika to jeden z głównych celów, który musi spełnić każdy właściciel wtyczki. Suwak na pierwszej stronie oznacza więcej selektorów kolorów, czcionek i podobnych opcji wizualnych. Jednakże, jeśli będziesz zaspokajać potrzeby programistów, administratorów i innych zaawansowanych użytkowników prędzej czy później, będą potrzebować obsługi CLI. Będą chcieli porzucić mysz i pracować tylko z klawiaturą. Dzięki projektowi WP-CLI dodanie obsługi CLI do Twojej wtyczki to bułka z masłem.

Odwieczna bitwa GUI vs CLI

Zróbmy coś z drogi: GUI (Graphical User Interface) nie jest lepszy niż CLI (Command Line Interface) i odwrotnie: CLI nie jest lepszy niż GUI. Ludzie wolą jedno od drugiego. To kwestia osobistych preferencji lub przyzwyczajenia. „Czy są takie same, czy są wymienne?” Z pewnymi kompromisami tak, mogą być, ale nikt nie lubi wybierać kolorów w czarno-białym interfejsie wiersza poleceń. To po prostu przynosi efekt przeciwny do zamierzonego. Każdy z nich służy specjalnemu celowi.

„Więc dlaczego potrzebujemy obu? Czy WP nie jest bardziej zorientowany na GUI?” Tak jest, WP jest bardziej zorientowany na GUI. Ale nie dla wszystkich użytkowników. Niektórzy ludzie używają WP w sposób, który jest bardziej odpowiedni dla CLI i umożliwia im znacznie szybszą pracę z nim. Co więcej, dlaczego nie mieć obu? Niczego nie pęcznieje ani nie przeszkadza.

Więc WP-CLI to wtyczka, prawda?

Nie, to nie jest wtyczka. Nie musisz nic dodawać do instalacji WordPressa, aby WP-CLI działało. Potrzebujesz tylko WP-CLI w swoim systemie operacyjnym. WP-CLI jest napisany w PHP i spakowany w phar. Jest to sposób na umieszczenie całej aplikacji PHP w jednym pliku, „phar” (archiwum PHP) w celu łatwej dystrybucji i instalacji w różnych systemach operacyjnych. Proces instalacji zależy od twojego systemu operacyjnego, ale jest łatwy i dobrze udokumentowany w podręczniku WP-CLI - lub jeśli bardziej interesujesz się filmami, oto jeden z instalacji WP-CLI w systemie Windows.

Nie będę powtarzał żadnego z powyższych materiałów. Jest wystarczająco szczegółowy i powinien rozpocząć korzystanie z WP-CLI w ciągu kilku minut. Kiedy go uruchomisz, zmień katalog roboczy na instalację WP, z którą planujesz pracować, i uruchom wp option get home , aby upewnić się, że jesteś na właściwej instalacji WP i że WP-CLI działa.

To prostsze niż się wydaje

Po pierwsze, potrzebujemy funkcji, która powie nam, czy użytkownik wchodzi w interakcję z WP przez CLI, czy nie. Przydaje się do wielu rzeczy, takich jak nie wysyłanie żadnych nagłówków HTTP w CLI i nie uwzględnianie funkcji CLI w „zwykłych” wywołaniach. Daje nam również możliwość ponownego wykorzystania starych funkcji pierwotnie napisanych dla GUI z niewielkimi zmianami.

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

Następnym krokiem jest ustalenie nazwy polecenia CLI. Istnieje około 40 wbudowanych poleceń. Nie możesz więc używać żadnej z tych nazw i powinieneś unikać nazw marek, takich jak „google”, ponieważ prawdopodobnie nie jesteś właścicielem Google. Najlepiej byłoby, gdyby była to nazwa wtyczki lub nazwa parasola dla zestawu funkcji, które wykonuje, aby można było umieścić wszystkie polecenia pod tą wtyczką, aby nie zanieczyszczać głównej przestrzeni nazw. To zdrowy rozsądek, jak w przypadku każdego kawałka kodu. Skorzystajmy site-info i stworzymy kilka funkcji, które zwracają różne informacje o witrynie.

Aby zachować porządek i porządek, umieść cały kod związany z WP-CLI w nowym pliku - custom-wp-cli-commands.php . Dodamy ten plik tylko wtedy, gdy będzie potrzebny i gdy cały kod związany z CLI będzie dostępny. W tym celu użyjemy funkcji, którą właśnie zbudowaliśmy. W celu przetestowania i nauki umieść plik w folderze aktywnego motywu, a następnie dodaj go do pliku functions.php motywu.

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

Następnie umieść to w 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' );

Jeśli otworzysz witrynę, stronę główną lub administratora, w przeglądarce nic się nie stanie. To dobrze. Aby przetestować nowe polecenie CLI, wróć do okna wiersza poleceń, uruchom wp site-info version , a otrzymasz wtyczkę i wersję witryny. Lub uruchom wp site-info plugins , a otrzymasz całkowitą liczbę wtyczek w witrynie. Łatwe, prawda? Przejdźmy przez kod.

Tak proste, jak rozszerzenie klasy PHP

Nasza klasa cli_site_info rozszerza klasę WP_CLI_Command ; nic wymyślnego. Możesz zadzwonić do klasy, jak chcesz. Ważny jest kod w ostatniej linii pliku – WP_CLI::add_command( 'site-info', 'cli_site_info' ) . Rejestruje nasze polecenie najwyższego poziomu i wiąże z nim naszą klasę. Jeśli chcesz zmienić polecenie site-info na coś innego, to jest miejsce, w którym możesz to zrobić.

Każda publiczna metoda (funkcja) w klasie jest podkomendą w WP-CLI. Koniecznie zapoznaj się z anatomią polecenia, aby nauczyć się prawidłowego żargonu WP-CLI. Nie ma potrzeby „rejestrowania” metody nigdzie ani żadnych dodatkowych czynności. Tak jak zrobiliśmy dla plugins() i version() – stwórz standardową funkcję i to wszystko. WP-CLI będzie wiedział, co z tym zrobić.

Gdy jesteś w metodzie, możesz uruchomić dowolny kod, którego potrzebujesz. Jednak interakcja z CLI będzie wymagała pewnych niestandardowych funkcji, ponieważ takie rzeczy jak echo nie będą działać zgodnie z oczekiwaniami. Zamiast echo jest WP_CLI::line() . Wewnętrzne API WP-CLI obejmuje wszystko, czego potrzebujesz, a wszystkie funkcje są dobrze udokumentowane, a także podzielone na dane wejściowe, wyjściowe, różne, systemowe i inne kategorie, co czyni je bardzo łatwymi do znalezienia.

Oprócz drukowania tekstu prawdopodobnie będziesz chciał użyć (asocjacyjnych) argumentów poleceń, aby móc wywoływać takie rzeczy, jak wp site-info version --wponly (wypróbuj), które wyświetla tylko informacje o wersji WP. Argumenty asocjacyjne są przechowywane w drugim argumencie funkcji metody. W naszym przypadku nazywa się to $assoc_args . Pozostaje tylko przetestować klucz tablicy pod kątem określonej wartości i odpowiednio dostosować kod, tak jak zrobiliśmy to w przypadku function version( $args, $assoc_args ) .

Dokumentacja i pomoc w CLI

WP-CLI ma wbudowany system pomocy. To bardzo przydatne. Jeśli programista zainwestuje trochę czasu, aby opisać polecenie w swoim kodzie, nigdy nie jest potrzebna żadna zewnętrzna dokumentacja polecenia. Dokumentacja nie napisze się sama (niestety), ale jeśli zainwestujesz absolutne minimum podczas tworzenia twoich poleceń, użytkownicy będą dozgonnie wdzięczni, ponieważ złożysz wszystkie dokumenty pod jednym dachem.

Piszesz dokumenty w swojej klasie jako komentarze, używając formatu PHPDoc. Aby głębiej kopać, zapoznaj się z podręcznikiem CLI. Uruchamiając wp help site-info otrzymasz listę i opis naszych podkomend, a jeśli zajrzysz do kodu, zobaczysz, skąd on pochodzi. Bardzo oczywiste. Aby uzyskać więcej informacji na temat podkomendy wersji, uruchom wp help site-info version , a otrzymasz również szczegółowe informacje na temat opcji.

Spraw, aby Twoi użytkownicy byli zadowoleni

Jasne, jeśli tworzysz widżet pogodowy, dodanie obsługi WP-CLI nie brzmi jak właściwy ruch. Jednak każde narzędzie używane przez zagorzałych programistów i administratorów, takie jak WP Reset, znacznie skorzysta z WP-CLI. Użytkownicy będą mogli łączyć polecenia, pisać skrypty bash i ogólnie wykonywać więcej rzeczy szybciej i łatwiej. To prowadzi do lepszych recenzji, szczęśliwszych użytkowników, większej liczby użytkowników i ostatecznie więcej pieniędzy dla Ciebie, niezależnie od modelu zarabiania, który masz.