Calling a Function

Functions in a PHP program can be built in (or, by being in an extension, effectively built in) or user-defined. Regardless of their source, all functions are evaluated in the same way:

$someValue = function_name( [ parameter, ... ] );

The number of parameters a function requires differs from function to function (and, as we’ll see later, may even vary for the same function). The parameters supplied to the function may be any valid expression and must be in the specific order expected by the function. If the parameters are given out of order, the function may still run by a fluke, but it’s basically a case of “garbage in = garbage out.” A function’s documentation will tell you what parameters the function expects and what value(s) you can expect to be returned.

Here are some examples of functions:

// strlen() is a PHP built-in function that returns the length of a string
$length = strlen("PHP"); // $length is now 3
// sin() and asin() are the sine and arcsine math functions
$result = sin(asin(1)); // $result is the sine of arcsin(1), or 1.0

// unlink() deletes a file
$result = unlink("functions.txt"); 
// $result = true or false depending on success or failure

In the first example, we give an argument, "PHP", to the function strlen(), which gives us the number of characters in the provided string. In this case, it returns 3, which is assigned to the variable $length. This is the simplest and most common way to use a function.

The second example passes the result of asin(1) to the sin() function. Since the sine and arcsine functions are inverses, taking the sine of the arcsine of any value will always return that same value. Here we see that a function can be called within another function. The returned value of the inner call is subsequently sent to the outer function before the overall result is returned and stored in the $result variable.

In the final example, we give a filename to the unlink() function, which attempts to delete the file. Like many functions, it returns false when it fails. This allows you to use another built-in function, die(), and the short-circuiting property of the logic operators. Thus, this example might be rewritten as:

$result = unlink("functions.txt") or die("Operation failed!");

The unlink() function, unlike the other two examples, affects something outside of the parameters given to it. In this case, it deletes a file from the filesystem. All such side effects of a function should be carefully documented and carefully considered.

PHP has a huge array of functions already defined for you to use in your programs. These extensions perform tasks such as accessing databases, creating graphics, reading and writing XML files, grabbing files from remote systems, and more. PHP’s built-in functions are described in detail in the appendix.

Defining a Function

To define a function, use the following syntax:

function [&] function_name([parameter[, ...]])
{
 statement list
}

The statement list can include HTML. You can declare a PHP function that doesn’t contain any PHP code. For instance, the column() function simply gives a convenient short name to HTML code that may be needed many times throughout the page:

<?php function column()
{ ?>
 </td><td>
<?php }

The function name can be any string that starts with a letter or underscore followed by zero or more letters, underscores, and digits. Function names are case-insensitive; that is, you can call the sin() function as sin(1), SIN(1), SiN(1), and so on, because all these names refer to the same function. By convention, built-in PHP functions are called with all lowercase.

Typically, functions return some value. To return a value from a function, use the return statement: put return expr inside your function. When a return statement is encountered during execution, control reverts to the calling statement, and the evaluated results of expr will be returned as the value of the function. You can include any number of return statements in a function (for example, if you have a switch statement to determine which of several values to return).

Let’s take a look at a simple function. Example 3-1 takes two strings, concatenates them, and then returns the result (in this case, we’ve created a slightly slower equivalent to the concatenation operator, but bear with us for the sake of the example).

function strcat($left, $right)
{
 $combinedString = $left . $right;

 return $combinedString;
}

The function takes two arguments, $left and $right. Using the concatenation operator, the function creates a combined string in the variable $combinedString. Finally, in order to cause the function to have a value when it’s evaluated with our arguments, we return the value $combinedString.

Because the return statement can accept any expression, even complex ones, we can simplify the program as shown here:

function strcat($left, $right)
{
 return $left . $right;
}

If we put this function on a PHP page, we can call it from anywhere within the page. Take a look at Example 3-2.

<?php
function strcat($left, $right)
{
 return $left . $right;
}
$first = "This is a ";
$second = " complete sentence!";

echo strcat($first, $second);

When this page is displayed, the full sentence is shown.

In this next example a function takes in an integer, doubles it by bit-shifting the original value, and returns the result:

function doubler($value)
{
 return $value << 1;
}

Once the function is defined, you can use it anywhere on the page. For example:

<?php echo "A pair of 13s is " . doubler(13); ?>

You can nest function declarations, but with limited effect. Nested declarations do not limit the visibility of the inner-defined function, which may be called from anywhere in your program. The inner function does not automatically get the outer function’s arguments. And, finally, the inner function cannot be called until the outer function has been called, and also cannot be called from code parsed after the outer function:

function outer ($a)
{
 function inner ($b)
 {
 echo "there $b";
 }

 echo "$a, hello ";
}

// outputs "well, hello there reader"
outer("well");
inner("reader");

Variable Scope

If you don’t use functions, any variable you create can be used anywhere in a page. With functions, this is not always true. Functions keep their own sets of variables that are distinct from those of the page and of other functions.

The variables defined in a function, including its parameters, are not accessible outside the function, and, by default, variables defined outside a function are not accessible inside the function. The following example illustrates this:

$a = 3;

function foo()
{
 $a += 2;
}

foo();
echo $a;

The variable $a inside the function foo() is a different variable than the variable $a outside the function; even though foo() uses the add-and-assign operator, the value of the outer $a remains 3 throughout the life of the page. Inside the function, $a has the value 2.

As we discussed in Chapter 2, the extent to which a variable can be seen in a program is called the scope of the variable. Variables created within a function are inside the scope of the function (i.e., have function-level scope). Variables created outside of functions and objects have global scope and exist anywhere outside of those functions and objects. A few variables provided by PHP have both function-level and global scope (often referred to as super-global variables).

At first glance, even an experienced programmer may think that in the previous example $a will be 5 by the time the echo statement is reached, so keep that in mind when choosing names for your variables.

global var1, var2, ... ;

$a = 3;

function foo()
{
 global $a;

 $a += 2;
}

foo();
echo $a;

global $var;
$var = & $GLOBALS['var'];

static var [= value][, ... ];

<?php
function counter()
{
 static $count = 0;

 return $count++;
}

for ($i = 1; $i <= 5; $i++) {
 print counter();
}

Function Parameters

Functions can expect an arbitrary number of arguments, declared by the function definition. There are two different ways to pass parameters to a function. The first, and more common, is by value. The second is by reference.

<?php
function doubler(&$value)
{
 $value = $value << 1;
}

$a = 3;
doubler($a);

echo $a;

function getPreferences($whichPreference = 'all')
{
 // if $whichPreference is "all", return all prefs;
 // otherwise, get the specific preference requested...
}

function getPreferences()
{
 // some code
}

$array = func_get_args();
$count = func_num_args();
$value = func_get_arg(argument_number);

<?php
function countList()
{
 if (func_num_args() == 0) {
 return false;
 }
 else {
 $count = 0;

 for ($i = 0; $i < func_num_args(); $i++) {
 $count += func_get_arg($i);
 }

 return $count;
 }
}

echo countList(1, 5, 9); // outputs "15"

foo(func_num_args());

$count = func_num_args();
foo($count);

function takesTwo($a, $b)
{
 if (isset($a)) {
 echo " a is set
";
 }

 if (isset($b)) {
 echo " b is set
";
 }
}

echo "With two arguments:
";
takesTwo(1, 2);

echo "With one argument:
";
takesTwo(1);
With two arguments:
 a is set
 b is set
With one argument:
Warning: Missing argument 2 for takes_two()
 in /path/to/script.php on line 6
a is set

class Entertainment {}

class Clown extends Entertainment {}

class Job {}

function handleEntertainment(Entertainment $a, callable $callback = NULL)
{
 echo "Handling " . get_class($a) . " fun
";

 if ($callback !== NULL) {
 $callback();
 }
}

$callback = function()
{
 // do something
};

handleEntertainment(new Clown); // works
handleEntertainment(new Job, $callback); // runtime error

Return Values

PHP functions can return only a single value with the return keyword:

function returnOne()
{
 return 42;
}

To return multiple values, return an array:

function returnTwo()
{
 return array("Fred", 35);
}

If no return value is provided by a function, the function returns NULL instead. You can set a return data type by declaring it in the function definition. For example, the following code will return an integer of 50 when it is executed:

function someMath($var1, $var2): int
{
 return $var1 * $var2;
}

echo someMath(10, 5);

By default, values are copied out of the function. To return a value by reference, prepend the function name with & both when declaring it and when assigning the returned value to a variable:

$names = array("Fred", "Barney", "Wilma", "Betty");

function &findOne($n) {
 global $names;

 return $names[$n];
}

$person =& findOne(1); // Barney
$person = "Barnetta"; // changes $names[1]

In this code, the findOne() function returns an alias for $names[1] instead of a copy of its value. Because we assign by reference, $person is an alias for $names[1], and the second assignment changes the value in $names[1].

This technique is sometimes used to return large string or array values efficiently from a function. However, PHP implements copy-on-write for variable values, meaning that returning a reference from a function is typically unnecessary. Returning a reference to a value is slower than returning the value itself.

Variable Functions

As with variable variables where the expression refers to the value of the variable whose name is the value held by the apparent variable (the $$ construct), you can add parentheses after a variable to call the function whose name is the value held by the apparent variable—for example, $variable(). Consider this situation, where a variable is used to determine which of three functions to call:

switch ($which) {
 case 'first':
 first();
 break;

 case 'second':
 second();
 break;

 case 'third':
 third();
 break;
}

In this case, we could use a variable function call to call the appropriate function. To make a variable function call, include the parameters for a function in parentheses after the variable. To rewrite the previous example:

$which(); // if $which is "first", the function first() is called, etc...

If no function exists for the variable, a runtime error occurs when the code is evaluated. To prevent this, before calling the function you can use the built-in function_exists() function to determine whether a function exists for the value of the variable:

$yesOrNo = function_exists(function_name);

For example:

if (function_exists($which)) {
 $which(); // if $which is "first", the function first() is called, etc...
}

Language constructs such as echo() and isset() cannot be called through variable functions:

$which = "echo";
$which("hello, world"); // does not work

Anonymous Functions

Some PHP functions do part of their work by using a function you provide to them. For example, the usort() function uses a function you create and pass to it as a parameter to determine the sort order of the items in an array.

Although you can define a function for such purposes, as shown previously, these functions tend to be localized and temporary. To reflect the transient nature of the callback, create and use an anonymous function (also known as a closure).

You can create an anonymous function using the normal function definition syntax, but assign it to a variable or pass it directly.

Example 3-6 shows an example using usort().

$array = array("really long string here, boy", "this", "middling length", "larger");

usort($array, function($a, $b) {
 return strlen($a) - strlen($b);
});

print_r($array);

The array is sorted by usort() using the anonymous function, in order of string length.

Anonymous functions can use the variables defined in their enclosing scope using the use syntax. For example:

$array = array("really long string here, boy", "this", "middling length", "larger");
$sortOption = 'random';

usort($array, function($a, $b) use ($sortOption)
{
 if ($sortOption == 'random') {
 // sort randomly by returning (−1, 0, 1) at random
 return rand(0, 2) - 1;
 }
 else {
 return strlen($a) - strlen($b);
 }
});

print_r($array);

Note that incorporating variables from the enclosing scope is not the same as using global variables—global variables are always in the global scope, while incorporating variables allows a closure to use the variables defined in the enclosing scope. Also note that this is not necessarily the same as the scope in which the closure is called. For example:

$array = array("really long string here, boy", "this", "middling length", "larger");
$sortOption = "random";

function sortNonrandom($array)
{
 $sortOption = false;

 usort($array, function($a, $b) use ($sortOption)
 {
 if ($sortOption == "random") {
 // sort randomly by returning (−1, 0, 1) at random
 return rand(0, 2) - 1;
 }
 else {
 return strlen($a) - strlen($b);
 }
 });

 print_r($array);
}

print_r(sortNonrandom($array));

In this example, $array is sorted normally, rather than randomly—the value of $sortOption inside the closure is the value of $sortOption in the scope of sortNonrandom(), not the value of $sortOption in the global scope.

What’s Next

User-defined functions can be confusing to write and complex to debug, so be sure to test them well and to try to limit them to performing one task each. In the next chapter we’ll be looking at strings and everything that they entail, which is another complex and potentially confusing topic. Don’t get discouraged: remember that we are building strong foundations for writing good, solid, succinct PHP code. Once you have a firm grasp of the key concepts of functions, strings, arrays, and objects, you’ll be well on your way to becoming a good PHP developer.