4.2     How to read function prototypes

This is NOT the latest copy of this book; click here for the latest version.

The standardised way to describe the parameters accepted and value returned from a function is through a function prototype. They are used throughout this book and also online in the PHP manual. Once you are practised in the art of reading a function prototype, you should be able to have a rough understanding of how to use a function just by reading its prototype. However, you need not understand how function prototypes work in order to read this book - all the functions used are explained textually, with the prototypes presented merely for convenience.

As they are used for each function shown in this book, it is important you understand them before proceeding. Do not worry what each function does right now, as they will each be explained in the coming pages. I have taken each function prototype directly from the PHP manual so that you should be able to flick to and from the manual easily. Here is the prototype for a basic function, strtoupper():

What that means is that the function takes one string and returns a string. The reason it says "string string" is because the PHP manual usually describes what each parameter does, and so it names each parameter. Here it is telling us that strtoupper() takes one parameter, a string, which is called "string" - not the best of naming schemes, I agree, but it makes sense. It also returns a string - the manual puts the return type before the function name, as with most C-like languages.

If a function uses a parameter as a reference, that parameter will be preceded in the prototype by an ampersand. This does not mean you have to use a prototype in your function call, it is just there to remind you that the parameter is a reference.

Now consider the prototype for sha1():

As you can see, sha1() returns a string, takes a string as its first parameter, with a boolean as its second parameter. However, the boolean is in square brackets - this has a special meaning, which is "this is an optional parameter".

The optional parameters can sometimes appear a little confusing, as is amply demonstrated by the definition for mysql_connect():

Every parameter in mysql_connect() is optional because PHP has default values for each of them if you do not provide them. The prototypes also include two special data types: "number", and "mixed". A number is any floating-point or integer number, and "mixed" means it accepts or returns two or more data types.

The definition of the pow() function, for example, is this:

It accepts any numbers and can return any numbers. The definition of serialize(), however, is this:

When you get to work using serialize(), you will find that it works with both objects and classes, which is why the parameter to serialize() is "mixed". There is also one data type called "void", which means "no return value" or "no parameters taken".

The final convention used in function prototypes is "...", which means "a variable number of parameters are taken". For example, the prototype for the isset() function is this:

There it takes a minimum of one variable, but it can accept many because of the optional "...".