Piszemy pierwszą, prostą wtyczkę do WordPressa #część 1


Piszemy pierwszą, prostą wtyczkę do WordPressa

Czy słyszałeś już o Potrzebie? Jest matką wynalazków. Kiedy czegoś Ci brak a w duszy doskwiera pustka, umysł zaczyna wtedy intensywnie myśleć – jakby tu zaspokoić tą potrzebę?

I wtedy po ratunek sięgasz gdzie? Do wtyczek!

Wtyczki spełniają przykazanie potrzeby. Rozszerzają możliwości witryny o dodatkowe funkcje i pozwalają dostosować ją do własnego ego sprawiając, że jest ona bardziej przyjazna dla użytkownika.

Gdyby WordPress nie dawał możliwości użycia templatek i wtyczek, wszelkie zmiany wprowadzone w plikach źródłowych przepadłyby bezpowrotnie przy pierwszej aktualizacji.

Naszym zadaniem jest więc napisać wtyczkę, która zatrzyma te zmiany pomimo wszystko.

À propos templatek. Pomimo, że WordPress daje nam możliwość ich użycia, nadal pozostaje ryzyko „utraty danych” przy jego zmianie.

Ale nie martw się – jest jeszcze nadzieja, bowiem jeszcze dziś nauczysz się jak przenieść i zachować ukochane funkcje ze starego motywu i zrobić z tego wtyczkę, gdyż podstawowym jej zadaniem jest dostarczenie platformie WordPress dodatkowych funkcji, niezależnie od używanego motywu.

Zanim zabierzemy się do pisania kodu, tak jak w każdej innej pracy, również i tu obowiązują pewne zasady: BHP, Savoir vivre czy netykiety.

Pozwalają nam one pisać kod wtyczki w czytelny sposób, który będzie służył nie tylko nam ale i innym użytkownikom-programistom.

Przejdźmy do sedna. Jest takich kilka zasad które należy wyznawać:

  1. Bezpieczeństwo
  2. Nazewnictwo
  3. Organizacja
  4. Nagłówki
  5. Standardy kodowania

Opiszę pokrótce każdą z nich.

 

Bezpieczeństwo


Nawiąże tu do genialnej prezentacji Krzysztofa Dróżdża z ostatniego WordUpa w Krakowie, którą powinieneś obowiązkowo przejrzeć. Prezentacja zatytułowana jest: Bezpieczny kod – Trzy nieco trudniejsze kawałki.

Mówiąc o bezpieczeństwie mam na myśli stosowanie funkcji, które nie powodują dziur w kodzie, przez które potencjalny włamywacz może dostać się do naszej strony. Szczególnie narażone są tu formularze kontaktowe (i innego tego typu wtyczki). Można by rzec, że są jak otwarte wrota, gdyż  przesyłają dane pomiędzy stronami i zapisują je do bazy danych.

Idealnym tego przykładem jest to wideo. Zobacz jak łatwo można włamać się na czyjś profil, kiedy formularz nie będzie zabezpieczony przed sfałszowanymi danymi.

Więcej o bezpiecznym kodzie będziesz mógł przeczytać, kiedy zajmiemy się częścią praktyczną tworzenia wtyczki.

 

Nazewnictwo


Tak jak każdy człowiek jest indywidualnym stworzeniem o indywidualnych cechach, genach i odcisku palca, tak nasza wtyczka powinna mieć indywidualny charakter, aby nie wchodziła w konflikt z innymi wtyczkami.

Mowa o nazewnictwie czyli stosowaniu nazw funkcji, nazw folderów i plików aby nie nastąpiła ich duplikacja.

Np. nie możesz zainstalować dwóch tych samych wtyczek (chociaż jest na to sposób), bo będą się ze sobą „gryzły” a ten błąd poniżej będzie zawsze tego skutkiem:

wtyczka-nie-mogla-zostac-wlaczona-poniewarz-spowodowala-wystapienie-krytycznego-bledu-Fatal_error-Cannot-redeclare

 

Podczas tworzenia nazwy dla wtyczki dobrą praktyką jest rozważenie nazwy bazującej na rzeczywistej funkcji wtyczki. Przykładowo: wtyczkę, która ma służyć jako formularz kontaktowy nie nazwiesz Moja Pierwsza Wtyczka, bo nikt nie zgadnie do czego ona służy.

Wystarczy przejrzeć oficjalny katalog wtyczek by zobaczyć co robią ich autorzy aby lepiej oddać charakter ich działania. Możesz Cię to zainspiruje.

 

Prefiksy zawsze i wszędzie

Najczęściej popełnianym błędem przez początkujących jest stosowania ogólnie przyjętych nazw funkcji i zmiennych. Jeżeli we wtyczce pojawi się funkcja np. update_options() i zainstalujesz inną wtyczkę, która też posiada taką funkcję, witryna przestanie działać ponieważ PHP nie zezwala na istnienie dwóch funkcji o tej samej nazwie.

 

Jak z tego wybrnąć?

Dobrą praktyką jest zatem używanie prefiksów (czyli przedrostków) składających się z inicjałów: imienia i nazwiska programisty, i nazwy wtyczki, w odniesieniu do wszystkich plików wtyczki, nazw funkcji, zmiennych oraz wszelkich pozostałych elementów. Nazwy te powinno się tworzyć z małych liter a jako separatora używać myślnika.

Np.: pn_fk_update_options() – inicjały oznaczają: pn – Paweł Nowak, fk – formularz kontaktowy.

To pozwoli nadać funkcji unikalną nazwę i zmniejszyć prawdopodobieństwo, że ktoś na świecie już takiej używa. Ryzyko konfliktu maleje zatem praktycznie do zera.

Ta sama zasad dotyczy nazw zmiennych. Zauważ, że zmienna $post jest zmienną globalną WordPressa, to znaczy, że dostęp do niej może mieć każdy inny komponent. Gdyby twoja funkcja nadpisała tą zmienną a nie daj Boże inna wtyczka chciałaby z niej skorzystać, może powstać poważny problem i wtedy szukaj wiatru w polu. Dochodzenie do przyczyny może być trudne jeżeli nie będziesz znał dobrze WordPressa.

 

Organizacja


Mówią na to – artystyczny nieład i twierdzą, że jest ekspresją ich osobowości, dzięki czemu mogą być prawdziwym sobą  i wyrażać się w twórczych pracach.

Kod to też poezja. Jednak Tu musisz zachować ład i porządek.

Organizacja plików i katalogów pozwoli Ci się odnaleźć, kiedy ich liczba zacznie rosnąć i kiedy przyjdzie Ci coś modyfikować.

Katalog wtyczki powinien zawierać tylko dwa pliki – podstawowy plik wtyczki i plik uninstall.php

 

Dlaczego?

Załóżmy np., że twoja wtyczka to potężny zbiór plików PHP, rozbudowanych funkcji, szablonów HTML, obrazków, arkuszy stylów i plików JavaScript. Trzymanie tego w jednym tylko katalogu narobiłoby niezłego burdelu. Zamiast potykać się o własne śmieci, można je posegregować kategoriami – w pod-katalogi  – każdy ląduje do takiego jakiego jest typu.

Dodatkowo zaleca się podział wtyczki na mniejsze kawałki – jest to kwestia wydajności – oddzielenie tego co ma działać po stronie administracyjnej od tego co zobaczysz po stronie interfejsu użytkownika (z ang. back end i front end), dzięki czemu możesz w łatwy sposób dodawać warunki (conditional tags) według tego, gdzie w danym momencie znajduje się użytkownik np.:

if (is_admin() ) {
 //wykonaj kod
}

 

Struktura katalogu.

Zawsze wrzucaj pliki do podfolderów o nazwie określającej jej typ. Niech właściwym wzorem do naśladowania będzie ten przykład poniżej.

Drzewo katalogu wtyczki:

Wchodzisz do katalogu wtyczki i od razu widzisz, że robił to ktoś z profesjonalnym podejściem. Takie właśnie praktyki stosuj.

Kiedy pakujesz pliki wtyczki do archiwum zip, powinny się one znajdować w katalogu o tej samej nazwie co plik główny wtyczki i zgodnie z zasadą nazewnictwa, bowiem kiedy WordPress instaluje wtyczkę w kokpicie, najpierw ją rozpakowuje a potem wrzuca do katalogu plugins. Pomyśl sobie jaki byłby bałagan, gdyby wszystkie wtyczki się tak instalowały. Po pierwsze większość z nich przestała by pewnie działać prawidłowo.

Jest to struktura logiczna i przejrzysta. Nie zapominaj, że robisz tylko sobie krzywdę nie stosując się do tych zasad. Zanim „wypuścisz” wtyczkę w kosmos, przyjdzie ci ją często modyfikować, poprawiać. Mając ład i porządek w plikach, nie będziesz błądził.

 

Nagłówki


Podobnie jak w przypadku motywów, WP rozpoznaje dany pakiet plików jako wtyczkę po specyficznym nagłówku umieszczonym na samym początku podstawowego pliku wtyczki. Wygląda on tak:

/*
Plugin Name: Unikalna Nazwa Wtyczki
Plugin URI: http://adres_URL_do_wtyczki
Description: Krótki i rzeczowy opis wtyczki.
Version: 1.0
Author: Programista tworzący kod
Author URI: http://adres_URL_autora
License: GPL2
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Domain Path: /languages
Text Domain: unikalny-identyfikator
*/

 

Zawsze pomiędzy: Plugin nameText Domain, nazwą pliku wtyczki i nazwą katalogu występuje zależność a raczej powinna taka występować. Należy o tym pamiętać. Np. Text Domain zawsze powinna być tworzona na podstawie Plugin Name a katalog z plikami wtyczki o tej samej nazwie co Text Domain. Kiedy zaczniesz testować swoje wtyczki tym narzędziem, szybko zrozumiesz o co chodzi i dlaczego to takie ważne.

Co oznaczają poszczególne nazwy?

Plugin Name – to po prostu nazwa wtyczki tworzona zgodnie z zasadą nazewnictwa.

Plugin URI – adres URL do wtyczki gdzie ją można pobrać. W przypadku tych darmowych, będzie to zazwyczaj odnośnik do repo WP a płatnych, odnośnik do stron trzecich.

Description – krótki i rzeczowy opis. W kilku zdaniach opisujesz co robi wtyczka. Element strategiczny z punktu widzenia marketingowego.

Version – wersja wtyczki. Na jej podstawie WP rozpoznaje m.in czy w repo znajduje się jej nowa wersja. Jak tak, to WP informuje Cię o nowej aktualizacji.

Author i Author URI –  to  programista, który pisał wtyczkę, ale równie dobrze może to być jakaś organizacja, firma itd. Odnośnikiem może być adres twojej witryny lub profil na WordPressie.

LicenseLicense URI – to informacje o licencji, jej rodzaju i adresu do pełnej wersji. Zawsze powinieneś umieszczać informacje na jakich warunkach wtyczka może być wykorzystywana. Niektóre wersje komercyjne nie zezwalają np. na instalacje więcej niż jednej wtyczki tj. jak masz więcej witryn, to wtyczkę możesz umieścić tylko na jednej z nich. W przypadku wtyczek umieszczonych w repo WP, licencja zawsze jest ta sama: GPL2

Domain Path – informacja dla WP, w jakiej lokalizacji znajduje się pakiet językowy.
Text Domain – unikalny identyfikator stosowany w tłumaczeniach, po którym WP rozpoznaje, że dany pakiet językowy należy do tej wtyczki. Są to funkcje gettext i należy ich używać jeżeli chcesz przygotować wtyczkę pod obsługę wielu języków.

Kiedy zajrzysz do zakładki Wtyczki w kokpicie, zobaczysz tam listę wtyczek. Informacje, które widzisz pochodzą właśnie z nagłówka. Masz więc zatem odniesienie, co gdzie może się znajeźć i w ten sposób wiesz jak tego używać.

Przykład:

Tabele Cenowe | Piszemy Pierwszą Prostą Wtyczkę Do WordPressa

 

Standardy tworzenia kodu


Oficjalną i obszerną listę dotyczącą standardów tworzenia kodu możesz znaleźć w dokumentacji:

https://codex.wordpress.org/WordPress_Coding_Standards

Nawet w kodzie można się czasami zgubić. Ściśnięty do granic możliwości, bez wcięć i spacji kod staje się zlepkiem nieczytelnego tekstu, który aż prosi się, żeby coś z nim zrobić.

Pamiętaj, że kod nie tylko jest dla maszyny. Musi być czytelny również dla ludzi. Przerzucanie instrukcji do nowych linii, stosowanie tabulacji, odstępów i komentarzy – to wszystko ma w sobie wyższy cel.

Kiedy patrzysz na tak starannie ułożony kod, zaczyna do ciebie docierać, że i w programowaniu można dostrzec elementy sztuki.

Tak. Pisanie kodu to sztuka. Ułożenie instrukcji tak aby wizualnie dawał efekt arcydzieła malarskiego. Określenie Kod To Poezja jest więc nie przypadkowe. Lecz nie tylko sam efekt wizualny się liczy. Liczy się również jakość. Dlatego powstały pewne standardy formatowania kodu.

 

W tym artykule poznasz te uniwersalne, najczęściej używane, które występują w większości języków programowania takich jak: HTML, CSS, JavaScript i PHP.

Nie będziemy się natomiast rozdrabniać pomiędzy nimi z osobna, ponieważ każdy z nich ma swoje własne, specyficzne dla danego języka zasady. Jeżeli chcesz je poznać, musisz zacząć się ich uczyć.

Np. w PHP używanie cudzysłowu pojedynczego lub podwójnego na ogromne znaczenie, bowiem użycie ich lub nie, decyduje czy ma zajść interpolacja czy nie.

Oto więc kilka z nich, o których należy teraz wspomnieć:

 

Dokumentacja


Zawsze twórz dokumentacje, choćby nie wiem co. Nie wyobrażam sobie jakiejś funkcji, która z niewiadomych przyczyn pojawiła się w kodzie i trzeba teraz domyślać się do czego może służyć. Twórz zatem dokumentację.

Dokumentacja to nie tylko pliki readme.txt z instrukcją obsługi, ale również są to komentarze, krótkie dopowiastki od programisty, które są bardzo pomocne, zwłaszcza gdy nie jesteś autorem kodu. Mają Ci one wyjaśnić w skrócie co robi funkcja. W języku PHP możemy używać kilku rodzajów komentarzy.

Oto one:

/*
* To jest komentarz blokowy
* Używamy go gdy chcemy dopisać dłuższą instrukcje
* która składa się z więcej niż jednej linii  
* Musi być on zawsze zamknięty!
* inaczej kod znajdujący się za nim, będzie potraktowany jako Komentarz!
* Przykładem takiego komentarza, jest nagłówek wtyczki
*/

# to jest komentarz liniowy pochodzący z języka C + 

# rozpoczynasz go znakiem hash i działa tylko do końca linii 

// i to jest komentarz liniowy 

// ten komentarz też działa tylko do końca linii! 

/* takiego komentarza używasz w plikach css i musi być zawsze zamknięty! */ 

<!-- a takiego w plikach HTML -->

 

Z tego typu komentarzami spotkasz się bardzo często przeglądając pliki źródłowe WordPressa. Więcej o nich możesz przeczytać z Wikipedi.

 

Małe i duże litery


Pomimo, że PHP rozróżnia wielkość liter czyli, że zmienna o nazwie $update nie jest tą samą zmienną o nazwie $Update z dużej litery, nazwy funkcji i zmiennych zawsze zapisuj małą literą a jako separatora używaj podkreślenia. Odróżni to zmienne od stałych i instrukcji SQL np.:

function update_options ( $update_options ) {
        //wykonaj kod
}

 

Apostrof i cudzysłów


Są używane do wprowadzania ciągu tekstowego, który ma być wyświetlony bezpośrednio w przeglądarce. Zawsze występują parami! To znaczy, że rozpoczynasz i kończysz tekst zawsze tym samym znakiem. Jest to częsty błąd popełniany na początku. Na szczęście jeżeli używasz dobrego edytora PHP i o tym zapomnisz, edytor w odpowiednim momencie podświetli składnie właściwym, zazwyczaj szarym kolorem.

Zaleca się aby zawsze używać apostrofów, z jednego ważnego powodu. Często będziesz używał znaczników HTML a znaczniki te mogą posiadać dodatkowe atrybuty, których wartości zawsze zawarte są pomiędzy cudzysłowie. Wyobraź sobie teraz jeżeli zawarłbyś tekst pomiędzy cudzysłów. Gdyby interpreter napotkał drugi (do pary) cudzysłów, odczytałby go jako koniec ciągu czyli reszta byłaby traktowana jako element PHP! Do tego nie można dopuścić, bo spowoduje to wystąpienie błędu i zatrzymanie się przetwarzania skryptu. Interpreter „nie rozumie” co znajduje się w dalszej części, bo przecież był to element HTML a nie PHP.

Przykład:

echo '<a href="aktywny_link" target="_blank">KLIK</a>';

Jedynym przypadkiem, w którym należy używać cudzysłów jest ten kiedy chcemy aby zmienna przeszła interpolacje, czyli wtedy, kiedy zostaje ona zamieniona na przypisaną wcześniej wartość.

echowynik testu: $update";

Wstawienie linka oznaczałoby zamianę cudzysłowu na apostrofy w każdym miejscu skryptu:

echo "<a href='$update'  target='_blank'>KLIK</a>";

Albo jeszcze inaczej. Można z tego wybrnąć przy użyciu magicznej kropki:

echo '<a href="http://wpsolucje.pl/admin.php?page=' . $update . '"  target="_blank">KLIK</a>';

 

 

Wcięcia


Wcięcia nadają całej strukturze kodu bardziej logicznego charakter i od razu można wychwycić jej sens. Używamy do tego tabulacji, nie spacji.

Np. kod:

if ( warunek ) { // wykonaj kod } else { //jednak ten kod wykonaj }

będzie mniej czytelny niż kod zapisany tak:

if (warunek ) {
   // wykonaj kod
} else {
   // jednak ten kod wykonaj
}

 

Spacje


Używamy ich po obu stronach operatorów logicznych i po przecinku. Przykład:

if ( $foo == $bar )foreach ( $foo as $bar ) array = ( 1, 2, 3, 4 ) itd.

 

Uwaga! Pamiętaj, że dla maszyny spacje, tabulacje, wcięcia i przejścia do nowej linii (potocznie zwane enterem!) nie mają znaczenia. Mają natomiast znaczenie dla ciebie, człowieka. Nadają strukturze kodu czytelności.

 

Skrócone znaczniki PHP


Ze względu na przenośność wtyczek i różne konfiguracje serwerów, w WordPressie nie używamy skróconych znaczników PHP tego typu:

<? i ?>

ZAWSZE używamy długich:

<?php i ?>

Temat nie podlega dyskusji.

 

Polecenia SQL


Polecenia SQL czyli instrukcje baz danych, zawsze zapisuj z DUŻEJ litery. Nie jest to obowiązek a raczej kwestia estetyczna, umowna. Choć w zapytaniach do bazy danych wielkość liter nie ma znaczenia, zapisywanie je dużymi literami pozwoli odróżnić je od funkcji PHP.

Przykład:

SELECT * FROM users WHERE ID=$s

Polecenie oznacza:

WYBIERZ wszystko(*) Z tabeli users GDZIE id=wartość zmiennej $es

 

Podsumowanie

W tym artykule mogłeś przeczytać o zasadach tworzenia wtyczki. Najpierw tworzysz dla siebie a potem dla innych. Kiedy po wielu miesiącach przyjdzie Ci wrócić do starego kodu, jego przejrzystość, ład i porządek zaskoczą Cię na nowo a praca będzie przyjemniejsza i krótsza!

I pamiętaj:

 

kod ( to ) {poezja;}


Otagowano: , , , , , ,

Kategoria: Wtyczki

Jedna odpowiedź do “Piszemy pierwszą, prostą wtyczkę do WordPressa #część 1”  


Napisz odpowiedź lub dodaj komentarz


Twój adres e-mail nie będzie opublikowany. Pola oznaczone gwiazdką * są wymagane

Możesz używać tych znaczników HTML: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>