PHP Functions Returning Values by Reference

PHP Functions 

Returning Values by Reference

Problem

You want to return a value by reference, not by value. This allows you to avoid making a duplicate copy of a variable.

Solution

The syntax for returning a variable by reference is similar to passing it by reference. However, instead of placing an & before the parameter, place it before the name of the function:

            function &array_find_value($needle, &$haystack) {
                  foreach ($haystack as $key => $value) {
                        if ($needle == $value) {
                               return $haystack[$key];
                        }
                  }
            }

Also, you must use the =& assignment operator instead of plain = when invoking the function:

            $band =& array_find_value('The Doors', $artists);

Discussion

Returning a reference from a function allows you to directly operate on the return value and have those changes directly reflected in the original variable.

The following code searches through an array looking for the first element that matches a value. It returns the first matching value. For instance, you need to search through a list of famous people from Minnesota looking for Prince, so you can update his name:

            function &array_find_value($needle, &$haystack) {
                  foreach ($haystack as $key => $value) {
                        if ($needle == $value) {
                               return $haystack[$key];
                        }
                  }
            }

            $minnesota = array('Bob Dylan', 'F. Scott Fitzgerald',
                                            'Prince', 'Charles Schultz');

            $prince =& array_find_value('Prince', $minnesota);

            $prince = 'O(+>'; // The ASCII version of Prince's unpronounceable symbol

            print_r($minnesota);

This prints:

            Array
            (
                    [0] => Bob Dylan
                    [1] => F. Scott Fitzgerald
                    [2] => O(+>
                    [3] => Charles Schultz
            )

Without the ability to return values by reference, you would need to return the array key and then rereference the original array:

            function array_find_value($needle, &$haystack) {
                  foreach ($haystack as $key => $value) {
                        if ($needle == $value) {
                               return $key;
                        }
                  }
            }

            $minnesota = array('Bob Dylan', 'F. Scott Fitzgerald',
                                            'Prince', 'Charles Schultz');

            $prince = array_find_value('Prince', $minnesota);
            // The ASCII version of Prince's unpronounceable symbol
            $minnesota[$prince] = 'O(+>';

When returning a reference from a function, you must return a reference to a variable, not a string. For example, this is not legal:

            function &array_find_value($needle, &$haystack) {
                  foreach ($haystack as $key => $value) {
                        if ($needle == $value) {
                               $match = $haystack[$key];
                        }
                  }

                  return "$match is found in position $key";
            }

That’s because "$match is found in position $key" is a string, and it doesn’t make logical sense to return a reference to nonvariables. This causes PHP to emit an E_NOTICE.

Unlike passing values into functions, in which an argument is either passed by value or by reference, you can optionally choose not to assign a reference and just take the returned value. Just use = instead of =&, and PHP assigns the value instead of the reference.