<script language="php">

echo "<p>Without seeing the source, the results will be quite
meaningless.  <p>The source code for this example is <a href=\"index.phps\">here</a>.  <p>Curiously, the PHP source syntax hilighter <b>stops displaying the code</b> at
an arbitrary point (I do <i>so</i> love PHP) so you can see the whole
source, sans syntax hilighting, <a href=\"index.txt\">here</a>. <p>Anyway.  On to the results...<p>&nbsp;</p>";

// Define a simple class.
class myClass {
    var $member = "default";

    function changeMember($newValue) {
        $this->member = $newValue;
    }
}

// Create an instance of the simple class.
$myInstance = new myClass();

echo "Here's an instance of myClass:<br>";

// Display the instance.
var_dump($myInstance);

// Define a function to which a myClass instance may be passed,
// which presumably manipulates the instance.
//
function myBadFunction($aMyClassInstance) {
    $aMyClassInstance->changeMember("foo");
}

// Invoke the function.
myBadFunction($myInstance);

echo "<p>Here's the instance, after passing it to myBadFunction():<br>";

// Display the resulting instance.
var_dump($myInstance);

echo "<p>It didn't change!  That's because <b>all</b> variables
are <u>passed by value</u> by default!";

echo "<p>Include an '&' in a parameter declaration to indicate pass by
reference.<br>";

// Define a function to which a myClass instance may be passed,
// and which really does manipulate the instance.  Note the crucial
// ampersand in the parameter declaration.
//
function myGoodFunction(&$aMyClassInstance) {
    $aMyClassInstance->changeMember("foo");
}

// Invoke the function.
myGoodFunction($myInstance);

echo "<p>Here's the instance, after passing it to myGoodFunction().<br>";

// Display the resulting instance.
var_dump($myInstance);

echo "<p>Here's an example of a function that returns a reference:<br>";

// Define a function which accepts a myClass reference and returns it.
//
// Note the all-important ampersand in the return declaration!
//
// NOTE: I find it helpful to mentally regard the ampersand as part of
//       the function name, thus making it harder to forget.  Try
//       leaving it out to see what happens...
//
function &InAndOut(&$aMyClassInstance) {
    $aMyClassInstance->changeMember("glue");
    return $aMyClassInstance;
}

// Invoke it.  Note the all-important ampersand in the invocation!
//
$result = &InAndOut($myInstance);

echo "<p>The result is:<br>";

var_dump($result);

echo "<p>The result should be a reference to the original object.  If we change it, the original object should be modified:<br>";

$result->changeMember("slough");

echo "<p>Original object is now:<br>";

var_dump($myInstance);

</script>