Quakenet/#php Tutorial

Note: If you opened this page from an external URL pay attention that all chapters are linked together. Be sure you also read all prior chapters of this tutorial, otherwise you will miss relevant content explained before.

Layout of the php manual

  1. The php manual
  2. Finding a function description
  3. How to read a function description
  4. Function description for sort()

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.

  1. 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.

  2. 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.

  3. The simpliest way is to open the url http://www.php.net/FUNCTIONNAME where FUNCTIONNAME is 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(4610, -4);
$ret sort($a);
$ret sort($a4);
$ret sort($a0);
sort($a, -400);
sort($a9*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
($aSORT_STRING);
sort($aSORT_NUMERIC);
?>

As cross references a list of other sort function is shown and after that the user comments finishes the function description.

Questions about the chapter

No questions

Back to Next to
Copyright © to the OPs of #php/QuakeNet Valid XHTML 1.0 Strict Valid CSS!