Dość często zauważam, że początkujący programista PHP ma bardzo duże problemy z prawidłowym odczytywaniem dokumentacji PHP. Nie ma co ukrywać iż PHP nie należy do języków mocno uporządkowanych. Wiele funkcji jest niespójnych, zbliżone funkcje mają zmienioną kolejność argumentów. Choć sama dokumentacja przeszła przez ostatnie lata gruntowne zmiany, to jednak na samym początku nie do końca wiadomo na co zwracać uwagę.

Przyjrzyjmy się jak wygląda opis przykładowej funkcji in_array:

in_array

(PHP 4, PHP 5, PHP 7)

in_array — Checks if a value exists in an array

Description 
bool in_array ( mixed $needle , array $haystack [, bool $strict = FALSE ] )

Searches haystack for needle using loose comparison unless strict is set.

W nawiasie pod nazwą funkcji podane są wersje PHP (w tym przypadku 4, 5 oraz 7) w których dana funkcja występuje. in_array() pojawia się już w PHP 4, zatem możemy używać jej od bardzo dawna i być spokojnym że zadziała z każdą wersją PHP. Wraz z rozwojem języka dodawane były oczywiście nowe funkcje – i tak np. funkcja intdiv pojawiła się dopiero w PHP 7. Odwołanie się do niej np. w PHP 5 sprawi wyświetlenie komunikatu błędu.

Poniżej znajdziemy krótkie podsumowanie funkcji:

in_array — Checks if a value exists in an array (sprawdza czy wartość istnieje w tablicy)

Linia ta mówi nam pokrótce jaka jest rola danej funkcji, czego możemy się po niej spodziewać.

Opis jest najważniejszą częścią dokumentacji i to on sprawia największe problemy.

bool in_array ( mixed $needle , array $haystack [, bool $strict = FALSE ] )

Widzimy tutaj kilka typów danych:

- bool – typ boolean: prawda / fałsz
- array – typ tablicowy
- mixed – typ mieszany: może to być tak naprawdę dowolny z typów. Jest on uzależniony od kontekstu lub samej funkcji do której parametr przekazujemy. Jedna funkcja może przez mixed rozumieć tablicę i string a inna przyjmie wszystkie obsługiwane przez PHP typy.

Wszystkie dostępne typy wymienione są oczywiście w dokumentacji PHP i zalecam aby dokładnie zapoznać się z nimi. Bez zrozumienia tej części, praktycznie niemożliwa staje się dalsza praca.

Celem dalszej analizy rozbijmy jeszcze definicję funkcji na 2 części:

- bool in_array
- ( mixed $needle , array $haystack [, bool $strict = FALSE ] )

Fragment

bool in_array 

oznacza, iż funkcja in_array zwraca typ bool. Czyli, jeżeli szukany element będzie występował w tablicy, funkcja zwróci `true`, w przeciwnym wypadku `false`. To, jaki typ dana funkcja zwraca, jest jedną z najbardziej istotnych informacji. Umożliwia nam poprawne sprawdzanie warunków, prawidłowe przypisywanie wartości do zmiennych i wiele innych.

Dalej mamy informację o argumentach funkcji:

( mixed $needle , array $haystack [, bool $strict = FALSE ] )

W tym wypadku występują 3. Igła (mixed $needle) w stogu siana (array $haystack) z porównywaniem typów (bool $strict). Jest tu oczywiście trochę zabawy językowej. Nasza `igła` to wartość której szukamy w `stogu siana` czyli tablicy. Opis 3 argumentu zawiera dwie bardzo istotne informacje. Po pierwsze jest on opcjonalny, co oznaczone jest poprzez [ ], oraz ma zadeklarowaną wartość domyślną FALSE. Przy wywołaniu funkcji możemy go zatem pominąć i wtedy wyszukiwanie w tablicy nastąpi bez porównywania typów.

Zobaczmy na przykładzie jak to działa. Załóżmy że chcemy wyszukać wartość 1 w tablicy:

$tab = [ '1', 'Ania', true];

var_dump(in_array(1, $tab)); // zwróci true
var_dump(in_array(1, $tab, true)); // zwróci false

W pierwszym wypadku in_array() zwróci true, gdyż bez ścisłego porównywania typów w PHP, wartość integer 1==string ‘1’ zatem element istnieje w tablicy. Z porównywaniem typów (3 parametr ustawiony na true) warunek 1 === ‘1’ nie został spełniony czyli wartość nie została odnaleziona w tablicy.

W powyższych przykładach wywołując funkcję in_array() podstawiliśmy pod mixed $needle typ integer, pod array $haystack tablicę $tab i pod bool $strict – bool true / false. Co się stanie jeżeli przekazany do funkcji typ danych nie będzie zgadzał się z tym podanym w dokumentacji?

var_dump(in_array(1, 'powinna być tutaj tablica a jest string'));

// Warning:  in_array() expects parameter 2 to be array, string given in...

PHP wyświetliło bardzo czytelne ostrzeżenie iż 2 parametr powinien być typu tablicowego a przekazany został string.

Co znajduje się dalej w dokumentacji? Pod definicją funkcji występuje opis wszystkich argumentów. Czym są needle, haystack oraz strict. Bardzo często znajdziemy w tej sekcji dodatkowe uwagi jak np. ta dla needle, że w sytuacji gdy jest on stringiem porównywanie następuje z uwzględnieniem wielkości liter. Warto czytać takie ostrzeżenia dzięki którym unikniemy nieprzyjemnych niespodzianek.

Poniżej w sekcji `zwracane wartości` znajduje się opis, w jakiej sytuacji funkcja zwraca określony typ danych. Dla obiektów będzie tutaj uwzględniona informacja o rzucanych wyjątkach. Przykładowo PDO::prepare w przypadku niepowodzenia może rzucić wyjątkiem PDOException.

W przypadku in_array niżej znajdziemy już przykłady, ale niektóre funkcje posiadają jeszcze dodatkowe informacje. Tak jest dla sort którego opis zawiera `changelog`. Dowiemy się z niego jakie zmiany zachodziły w poszczególnych wersjach PHP, co zostało dodane, co zmienione. Jest to szczególnie istotne w przypadku gdy robimy poważny upgrade systemu ze starszej wersji PHP.

Skoro jesteśmy już przy sort() warto jeszcze zobaczyć definicję:

bool sort ( array &$array [, int $sort_flags = SORT_REGULAR ] )

Pojawił się tu nowy zapis `array &$array` – znak `&` oznacza referencję czyli funkcja sort() zmodyfikuje nam bezpośrednio zmienną przekazaną jako parametr. Jak widzimy funkcja zwraca wartość bool a nie np. posortowaną tablicę, zatem jest to jedyny sposób przekazania wyniku dalej. Dla porównania array_merge zwraca nową tablicę pozostawiając przekazane do niej zmienne nienaruszone.

Czasami warto zwrócić jeszcze uwagę na komentarze. Mogą zawierać dużo istotnych informacji i przykładów, niekiedy w komentarzach ktoś mógł już rozwiązać nurtujący nas problem.

Mam nadzieję że artykuł pomógł rozwiać niektóre wątpliwości. Na początek z całą pewnością ciężko jest się po dokumentacji poruszać, jednak jest nieodłączną częścią życia programisty. W sieci można oczywiście znaleźć porady czy przykłady, jednak to dokumentacja jest najbardziej aktualna i przydatna.

Macie pytania? Zadajcie je w komentarzach do poradnika. Postaram się odpowiedzieć na wszystkie niejasności.

• sieć
• http
• apache
• ssl
• php
• composer
• javascript
• jquery
• ajax
• html
• pdo
• sql server
• spl
• css
• sql
• mysql
• postresql
• mongodb
• psr
• programowanie
• regex