To create a new function you must think of a name for it and consider what it will do. Functions can return values to the caller, or not return a value. They can be set up to take or not take parameters. To illustrate function syntax, let us examine a function called getNiceTime(), which will return a formatted string containing the current server time, and is shown in Listing 12.13. You will notice that the definition requires the use of the function keyword followed by the function’s name, round ( ) brackets for parameters, and then the body of the function inside curly { } brackets.

/**
* This function returns a nicely formatted string using the current
* system time.
*/
function getNiceTime(){
   return date("H:i:s");
}

While the example function in Listing 12.13 returns a value, there is no requirement for this to be the case. Listing 12.14 illustrates a function definition that doesn’t return a value but just performs a task.

/**
* This function outputs a footer menu
*/
function outputFooterMenu() {
   echo '<div id="footer">';
   echo '<a href="#">Home</a> | <a href="#">Products</a> | ';
   echo '<a href="#">About us</a> | <a href="#">Contact us</a>';
   echo '</div>';
}

function mustReturnString(string $name) : string {
   return "hello ". $name;
}

Now that you have defined a function, you are able to use it whenever you want to. To invoke or call a function you must use its name with the () brackets. Since getNiceTime() returns a string, you can assign that return value to a variable, or echo that return value directly, as shown in the following example:

$output = getNiceTime();
echo getNiceTime();

If the function doesn’t return a value, you can just call the function:

outputFooterMenu();

It is common to define functions with parameters since functions are more powerful and reusable when their output depends on the input they get. Parameters (also called arguments) are the mechanism by which values are passed into functions, and there are some complexities that allow us to have multiple parameters, default values, and to pass objects by reference instead of value.

To define a function with parameters, you must decide how many parameters you want to pass in, and in what order they will be passed. Each parameter must be named. To illustrate, let us write another version of getNiceTime() that takes an integer as a parameter to control whether to show seconds. You will call the parameter showSeconds, and write our function as shown in Listing 12.16. Notice that parameters, being a type of variable, must be prefaced with a $ symbol like any other PHP variable.

/**
* This function returns a nicely formatted string using the current
* system time. The showSeconds parameter controls whether or not to
* include the seconds in the returned string.
*/
function getNiceTime($showSeconds) {
   if ($showSeconds==true)
       return date("H:i:s");
   else
       return date("H:i");
}

Thus to call our function, you can now do it in two ways:

echo getNiceTime(true);   // this will print seconds
echo getNiceTime(false);  // will not print seconds

In fact any nonzero number passed in to the function will be interpreted as true since the parameter is not type specific.

/**
* This function returns a nicely formatted string using the current
* system time. The showSeconds parameter controls whether or not
* to show the seconds.
*/
function getNiceTime($showSeconds=true) {
   if ($showSeconds==true)
       return date("H:i:s");
   else
       return date("H:i");
}

Passing Parameters by Reference

By default, arguments passed to functions are passed by value in PHP. This means that PHP passes a copy of the variable so if the parameter is modified within the function, it does not change the original. Listing 12.18 illustrates a simple example of passing by value. Notice that even though the function modifies the parameter value, the contents of the variable passed to the function remain unchanged after the function has been called.

Listing 12.18 Passing a parameter by value

function changeParameter($arg) {
   $arg += 285;
   echo "<br/>arg=" . $arg;
}

$initial = 15;
echo "<br/>initial=" . $initial;   // output: initial=15
changeParameter($initial);         // output: arg=300
echo "<br/>initial=" . $initial;   // output: initial=15

Like many other programming languages, PHP also allows arguments to functions to be passed by reference, which will allow a function to change the contents of a passed variable. A parameter passed by reference points the local variable to the same place as the original, so if the function changes it, the original variable is changed as well. The mechanism in PHP to specify that a parameter is passed by reference is to add an ampersand (&) symbol next to the parameter name in the function declaration. Listing 12.19 illustrates an example of passing by reference.

Listing 12.19 Passing a parameter by reference

function changeParameter(&$arg) {
  $arg += 300;
  echo "<br/>arg=". $arg;
}

$initial = 15;
echo "<br/>initial=" . $initial;   // output: initial=15
changeParameter($initial);         // output: arg=315
echo "<br/>initial=" . $initial;   // output: initial=315

Figure 12.10 illustrates visually the memory differences between pass-by-value and pass-by-reference.

Figure 12.10 Pass by value versus pass by reference

Figure 12.10 Full Alternative Text

The possibilities opened up by the pass-by-reference mechanism are significant, since you can now decide whether to have your function use a local copy of a variable, or modify the original. By and large, most of the time you should keep your functions pure (see discussion on pure functions in Chapter 1) and use pass-by value in the majority of your functions.

function getNiceTime(bool  $showSeconds=1) {
   if ($showSeconds==true)
      return date("H:i:s");
   else
      return date("H:i");
}

declare(strict_types=1);

It will come as no surprise that all variables defined within a function (such as parameter variables) have function scope, meaning that they are only accessible within the function. It might be surprising though to learn that, unlike JavaScript, any variables created outside of the function in the main script are unavailable within a function. For instance, in the following example, the output of the echo within the function is 0 and not 56 since the reference to $count within the function is assumed to be a new variable named $count with function scope.

$count = 56;

function testScope() {
   echo $count;     // outputs 0 or generates run-time warning
}
testScope();
echo $count;        // outputs 56

Of course, in the aforementioned example, one could simply have passed $count to the function. However, there are times when such a strategy is unworkable. For instance, most web applications will have important data values such as connections, application constants, and logging/debugging switches that need to be available throughout the application, and passing them to every function that might need them is often impractical. PHP does allow variables with global scope to be accessed within a function using the global keyword, as shown in Listing 12.21, though generally speaking, its usage is discouraged.

$count = 56;

function testScope() {
   global  $count;
   echo $count;   // outputs 56
}

testScope();
echo $count;      // outputs 56