1. The php manual
On the official homepage of php you get besides the source code and downloads of php also the manual of php. It contains some basic information about php like installation and security but also a list of all functions which exists in php. These functions are grouped together in groups like String or MySQL.
2. Finding a function description
There are a lot of function descriptions in the manual, however you must find the right one
for you. First you should check the whole function reference, specially in the
function groups. A function which should sort an array would be found in the
group Arrays, a function to change a text in a string would be found
in the group Strings. In such a group there is a list of
all functions which belongs to it. Each function got a short description what they do.
As an example you will find inside the group Arrays the function
sort with the short description Sort an array. A click on
this function gets you the description.
The easiest way for beginners (and the most annoying way for any helpers or forum moderators) is to simply ask in a forum or chat.
<user> I have a problem, I have an array in php but the values aren't sorted in any way.
How can I sort the array?
<helper> sort
<helper2> with usort
<helper3> do you know www.php.net?
<helber4> try it with sort()
You have ben kicked from #helpchannel by operator3 (sort(), and next time check the manual at www.php.net/manual)
In most cases its just a function name. There are several ways to get the function description out of the manual.
-
On the homepage there is a link documentation in the upper manual which gets you to the manual. As the manual is translated into several language you should alyways use the english version, as this is the most up to date version. Inside the english version is a chapter called Function Reference. As the function may be a function for array the function may be in the Arrays" section. At the bottom of this there is a sorted list of functions in this group. There you find the function sort with the description
Sort an array. Click on it and you get to the detailed description. -
On the homepage is an input field in the top right corner which allowes you to search on the homepage. It searchs in the function reference by default but can also be changed to search in the bug database or on the whole site. You can enter the function name inside the search and get the function description or a search result list with functions which sounds similar to the entered one.
-
The simpliest way is to open the url
http://www.php.net/FUNCTIONNAMEwhereFUNCTIONNAMEis the function to search for. This call automatically starts the search and redirects you to the function description.
3. How to read a function description
As you may want to read the function description in your native language you should however read it in english to get the most up to date version of the description. This can be done by selecting English in the drop down list in the top of the page.
After the name of the function there is an expression which shows in which php version this function exists and a short description of the function.
Now the detailed function description is followed. It starts with the
function signature. It contains the
return value, name of the function and the
parameter list. The return value shows
what kind of data the function is returning. The value void means no
value is returned. The parameter list shows which
parameter can be used. Every parameter got the syntax type $name or
type &$name. The type shows which type the parameter should be.
There are some special types which doesn't exists in php like number
for a float or int number. A list of
all pseudo types can be found at Pseudo-types
and variables used in this documenation. After the type there is the
name of the parameter. This name is also used in the function description itself.
If there is a & the parameter is used as a reference. If this
is the case the parameter must be a variable (and cannot be a static value) and
the function changes the content of the variable. Without the &
just a copy of the parameter is send to the function. If a parameter is written
in brackets the parameter is optional.
After the function signature there is the description about the function and its parameters. It use the same parameter names as in the parameter list above. These parameters are written in a monospace italic font. The detailed function description also contains some examples how to use the function and a detailed list of all parameters and how they work.
The return value is explained in a seperate section. For a return value of
void this section is omitted, for a return value of
mixed there is a lot of text which descripe which type is when
returned by this function.
There is also a changelog which explaines which parameters are implemented since which php version and how a function worked before or after a given php version.
The most functions got cross references to other similar functions. Maybe you read a function description which is not exactly what you want but may find the right function in the cross reference.
At the end there are user comments for each function. These explain some hints how to use the function and provides you with a lot of examples and experiances.
4. Function description for sort()
As an example we explain the function description for sort. This function exists in the php versions php4 and php5 and according to the short description this function is used to sort an array.
The function signature explaines this function returns a boolean value, the first parameter must be an array and the second parameter must be an integer value, if given. Independent how the function works all following programm lines are possible.
<?php
$a = array(4, 6, 10, -4);
$ret = sort($a);
$ret = sort($a, 4);
$ret = sort($a, 0);
sort($a, -400);
sort($a, 9*30-5);
sort($a, $a[0]); // possible as $a[0] got the value int(4)
?>
The function description got a text which explaines what the function do. In this case
it sorts the array ascending. Further it says it returns true if the
array is sorted or false if there was an error.
Since the second parameter can be any integer value only some of them makes sense.
The description explaines that you should use the values SORT_REGULAR,
SORT_NUMERIC, SORT_STRING or SORT_LOCALE_STRING
to get the given behavior of the function. It looks like these values are strings
and the function should be called with sort($a, "SORT_NUMERIC");, but thats
not true. First, the second parameter must be an integer, not a string. Second, parameters
or values written in uppercase are normally constants in php. If you check the
group Arrays again you see a list of predefined constants which
got the mentioned constants above. So you can use this constants for your function call.
<?php
sort($a, SORT_STRING);
sort($a, SORT_NUMERIC);
?>
As cross references a list of other sort function is shown and after that the user comments finishes the function description.
