O czym pamiętać pisząc wtyczkę

Czasem samo korzystanie z WordPressa nie wystarcza i wtedy przychodzi do głowy straszny pomysł – może napiszę własną wtyczkę? Czasem wychodzi lepiej, czasem gorzej, ale warto mieć na uwadze kilka wskazówek, które podniosą jakość danego plugina. Pomysł to połowa sukcesu, ale nie można zapominać, że druga połowa tkwi w kodzie. I o tym kodzie jest dzisiejszy wpis.

WP_DEBUG

Tryb programistyczny to podstawa. Jeśli masz go wyłączonego to całkiem możliwe, że w środku Twojego kodu kryją się jakieś ostrzeżenia i powiadomienia. Instalujemy więc gdzieś WordPressa lub stawiamy wersję lokalną, włączamy WP_DEBUG w pliku wp-config.php i zabieramy się do roboty.

Codex, Codex, Codex

Warto sobie wziąć do serca wskazówki dotyczące pisania wtyczki, które można znaleźć na stronie Writing a Plugin. Oprócz powyższych wskazówek Codex to skarbnica wiedzy, która w przejrzysty sposób powinna rozwiać wszelkie wątpliwości na temat używanych funkcji.

Pisz lokalnie, myśl globalnie

Pamiętaj, że jeśli dobrze pójdzie Twojej wtyczki będzie używać wiele ludzi. Nie definiuj więc adresów do plików w ten sposób:

$url = site_url().'wp-content/plugins/plugin-name/file.php';

To dlatego, że ktoś może Twoją wtyczkę umieścić chociażby w folderze mu-plugins i już wszystko się wykrzaczy. Lepiej więc zrobić to w następujący sposób.

W głównym pliku wtyczki definiujemy stałą:

define( 'PLUGIN_NAME_DIR', dirname(__FILE__) );

Później przy dołączaniu plików możemy już użyć naszej stałej (pamiętaj, że jest to ścieżka na serwerze, a nie URL):

require_once( PLUGIN_NAME_DIR.'/file.php' );

Akcja nie załatwi za Ciebie wszystkiego

Załóżmy, że dodajesz swoją wtyczką w panelu administracyjnym nową stronę do menu. Na tej stronie potrzebujesz jakiegoś skyptu o hipotetycznej nazwie script123. Nie zaczepiaj się w ten sposób:

add_action('admin_enqueue_scripts', 'plugin_name_load_script');
function plugin_name_load_script() {

    wp_enqueue_script('script123');

}

Dlatego, że script123 będzie ładowany nie tylko na Twojej stronie, ale na każdej stronie w panelu administracyjnym. Przy 10 wtyczkach to jest już problem.

O wiele lepszym sposobem jest wykorzystanie do tego parametru przekazywanego w akcji. O tak:

add_action('admin_enqueue_scripts', 'plugin_name_load_script');
function plugin_name_load_script($hook) {

    if( 'hook_twojej_strony' != $hook )
        return;

    wp_enqueue_script('script123');

}

$hook jednoznacznie określa każdą stronę w panelu administracyjnym. Żeby dowiedzieć się jak on wygląda dla Twojej podstrony najlepiej to sprawdzić poprzez proste:

echo $hook;

w naszej akcji i wejście na interesującą nas podstronę w panelu.

Jeśli nie chcesz się bawić w takie akcje i hooki możesz to zrobić podczas definiowania nowej podstrony. Wystarczy to co zwraca funkcja użyta do generowania strony przypisać do jakiejś zmiennej:

$page_hook = add_submenu_page($args);

Zasadniczo jest to ten sam $hook przekazywany w akcji.

Teraz już wystarczy dodać akcję ze enqueue_script w środku:

add_action('admin_print_scripts-'.$page_hook, 'funkcja_z_enqueue_script');

Nie ufaj użytkownikowi

Jeśli w swojej wtyczce korzystasz z jakichś ustawień, gdzie użytkownik podaje jakiekolwiek dane to załóż, że wpisuje je nieprawidłowe. Problem przypomina nieco zaganianie owcy do zagrody i w sumie na tym polega – odcięcie wszystkich nieprawidłowych dróg :)

Pamiętaj też, że to że wygenerowałeś formularz w html5 i masz w polu type=”email” nie oznacza, że w Twoim formularzu będzie szedł zawsze tylko email. Tablicę $_POST można bardzo łatwo spreparować (o $_GET nawet nie wspominam), a HTML wygenerowany przez Twój skrypt można w każdej chwili zmodyfikować w przeglądarce.

WordPress oferuje kilka funkcji służących do sanityzacji (mądre słowo :) ) danych. Są to funkcje sanitize_*().

Oto kilka przykładów:

• Filtrowanie emaila – sanitize_email()
• Filtrowanie dowolnego pola tekstowego – sanitize_text_field()
• Filtrowanie tytułu (Zasadniczo Tworzenie Sluga : zasadniczo-tworzenie-sluga) – sanitize_title()

Pamiętaj, że te funkcje nie sprawdzają i nie zwracają wartości true jeśli jest ok i false jeśli coś jest nie tak. Te funkcje jak sama ich nazwa wskazuje dezynfekują, więc jeśli podasz adres email '[email protected]!’ to funkcja sanitize_email() zwróci '[email protected]’.

Jeśli chcesz sprawdzać czy dane są ok czy nie użyj funkcji PHP filter_var(). Np w taki sposób:

filter_var('[email protected]', FILTER_VALIDATE_EMAIL);

Lub:

filter_var('http://example.com', FILTER_VALIDATE_URL);
Jeśli z danymi jest wszystko ok funkcja zwraca te dane. Jeśli nie - false.

Testuj

To nie przypadek, że firmy przeznaczają sporą część zarobków na testy. Testuj więc i Ty. Przejdź przez każdą możliwą ścieżkę i rozważ każdy scenariusz. Wpisz każde nieprawidłowe dane w pola ustawień. Krótko – wyloguj się z admina i zaloguj się na usera :) Przy prostych wtyczkach raczej nie ma tak, że koszt testów i usunięcia błędów na etapie rozwoju jest mniejszy niż po wydaniu produktu bo zawsze można prosto zaktualizować wtyczkę z poprawionym błędem. Tak było właśnie z moim Advanced Cron Manager – już po dodaniu do Repozytorium zauważyłem, że nie zablokowałem możliwości usuwania schedules innych wtyczek. Nie działo się nic poważnego bo i tak nie było usunięte, ale mogło nieco dezorientować. Lepiej jednak dbać od razu u „renomę” i wydawać jak najlepszy produkt.

Sprzątaj po sobie

Dzięki Łukasz Więcek za przypomnienie :) To również jest bardzo ważna kwestia. Jeśli używałeś w swojej wtyczce jakichś opcji to zadbaj o to, żeby po sobie posprzątać. Jak to zrobić? Bardzo prosto. W głównym katalogu wtyczki tworzymi plik uninstall.php, w nim dodaj od razu:

//if uninstall not called from WordPress exit
if ( !defined( 'WP_UNINSTALL_PLUGIN' ) ) 
    exit();

Aby nie wywołać przypadkowo kodu, który się tam znajduje. Np. poprzez wejście bezpośrednio w ten plik z adresu w przeglądarce.

Uwaga: podczas załączania tego pliku nie ma tworzonej instancji wtyczki! Oznacza to, że jak masz jakąś funkcję lub metodę to odinstalowywania to musisz zainkludować plik swojej wtyczki i wywołać to czego potrzebujesz.

Możesz też użyć funkcji register_uninstall_hook().

Nie każ się domyślać

Na koniec luźna rada dotycząca dodawania wtyczki do Repozytorium WordPressa. Chcesz szybko przejść przez weryfikację? Opisz w formularzu dodawania nowej wtyczki dokładnie jak ona działa. W kodzie zadbaj o opisywanie funkcji (odkąd zainstalowałem rozszerzenie DocBlock w Sublime Text pisanie komentarzy to przyjemność). Im mniej recenzent będzie musiał się zastanawiać tym szybciej Twoja wtyczka przejdzie przez proces weryfikacji.

Podsumowanie

Mam nadzieję, że ten wpis przybliżył nico dobre zasady każdemu kto wydaje lub planuje wydać wtyczkę. Zależy mi w tym wpisie na radach bardziej doświadczonych kolegów i koleżanek – macie coś do dodania? :)