[PHP-DEV] "waldschrotts guide to nifty references" - manual page draft, version 0.9b From: André Langhorst (waldschrott <email protected>)
Date: 08/19/00

Really worth reading :) I have very likely invested the night (egon if you´re reading please do not tell I should sleep, I´ll do now),
to provide another glorious chapter for the PHP manual of world domination...

Please read carefully and correct grammatical and syntactical woes (typos too)((engl. is not my native language))
shortcomings displaying the current technical reality.

The subject (= manual entry title) is of course negotiatable ;)
additions welcome.

Note: I´ve reused the same comments and variable names over and over to simplify
the process of understanding, it´s intended not laziness.
have fun... I`ll be back in now()+7hours... I hope I haven´t missed sth.

References in PHP - Creating aliases for variables
------------------------------------------------------------------------
You can create multiple names for the same variable in PHP to access them. You´re establishing this reference using the "&"-sign.
This way you´re telling PHP to create another reference to the variable already existing. It´s another reference, because you´ve created
the first reference by creating the variable. The variable exists apart from variable names, as long it exists one variable name to access it,
otherwise the variable is freed, thus creating further references is like having a chamber and creating more and more doors to enter it. If you´ve no door to enter,
it´s useless and it does not exist anymore by definition.
The name reference is a bit misleading as you´re expecting that the reference itself is somehow different from the variable,
but you cannot say which one is reference and which one is variable, they´re both variable and reference concurrently. They´re the same.
It´s really different from pointers in C and Java references, it's very much similar to the way references are in C++.

Example:
$foo=5;
        // assign the value 5 to a variable accessible through $foo
$boo=&$foo; // create reference $boo to that variable accessible through $foo from outside the function
// now that variable is accessible through $foo AND $boo equally
$boo=6;
        // by changing $boo, $foo is changed too, because they´re the same variable
echo $foo; // both are referencing to the same variable with the value 6

References as function parameters
--------------------------------------------------
Function parameters can be declared to be referenced for the variables passed to the function call too.
Simply prepending the function parameter with a "&"-sign does the job.

$foo=5;
                // assign the value 5 to a variable accessible through $foo
function foo(&$boo) { // create reference $boo to that variable accessible through $foo from outside the function
// now that variable is accessible through $foo AND $boo equally
$boo=6;
}
// by changing $boo, $foo is changed too, because they´re the same variable
echo $foo; // both are referencing to the same value 6

Returning references
------------------------------
You´re also able to return references to use the same variable surviving function calls without the need to use global variables.
Prependind the function name with the "&"-sign indicates that you´re going to return a reference.
Currently it´s not sufficient to assign that reference afterwards with the assignement operator, like you´d do it with the new() statement,
you´ll have to tell PHP explicitly that it should assign this reference again.

function &foo(&$boo) { // tell function to return a refernce, create reference $boo
// to that variable accessible through $foo from outside the function
$boo=6;
        // by changing $boo, $foo is changed too, because they´re the same variable
return $boo;} // return the variable to outside

$foo=5;
                // assign the value 5 to a variable accessible through $foo
$foobar=&foo($foo); // create reference $foobar to the reference returned by foo()
echo $foobar; // the variable is now accessible through $foobar, and $foo from the global scope
// it was accessible through $boo from the function scope, this reference does not exist
// anymore, because the function has finished
$foobar=7;
        // to prove that $foobar and $foo are the same, we´ll asign the value 7 to them
echo $foo; // so far we´ve had access to the same variable the whole time, at the beginning, inside the function
// and now at the end, the only difference is that it happend through different references (aliases)

Common pitfalls
-----------------------
Re-Referencing of multiple variable names bound to a certain variable to be referenced to another variable does not work in PHP,
if you´ve understood the concept of references in PHP you´ll understand why.

Example:
function foo(&$boo) { // create reference $boo to that variable accessible through $foo from outside the function
$barfoo=3;
// assign the value 3 to a variable accessible through $barfoo
$boo=&$barfoo; // you could expect here that $boo and $foo are referenced to $barfoo, this is not the case
// instead the relation to the variable $boo and $foo are referenced to is broken and $boo is referenced
// to the variable accessible through $barfoo now, as if $boo had never referenced to another variable
return $boo; } // return the value of $boo to prove that it is 3 and not 5

$foo=5;
                // assign the value 5 to a variable accessible through $foo
echo foo($foo); // echo the returned value from foo()

Circular references
---------------------------
Thanks to these indirectional pointers (references) it´s possible to create true recursive datastructures, which can be very handy
in object-orientated communication mechanisms.

Simple example, not displaying practical use:

class foo {
var $a=1;
var $foobar; // this property will be a reference to another object later
function reference(&$boo) { // make $boo a reference
$this->foobar=&$boo; } } // make $this->foobar another reference to what $boo references too (passed object)

class foobar {
var $a=2;
var $foo; // this property will be a reference to another object later
function reference(&$boobar) { // make $boobar a reference
$this->foo=&$boobar; } } // make $this->foo another reference to what $boobar references too (passed object)

$object_foo=new foo(); // create an instance of class foo
$object_foobar=new foobar(); // create an instance of class foobar
$object_foo->reference($object_foobar); // invoke the referencing mechanism, step 1, $object_foo->foobar is referenced to $object_foobar
$object_foobar->reference($object_foo); // invoke the referencing mechanism, step 2, $object_foobar->foo is referenced to $object_foo
// circular reference established
//Now that we´ve created a circular reference we´re able doing weird things like..
echo $object_foo->a;
echo $object_foo->foobar->a;
echo $object_foo->foobar->foo->a;
echo $object_foo->foobar->foo->foobar->a;
echo $object_foo->foobar->foo->foobar->foo->foobar->foo->foobar->foo->foobar->foo->a;
// ... etc. :)

Note:
The use of circular references causes memory leaks which get cleaned up after each request in same cases (the more complex, the more likely to leak),
this is intended and should not hurt if you´re not using extremely large objects and having extremely much concurrent scripts running. 

-- 
PHP Development Mailing List <http://www.php.net/>
To unsubscribe, e-mail: php-dev-unsubscribe <email protected>
For additional commands, e-mail: php-dev-help <email protected>
To contact the list administrators, e-mail: php-list-admin <email protected>