From 22434db00e7486f5cecb9550904bbddce944ddcb Mon Sep 17 00:00:00 2001
From: Adam Harvey <aharvey@php.net>
Date: Fri, 22 Oct 2010 08:15:45 +0000
Subject: [PATCH] Fix doc bug #53117 (Assignment by reference within assignment
 operator) by breaking out the previously brief discussion of using the
 assignment operator to assign by reference into its own subsection, including
 a reference to by-reference assignments of new expressions being deprecated.
 Also updated the References Explained section to reflect 5.3+ generating
 E_DEPRECATED errors in that case, rather than E_STRICT.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@304605 c90b9560-bf6c-de11-be94-00142212c4b1
---
 language/operators.xml  | 78 +++++++++++++++++++++++++++++++++++------
 language/references.xml |  3 +-
 2 files changed, 70 insertions(+), 11 deletions(-)

diff --git a/language/operators.xml b/language/operators.xml
index c90bdad192..eb95605420 100644
--- a/language/operators.xml
+++ b/language/operators.xml
@@ -364,17 +364,75 @@ $b .= "There!"; // sets $b to "Hello There!", just like $b = $b . "There!";
     Note that the assignment copies the original variable to the new
     one (assignment by value), so changes to one will not affect the
     other. This may also have relevance if you need to copy something
-    like a large array inside a tight loop. Assignment
-    by reference is also supported, using the <computeroutput>$var =
-    &amp;$othervar;</computeroutput> syntax.
-    'Assignment by reference' means that both variables end
-    up pointing at the same data, and nothing is copied anywhere.
-    To learn more about references, please read <link
-    linkend="language.references">References explained</link>. As of
-    PHP 5, objects are assigned by reference unless explicitly told
-    otherwise with the new <link linkend="language.oop5.cloning">clone</link>
-    keyword.
+    like a large array inside a tight loop.
    </para>
+   <para>
+    An exception to the usual assignment by value behaviour within PHP occurs
+    with <type>object</type>s, which are assigned by reference in PHP 5.
+    Objects may be explicitly copied via the <link
+    linkend="language.oop5.cloning">clone</link> keyword.
+   </para>
+
+   <sect2 xml:id="language.operators.assignment.reference">
+    <title>Assignment by Reference</title>
+    <para>
+     Assignment by reference is also supported, using the
+     "<computeroutput>$var = &amp;$othervar;</computeroutput>" syntax.
+     Assignment by reference means that both variables end up pointing at the
+     same data, and nothing is copied anywhere.
+    </para>
+    <para>
+     <example>
+      <title>Assigning by reference</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+$a = 3;
+$b = &$a; // $b is a reference to $a
+
+print "$a\n"; // prints 3
+print "$b\n"; // prints 3
+
+$a = 4; // change $a
+
+print "$a\n"; // prints 4
+print "$b\n"; // prints 4 as well, since $b is a reference to $a, which has
+              // been changed
+?>
+]]>
+      </programlisting>
+     </example>
+    </para>
+    <para>
+     As of PHP 5, the <link linkend="language.oop5.basic.new">new</link>
+     operator returns a reference automatically, so assigning the result of
+     <link linkend="language.oop5.basic.new">new</link> by reference results
+     in an <constant>E_DEPRECATED</constant> message in PHP 5.3 and later, and
+     an <constant>E_STRICT</constant> message in earlier versions.
+    </para>
+    <para>
+     For example, this code will result in a warning:
+     <informalexample>
+      <programlisting role="php">
+<![CDATA[
+<?php
+class C {}
+
+/* The following line generates the following error message:
+ * Deprecated: Assigning the return value of new by reference is deprecated in...
+ */
+$o = &new C;
+?>
+]]>
+      </programlisting>
+     </informalexample>
+    </para>
+    <para>
+     More information on references and their potential uses can be found in
+     the <link linkend="language.references">References Explained</link>
+     section of the manual.
+    </para>
+   </sect2>
   </sect1>
 
   <sect1 xml:id="language.operators.bitwise">
diff --git a/language/references.xml b/language/references.xml
index 6d5290c710..0f5fb3a1e1 100644
--- a/language/references.xml
+++ b/language/references.xml
@@ -105,7 +105,8 @@ $foo =& find_var($bar);
      Since PHP 5, <link linkend="language.oop5.basic.new">new</link>
      returns a reference automatically, so
      using <literal>=&amp;</literal> in this context is deprecated and
-     produces an <constant>E_STRICT</constant> message.
+     produces an <constant>E_DEPRECATED</constant> message in PHP 5.3 and
+     later, and an <constant>E_STRICT</constant> message in earlier versions.
     </para>
     <warning>
      <para>