References

Variable References

In PHP, references are created by prefixing a variable (or function) name by an ampersand (&) character. Consider the example in Listing 1.27:

Listing 1.27. Using PHP References

<?php

    $myvar = 42;       /* Initialize $myvar */
    $myref = &$myvar;  /* Create a reference $myref to $myvar */

    echo "The value of \$myref is '$myref'<BR>";
    echo "The value of \$myvar is '$myvar'<BR>";

    $myvar++;

    echo "The value of \$myref is '$myref'<BR>";
    echo "The value of \$myvar is '$myvar'<BR>";

    $myref--;

    echo "The value of \$myref is '$myref'<BR>";
    echo "The value of \$myvar is '$myvar'<BR>";

?>

When this script is executed, the output will be as follows:

The value of $myref is '42'
The value of $myvar is '42'
The value of $myref is '43'
The value of $myvar is '43'
The value of $myref is '42'
The value of $myvar is '42'

As you can see, the variables $myvar and $myref are now references/aliases to the same piece of data, and any change made to one affects the other.

NOTE Because both $myvar and $myref represent the same data, if you destroy either variable using the unset() PHP function, the data would not be lost. Rather, the remaining variable would still point to the data. This will be true regardless of how many different references to a single variable are destroyed. As long as one variable still references a given piece of data, it can be accessed from within your scripts through that variable.

References Used in Functions

References can also be used in conjunction with functions. For instance, consider a situation in which it would be beneficial to return more than one value from a function. It is impossible to return two values using the return statement, and it may not be desirable to set global variables. By using references you can return as many values as desired in a relatively clean fashion.

To define a parameter to a function as a reference, prefix the parameter variable name with the reference operator & and pass a reference to the function when called, as shown in Listing 1.28:

Listing 1.28. Passing by Reference in PHP

<?php

    function reference_test($var, &$result, &$result2) {

        $result = "This is return value #1";
        $result2 = "You entered $var as your parameter";

        return 42;

    }

    $res = reference_test(10, &$res1, &$res2);

    echo "The value of \$res is '$res'<BR>";
    echo "The value of \$res1 is '$res1'<BR>";
    echo "The value of \$res2 is '$res2'<BR>";

?>

This produces the following output:

The value of $res is '42'
The value of $res1 is 'This is return value #1'
The value of $res2 is 'You entered 10 as your parameter'

If you are confused as to how this script works, let's walk through it step by step. First, our function reference_test() is declared accepting three parameters. The first parameter, $val, is a standard PHP parameter, whereas the remaining two, $result and $result2, are reference parameters. When the reference_test() function is called, it is passed three parameters. The first is a constant value of 10, and the remaining two are references to the variables $res1 and $res2. When this function call is executed, a link between the variables $result and $result2 and the variables $res1 and $res2 is created (because they reference each other). Hence, when changes are made to the $result and $result2 variables from within the function, the linked references outside the function $res1 and $res2 are also changed. The function still returns an integer constant of 42, which is then stored in the $res variable as expected.

NOTE Don't worry if this script confuses you at first. References are one of the hardest topics in PHP to completely understand (especially as things get more complicated) and it will take some practice to get the hang of them. Also note that you don't need to pass by reference at runtime and in the function declaration. Either place will have the same result. The only difference is that declaring in the function definition means all calls to the function are automatically passed by reference.

Along with passing variables to functions by reference, PHP supports the returning of variable references. In the example shown in Listing 1.29, this concept is used to create a function that returns a reference based on the values of the parameters passed.

Listing 1.29. Returning a Value by Reference

<?php

    function &find_var($one, $two, $three) {

        if(($one > 0) && ($one <= 10)) return $one;
        if(($two > 0) && ($two <= 10)) return $two;
        if(($three > 0) && ($three <= 10)) return $three;

    }

    $c_one = 'foo';
    $c_two = 42;
    $c_three = 4;

    $right_var = &find_var($c_one, $c_two, $c_three);

    $right_var++;

    echo "The value of \$c_three and \$right_var are: ";
    echo "$c_three and $right_var<BR>\n";

?>

When this code is executed, the find_var() function will determine which of the three parameters is between 1 and 10 and return a reference to that variable, which will then be linked to the $right_var variable. The result is that when $right_var is incremented, the only variable that met the requirements (the $c_three variable) will also be incremented, resulting in the following output:

The value of $c_three and $right_var are: 5 and 5