Funkcje wbudowane, czyli korzystanie z dokumentacji

Jak już mówiłem na początku tego rozdziału, w PHP posiadamy wiele wbudowanych funkcji. Wiedzę z nich należy czerpać z dokumentacji. Dostępna jest ona pod adresem: www.php.net/manual/en/.

Chciałbym teraz pokrótce opowiedzieć co i jak można w niej odnaleźć, gdyż umiejętność pracy z dokumentacją jest bardzo ważna. Gdy chcesz coś zrobić, a nie wiesz jak to zrobić, w pierwszej kolejności należy udać się do swojej ulubionej wyszukiwarki internetowej. Tam, najlepiej po angielsku, należy krótko hasłami wpisać oczekiwaną rzecz. W momencie, gdy już kojarzymy jakiej funkcji potrzeba, a nie pamiętamy szczegółów, możemy też rzecz jasna zerknąć bezpośrednio do dokumentacji. Być może takie porady i poniższy przewodnik wyda Ci się wręcz śmieszny, ale uwierz mi, że naprawdę jest masa osób, które mają z tym problem.

Do rzeczy. Wyobraźmy sobie więc, że chcemy sprawdzić przykładowo, czy jakaś wartość jest stringiem. Nigdy wcześniej tego nie robiliśmy, nie mamy pomysłu co robić. Otwieramy więc wyszukiwarkę i staramy się opisać, o co nam chodzi:

Już w pierwszych wynikach widać, że dostaliśmy linka prosto do dokumentacji (www.php.net/manual/en/function.is-string.php), a opis wygląda jak to, czego byśmy potrzebowali. Otwieramy i widzimy:

Zaraz pod nazwą funkcji wymienione są wersje języka, w których jest ona dostępna. Następnie widzimy krótki opis, mówiący jednym zdaniem co robi dana funkcja. W sekcji „Description” mamy pełny opis funkcji, wraz z pokazanym zapisem funkcji:

is_string ( mixed $value ) : bool

A co on oznacza? Najpierw mamy nazwę funkcji. W nawiasach jest informacja o argumentach, jakie należy przekazać do funkcji i ich typie - ten zapis powinien być już dla Ciebie znajomy, wygląda jak zapis argumentów w kodzie. Podobnie mogą tu być określone wartości domyślne po znaku = czy typy. mixed oznacza dopuszczenie wartości dowolnego typu. Na końcu, po dwukropku, mamy określone, jakiego typu dane zwraca funkcja, zapis również podobny do właściwego określania typu.

Finalnie dowiedzieliśmy się, że aby sprawdzić, czy dana wartość będzie stringiem, możemy użyć funkcji o nazwie is_string. Przekazujemy jej jeden argument dowolnego typu, który będzie zmienną/wartością do sprawdzenia. W odpowiedzi dostaniemy wartość typu bool, która będzie zawierała true jeśli wartość jest typu string lub false jeśli tak nie jest.

var_dump ( mixed $value , mixed ...$values ) : void

Poniżej są sekcje „Parameters” oraz „Return Values”. Jest to uszczegółowienie powyższego zapisu. Wypisane są argumenty i określone, czym dokładnie są. Podobnie z wartością domyślną, mamy dokładne informacje o tym, co czy ewentualnie w zależności od czego zostanie zwrócone.

Jeszcze niżej, w sekcji „Examples” pokazane są różne przykłady obrazujące działanie i przykładowe wykorzystanie danej funkcji. Czasem zdarzy się też dział „Notes” zawierający różne uwagi na temat opisywanej rzeczy. Na koniec już mniej istotne: „See Also” czyli proponowane podobne funkcje oraz „User Contributed Notes” - komentarze od użytkowników.

W zasadzie to na tyle. Oczywiście, ten przykład to prosta sytuacja, gdzie Google od razu wie, o co chodzi, a dokumentacja ma gotową odpowiedź. Z pewnością będzie wiele momentów, gdzie proste szukanie nie pomoże. Dodatkowo pamiętaj, że źródła są różne - czasem lepsze, czasem gorsze. Podobnie sposobów na zrobienie czegoś może być wiele. Niekoniecznie to, co będzie topowym wynikiem w wyszukiwarce, będzie poprawną czy jedyną najlepszą odpowiedzią. Tego jednak z czasem też będziesz się uczył. Ważne jest, aby próbować samemu szukać, rozwiązywać problemy i pogłębiać wiedzę.

Myślę, że nie było to trudne. Często widuję jednak sytuacje, na przykład na forach, gdy ktoś informuje pytającego, aby użył danej funkcji, a ten odpowiada, że nie wie jak to zrobić. Teraz już więc wiesz, że wystarczy otworzyć dokumentację, trochę poczytać i wszystko powinno stać się jaśniejsze. Dokumentacja Twoim przyjacielem! :)

Ćwiczenia

1. Jako ćwiczenie po tej lekcji możesz odwiedzić dokumentację i przejrzeć jak wygląda zapis informacji o wybranych przez siebie funkcjach.