Arguments and Return Values

Every function call consists of the function name followed by a list of arguments in parentheses. If there is more than one argument, the list items are separated with commas. Some functions do not require any arguments at all, but a pair of parentheses is still requiredeven if there are no arguments contained in them.

The built-in function phpinfo generates a web page that contains a lot of information about the PHP module. This function does not require any arguments, so it can be called from a script that is as simple as

 <?php phpinfo();?> 

If you create this script and point a web browser at it, you will see a web page that contains system information and configuration settings.

Returning Success or Failure

Because phpinfo generates its own output, you do not need to prefix it with echo, but, for the same reason, you cannot assign the web page it produces to a variable. In fact, the return value from phpinfo is the integer value 1.

Returning True and False Functions that do not have an explicit return value usually use a return code to indicate whether their operation has completed successfully. A zero value (FALSE) indicates failure, and a nonzero value (TRUE) indicates success.

The following example uses the mail function to attempt to send an email from a PHP script. The first three arguments to mail specify the recipient's email address, the message subject, and the message body. The return value of mail is used in an if condition to check whether the function was successful:

 if (mail("[e-mail]",           "Hello", "This is a test email")) {   echo "Email was sent successfully"; } else {   echo "Email could not be sent"; } 

If the web server that this script is run on is not properly configured to send email, or if there is some other error when trying to send, mail will return zero, indicating that the email could not be sent. A nonzero value indicates that the message was handed off to your mail server for sending.

Return Values Although you will not always need to test the return value of every function, you should be aware that every function in PHP does return some value.

Default Argument Values

The mail function is an example of a function that takes multiple arguments; the recipient, subject, and message body are all required. The prototype for mail also specifies that this function can take an optional fourth argument, which can contain additional mail headers.

Calling mail with too few arguments results in a warning. For instance, a script that contains the following:

 mail("[e-mail]", "Hello"); 

will produce a warning similar to this:

 Warning: mail() expects at least 3 parameters, 2 given in /home/chris/mail.php on line 3 

However, the following two calls to mail are both valid:

 mail("[e-mail]", "Hello", "This is a test email"); mail("[e-mail]", "Hello", "This is a test email",      "Cc: [e-mail]"); 

To have more than one argument in your own function, you simply use a comma-separated list of variable names in the function definition. To make one of these arguments optional, you assign it a default value in the argument list, the same way you would assign a value to a variable.

The following example is a variation of add_tax that takes two argumentsthe net amount and the tax rate to add on. $rate has a default value of 10, so it is an optional argument:

 function add_tax_rate($amount, $rate=10) {   $total = $amount * (1 + ($rate / 100));   return($total); } 

Using this function, the following two calls are both valid:

 add_tax_rate(16); add_tax_rate(16, 9); 

The first example uses the default rate of 10%, whereas the second example specifies a rate of 9% to be usedproducing the same behavior as the original add_tax function example.

Optional Arguments All the optional arguments to a function must appear at the end of the argument list, with the required values passed in first. Otherwise, PHP will not know which arguments you are passing to the function.

Variable Scope

The reason values have to be passed in to functions as arguments has to do with variable scopethe rules that determine what sections of script are able to access which variables.

The basic rule is that any variables defined in the main body of the script cannot be used inside a function. Likewise, any variables used inside a function cannot be seen by the main script.

Scope Variables available within a function are said to be local variables or that their scope is local to that function. Variables that are not local are called global variables.

Local and global variables can have the same name and contain different values, although it is best to try to avoid this to make your script easier to read.

When called, add_tax calculates $total, and this is the value returned. However, even after add_tax is called, the local variable $total is undefined outside that function.

The following piece of code attempts to display the value of a global variable from inside a function:

 function display_value() {   echo $value; } $value = 125; display_value(); 

If you run this script, you will see that no output is produced because $value has not been declared in the local scope.

To access a global variable inside a function, you must use the global keyword at the top of the function code. Doing so overrides the scope of that variable so that it can be read and altered within the function. The following code shows an example:

 function change_value() {   global $value;   echo "Before: $value <br>";   $value = $value * 2; } $value = 100; display_value(); echo "After: $value <br>"; 

The value of $value can now be accessed inside the function, so the output produced is as follows:

 Before: 100 After: 200