In my opinion there are some functions missing in PHP, depending the handling of references. I found out, that it isn't possible to find out, if and what other variables references to my value. But this is sometimes important, especially for very complex scripts or self-configuring.

So I would suggest the following new functions:

- references() (or perhaps better references_of() which is more meaningful) - returns an array of all referenced variables, exept the current. false, if it has no other references

print_r( references($b) );

should output "array('a')", this means $b has in it's local and/or global scope the reference $a.

Hm, maybe it's important to differ local and global, so a second parameter with the defined values REFERENCES_LOCAL etc. Could be fine.

Maybe it's difficult to output referenced variables which are objects or arrays... I have currently no idea how to do that consequently and easy:

$a=array(0=>1);
$b=&$a[0];
print_r(references($b));

... should output what?? array('a'=>array('0')) or array('a[0]')??

(btw: In the case of the second option the following feature would be very nice (I have been missing this sometimes, but don't know if this is currently working):

$c='a[0]';
$$c='hugo';
echo $a[0];
-> outputs 'hugo' )


- references_all() (or perhaps better all_references() ?)- This is like references(), but returns ALL references, including the parameter. So it should return always an array. This is good to build a loop here, see down.


- is_referenced() or perhaps referenced_num() - returns true or better the number of references of this variable to the VALUE (without counting itself)

$a=1;
$b=&$a;
echo referenced_num($a);
echo referenced_num($b);

should both output '1' 


- unset_references() - unsets all references to the VALUE of a variable, with this you can be sure, that storage of this value is cleaned up, even, if you are in a local scope like

function bla() {
global $a;
unset_references($a);
}
$a='hugo'
bla();
# $a is unset

This is not the very same as setting the VALUE to the value NULL ($a=null;), where the references to $a will survive.

It really unsets all references to the value unsets, it is just like it has never been set before, which means, that

unset_references($a);
echo $b;

(should consequently output a notice, that $b never has been set in the script...)

A gimmick to be consequent unset_references(&$var) should be the same as unset($var)  and deletes only the REFERENCE $var.

Indeed 

unset_references($a);

is maybe the same (?) as:

foreach ( all_references($a) as $v ) {
   unset_references(&$$v);
}

Looks very cool. :-)

Another good name alias would be unset_value(), cause it also unsets the value, or more simply clean() or purge().


- There may be some other features depending references, like

 foreach ( $array as &$value )

which will call the loop var $value by reference instead by value (think this could be easy to implement).


- The documentation should be rewritten in some parts. My experience brought out, that it's fine to distinguish better between

* VARIABLE (= *always* a REFERENCE, or POINTER to a VALUE, unlike C, PHP cannot directly hold VALUES in a VARIABLE)
 and
* VALUE (= STORAGEPLACE of a VARIABLE, a VALUE can have many VARIABLES or REFERENCES)

The documentation here is based on PHP3, in PHP4 many things has changed, so it's a little "wrong" in some parts (see my comment to the function unset())...

This would make many things more clearly for beginners - I saw this with our trainees here: When I explained, that a variable is always only a reference to a value they said all "ah, ja, that is it, this is missing in the docs"... :-)