PHP/Korzystanie z dokumentacji

Korzystanie z dokumentacji

Najważniejszym miejscem dla każdego programisty PHP jest dokumentacja projektu. Jest ona o tyle ważna, że informacja o nowościach w składni w pierwszej kolejności pojawia się właśnie tutaj. Źródła w rodzaju artykułów niekoniecznie są aktualizowane wraz z nowymi wersjami i nie można się na nich w pełni opierać. Dokumentacja przydaje się też przy poszukiwaniu nowych funkcji, modułów lub mało znanych możliwości.

Angielska wersja dokumentacji dostępna jest pod adresem www.php.net/manual/en. Istnieje także polska, lecz jest ona bardzo rzadko uaktualniana, a ilość i jakość przetłumaczonych rozdziałów pozostawiają nieco do życzenia. Przyjrzyjmy się zatem jej strukturze.

Dokumentacja PHP powstaje w oparciu o XML-ową aplikację DocBook, dlatego jej struktura jest bardzo uporządkowana. W całym tekście przyjęte są jednolite konwencje stylistyczne, a nawigacja jest intuicyjna. Kody źródłowe drukowane są na szarym tle, z kolorowaną składnią, jeżeli dotyczy ona źródeł PHP. W wielu miejscach umieszczone są uwagi, ostrzeżenia oraz porady. Na dole każdej strony znajduje się sekcja z komentarzami programistów. Naprawdę warto od niej zaczynać studiowanie dokumentacji, ponieważ często znajdują się tam o wiele ciekawsze przykłady użycia lub naprawdę przydatne sztuczki i algorytmy. Ilość komentarzy do najpopularniejszych funkcji jest ogromna i obejmuje niemal wszystko: własne implementacje, przykłady i komentarze odnośnie użycia, linki do artykułów oraz inne.

Instalacja PHP

Informacje dotyczące instalowania PHP znajdują się w rozdziale II. Opisane zostały tam przykłady oraz dodatkowe wiadomości dla wszystkich platform i serwerów. Nie wystarczą one jednak do skonfigurowania PHP do własnych potrzeb, ponieważ spis dyrektyw znajduje się gdzie indziej.

Spis dyrektyw konfiguracyjnych dla systemów Unix znajduje się w rozdziale IX ("Dodatki") i oznaczony jest literą "F": "Configure options". Nie zawiera on jednak spisu komend aktywujących poszczególne moduły. Te należy sobie odszukać na stronie poświęconej każdemu z nich.

Pozycję niżej znajduje się wykaz dyrektyw pliku php.ini, także bez listy modułów. Ogólnie wszystko, co związane z instalowaniem jakiegokolwiek rozszerzenia, znajduje się na poświęconej mu stronie dokumentacji w sekcji "Installation".

Składnia języka

Aby dowiedzieć się, jak przedstawia się składnia języka, należy zajrzeć do rozdziału "Language reference". Jest to typowy spis dostępnych komend, instrukcji oraz elementów wyrażeń ułożony tematycznie. Najbardziej przydatny będzie dla programistów mających już pewną wprawę w tworzeniu aplikacji oraz skryptów, gdyż opisy nie są tak przystępne, jak w kursach i książkach. Ich zadaniem jest dostarczenie wyczerpującej wiedzy o danym elemencie i wypisanie wszystkich możliwych zagadnień z nim związanych.

Rozdział poświęcony programowaniu obiektowemu jest zdublowany. W PHP 5 ten element został napisany całkowicie od nowa, tracąc część kompatybilności ze starymi wersjami i stąd konieczność podania dwóch osobnych opisów w zależności od posiadanej wersji. Do części dla PHP 4 polecamy już sięgać jedynie z powodów historycznych.

"Security" oraz "Features"

W tych dwóch rozdziałach znajdują się informacje praktyczne pokazujące niektóre aspekty charakterystyczne dla PHP. Tutaj możesz dowiedzieć się o:

1. Ładowaniu plików na serwer
2. Bezpieczeństwie skryptów
3. Kilku niezbyt lubianych przez programistów opcjach: Register globals oraz Magic quotes.
4. Metodach raportowania błędów
5. Obsłudze ciastek i sesji
6. Pisaniu skryptów dla tzw. trybu bezpiecznego wykorzystywanego na produkcyjnych serwerach.

Spis funkcji

Jest to jeden z najważniejszych rozdziałów dla programisty. Zawiera spis wszystkich funkcji pogrupowanych według modułów. Na początku każdego podrozdziału znajduje się skrótowy opis rozszerzenia, wymagania oraz sposób jego zainstalowania. Należy tu zwrócić uwagę na następujące frazy:

No external libraries are needed to build this extension.

To rozszerzenie nie wymaga obecności żadnych dodatkowych bibliotek w systemie.

There is no installation needed to use these functions; they are part of the PHP core.

Funkcje te są częścią jądra PHP i nie da się ich wywalić. Są zatem zawsze dostępne.

The SimpleXML extension is enabled by default. To disable it, use the --disable-simplexml configure option.

Komunikat w tym stylu oznacza, że domyślnie rozszerzenie to jest zawsze aktywne, ale istnieje możliwość jego wyłączenia.

Następnie na stronie znajduje się kilka prostych przykładów i lista stałych definiowanych przez dany moduł. Na końcu wyszczególniony jest alfabetyczny spis wszystkich funkcji modułu wraz z lakonicznie zaznaczonym działaniem. Aby dowiedzieć się więcej, należy po prostu kliknąć na wybraną funkcję.

Opis funkcji zaczyna się od składni. Wygląda on mniej więcej tak:

bool setcookie ( string name [, string value [, int expire [, string path [, string domain [, bool secure]]]]] )

Zaczyna się on od nazwy typu danych zwracanego przez funkcję. W dokumentacji stosowana jest następująca konwencja:

• int, string, float, bool - skalarne typy danych: liczby, ciągi tekstowe, wartości logiczne.
• array - tablica
• mixed - funkcja może zwrócić jeden z kilku rodzajów typów. W tym wypadku trzeba samodzielnie doczytać w opisie, co jest zwracane w jakich sytuacjach.

Jeżeli funkcja zwraca obiekt, podawana jest jego nazwa.

W nawiasach okrągłych podany jest spis parametrów, również z zaznaczonymi typami. Nawiasy kwadratowe oznaczają parametry opcjonalne. Z podanego powyżej przykładu wynika, że możemy podać:

1. nazwę
2. nazwę i wartość
3. nazwę, wartość i czas wygaśnięcia
4. nazwę, wartość, czas wygaśnięcia i ścieżkę
5. nazwę, wartość, czas wygaśnięcia, ścieżkę i domenę
6. nazwę, wartość, czas wygaśnięcia, ścieżkę, domenę oraz nakaz wysłania ciastka połączeniem szyfrowanym

Dokładniejsze informacje, co robi jaki parametr, znajdują się w opisie funkcji. Kończy się on sekcją "See also" odsyłającą do funkcji podobnych lub uzupełniających zawarte tu informacje.

W przypadku nowych, obiektowych rozszerzeń, nazwa funkcji jest dwuczęściowa: obiekt::funkcja.

Do PHP stworzono już bardzo dużo modułów i ogrom ich spisu może przerazić. Oto krótki przewodnik, gdzie co można znaleźć:

1. Arrays - wszystko, co związane z tablicami
2. ctype - sprawdzanie zawartości ciągów tekstowych
3. Exif - wyciąganie dodatkowych informacji z plików JPG i TIFF
4. Filesystem - operacje na plikach
5. Function handling - zarządzanie funkcjami
6. HTTP - kilka funkcji do protokołu HTTP (np. wysyłanie ciastek)
7. Image functions - biblioteka GD do generowania obrazków
8. Math - funkcje matematyczne
9. Misc. - funkcje niepasujące nigdzie indziej (np. kolorowanie składni)
10. MySQL - najstarszy zbiór funkcji do komunikacji z bazą MySQL
11. mysqli - "Improved MySQL", komunikacja z nowymi wersjami bazy MySQL.
12. Network - funkcje sieciowe
13. Output Control - buforowanie wyjścia skryptu
14. PDO - biblioteka PDO do komunikacji z różnymi bazami danych, którą niebawem poznamy.
15. spl - "Standard PHP Library", obiektowe nakładki na wiele podstawowych operacji.
16. Strings - operacje na ciągach tekstowych
17. Variables handling - rozpoznawanie typów zmiennych itd.

Zachęcamy do przejrzenia tych rozdziałów i zorientowania się w ich strukturze. Dobra orientacja w dokumentacji PHP sprawia, że nie trzeba nawet przykładać dużej wagi do "wkuwania" funkcji na pamięć.