Functions (Webmaster in a Nutshell, 3rd Edition)

16.9. Functions

A function is a named sequence of code statements that can optionally accept parameters and return a value. A function call is an expression that has a value; its value is the returned value from the function. PHP provides a large number of internal functions. The Section 16.13 lists all of the commonly available functions. PHP also supports user-definable functions. To define a function, use the function keyword. For example:

function soundcheck($a, $b, $c) {
  return "Testing, $a, $b, $c";
}

When you define a function, be careful what name you give it. In particular, you need to make sure that the name does not conflict with any of the internal PHP functions. If you do use a function name that conflicts with an internal function, you get the following error:

Fatal error: Can't redeclare already declared function in 
filename on line N

After you define a function, you call it by passing in the appropriate arguments. For example:

echo soundcheck(4, 5, 6);

You can also create functions with optional parameters. To do so, you set a default value for each optional parameter in the definition, using C++ style. For example, here's how to make all the parameters to the soundcheck() function optional:

function soundcheck($a=1, $b=2, $c=3) {
  return "Testing, $a, $b, $c";
}

16.9.1. Passing Arguments to Functions

There are two ways you can pass arguments to a function: by value and by reference. To pass an argument by value, you pass in any valid expression. That expression is evaluated and the value is assigned to the corresponding parameter defined within the function. Any changes you make to the parameter within the function have no effect on the argument passed to the function. For example:

function triple($x) {
  $x=$x*3;
  return $x;
}
$var=10;
$triplevar=triple($var);

In this case, $var evaluates to 10 when triple() is called, so $x is set to 10 inside the function. When $x is tripled, that change does not affect the value of $var outside the function.

In contrast, when you pass an argument by reference, changes to the parameter within the function do affect the value of the argument outside the scope of the function. That's because when you pass an argument by reference, you must pass a variable to the function. Now the parameter in the function refers directly to the value of the variable, meaning that any changes within the function are also visible outside the function. For example:

function triple(&$x) {
  $x=$x*3;
  return $x;
}
$var=10;
triple($var);

The & that precedes $x in the triple() function definition causes the argument to be passed by reference, so the end result is that $var ends up with a value of 30.

16.9.2. Variable Scope

The scope of a variable is the context within which a variable is available. There are two scopes for variables in PHP. Global variables are available directly from the mainline PHP execution. That is, if you are not inside a function, you can access global variables directly. Unlike most other languages, functions in PHP have their own, completely separate variable scope. Take this example:

<?php
  function test( ) {
    echo $a;
  }

  $a = "Hello World";
  test( );       
?>

If you run this script you will find that there is no output. This is because the $a you are trying to access inside the test( ) function is a completely different variable from the global $a you created in the global scope just before calling the function. In order to access a globally-scoped variable from inside a function, you need to tell the function to use the global scope for that particular variable. It can be done with the global keyword like this:

<?php
  function test( ) {
    global $a;
    echo $a;
  }

  $a = "Hello World";
  test( );       
?>

Alternatively, you can use the $GLOBALS array like this:

<?php
  function test( ) {
    echo $GLOBALS['a'];
  }

  $a = "Hello World";
  test( );       
?>

In this last example, the $GLOBALS array is known as a superglobal, which is a variable that is automatically available in all scopes without needing to be declared global in order to be accessed from within a function.

16.9.3. Static Variables

PHP supports declaring local function variables as static. A static variable retains its value between function calls, but is still accessible only from within the function it is declared in. Static variables can be initialized; this initialization only takes place the first time the static declaration is executed. Static variables are often used as counters, as in this example:

function hitcount( )
  static $count = 0;

  if ($count == 0) {
    echo "This is the first access to this page";
  } else {
    echo "This page has been accessed $count times";
  }
  $count++;
}