Karma's Nucleus DevBlog

In order to understand some parts of the Nucleus core code, you need to know what references are, how they work, and how to use them. This article tries to explain the basics of references. If you're familiar with programming languages like C or C++, this will look trivial. But remember: PHP references are NOT the same as pointers in C, they're more like symbol table aliasses.

Knowing how references work will help you understand the Nucleus MANAGER class and the Nucleus Plugin API.

Variables & Memory

Conceptually, an assignment to a variable will associate the variable with some location in memory that contains the data from the assignment.

$a = 123

After this code, the $a variable will point to some memory location containing a value of 123. Nothing unexpected so far.

References

Now, let's consider the following piece of code:

$b = $a
$c =& $a

What will happen?

It turns out that we've created two new variables, called $b and $c. The first one ($b) points to a new memory location, containing the same value as $a did. The value has been copied. $c on the other hand, refers to the same memory location as $a did, because of the =& operator. No data has been copied.

Some more code:

$a++; $b++; $c++;

Quite obvious, the values of each of the variables is increased by one. But since $a and $c point to the same code, the final value for these variables will be 125.

Function arguments

Let's add some more code. We'll be adding two functions and will be calling them.

function ref(&$x) { $x = $x / 2; }
function nonref($x) { $x = $x / 2; }

ref($b);
nonref($c);

You'll notice that the ref function has & before its parameter name. It indicates that the parameter should be passed by reference rather than by value. It also means that if we call this method on $b, the resulting value in $b will be 62.

The nonref method, on the other hand, gets its parameters by value. The calculation inside the function is thus done on a temporary copy and therefore will not affect $c or $a.

Arrays!

Let's throw in some arrays. Arrays can also contain references, complicating things once more.

$r = array(&$a, &$b, $c);

So, what does the memory look like now? The array contains three values, two of which are references to $a and $b.

You'll probably guess what the following code has as result:

$r[0]++; $r[1]++; $r[2]++;

Now for a tricky one: let's pass the array as a whole to some functions. One of them takes an array by reference, the other one takes it by values. First, let's define our functions:

function a_ref(&$x) { $x[0]++; $x[1]++; $x[2]++; }
function a_nonref($x) { $x[0]++; $x[1]++; $x[2]++; }

Now, let's call a_ref($r) first. As you expect, the result will be as follows:

Maybe a little unexpected, but when calling the method with copy semantics (a_nonref($r)), we see that the values still change (except for $r[2])!

The reason for this, is that even though the array $r is copied to a temporary $x variable before executing the code in the function, taking a copy of a reference yields the same reference. So while executing a_nonref, $x contains two references (to $a and $b), plus a copy of the value 127. The fact that the 127 value is copied is the reason why $r[2] hasn't changed to 128 here.

The danger of foreach

One important thing to know is that a foreach loop will take a copy for each iteration. This means that the following code will not alter $r

foreach ($r as $foo) 
{
   $foo++;
}

Instead, you should use the following code:

foreach (array_keys($r) as $idx)
{
   $foo =& $r[$idx];
   ...
}

Be careful not to use foreach ($r as &$foo), since this only works in PHP5+. It looks cleaner, though :)

Call-time pass-by-reference

In earlier versions of PHP it was possible to do something like:

my_func(&$foo)

function my_func($x) {}

This behavior has long been deprecated, and should never be used. In php.ini, there's an option allow_call_time_pass_reference which is nowadays generally set to Off.

So, why would references be useful?

The samples above (creating references to simple integers) aren't really useful in daily life. References are mostly used in Nucleus to avoid copying of entire objects, to save memory usage and to allow plugins to edit certain data while handling events.

What is the effect on performance?

Quoting part of the phpPatterns() - PHP and Variable References article: