From 1c88e130dd787285869ed37b9fad6a8464a4795d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gustavo=20Andr=C3=A9=20dos=20Santos=20Lopes?=
 <cataphract@php.net>
Date: Thu, 18 Nov 2010 10:34:33 +0000
Subject: [PATCH] - Revision #305471 reverted and added a more detailed
 explanation of the   topic of indirect modification of overloaded array
 dimensions.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@305489 c90b9560-bf6c-de11-be94-00142212c4b1
---
 language/predefined/arrayaccess/offsetget.xml | 30 +++++++++++++++++++
 language/predefined/arrayaccess/offsetset.xml | 23 ++++++++------
 2 files changed, 44 insertions(+), 9 deletions(-)

diff --git a/language/predefined/arrayaccess/offsetget.xml b/language/predefined/arrayaccess/offsetget.xml
index 66b947775d..b59bc930ff 100644
--- a/language/predefined/arrayaccess/offsetget.xml
+++ b/language/predefined/arrayaccess/offsetget.xml
@@ -37,6 +37,36 @@
   </para>
 
  </refsect1>
+ 
+ <refsect1 role="notes">
+  &reftitle.notes;
+  <note>
+    <para>
+      Starting with PHP 5.3.4, the prototype checks were relaxed and it's
+      possible for implementations of this method to return by reference.
+      This makes indirect modifications to the overloaded array dimensions of
+      <classname>ArrayAccess</classname> objects possible.
+    </para>
+    <para>
+      A direct modification is one that replaces completely the value of
+      the array dimension, as in <literal>$obj[6] = 7</literal>. An
+      indirect modification, on the other hand, only changes part of the
+      dimension, or attempts to assign the dimension by reference to
+      another variable, as in <literal>$obj[6][7] = 7</literal> or
+      <literal>$var =& $obj[6]</literal>. Increments with
+      <literal>++</literal> and decrements with <literal>++</literal>
+      are also implemented in a way that requires indirect modification.
+    </para>
+    <para>
+      While direct modification triggers a call to
+      <function>ArrayAccess::offsetSet</function>, indirect modification
+      triggers a call to <function>ArrayAccess::offsetGet</function>.
+      In that case, the implementation of
+      <function>ArrayAccess::offsetGet</function> must be able to return by
+      reference, otherwise an <constant>E_NOTICE</constant> message is raised.
+    </para>
+  </note>
+ </refsect1>
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
diff --git a/language/predefined/arrayaccess/offsetset.xml b/language/predefined/arrayaccess/offsetset.xml
index 3168930655..304ca5581a 100644
--- a/language/predefined/arrayaccess/offsetset.xml
+++ b/language/predefined/arrayaccess/offsetset.xml
@@ -80,15 +80,20 @@ Array
     </informalexample>
    </para>
   </note>
- </refsect1>
-
- <refsect1 role="errors">
-  &reftitle.errors;
-  <para>
-   Issues <constant>E_NOTICE</constant> in an attempt of indirect modification
-   of overloaded element (like usage of <literal>++</literal> or
-   <literal>--</literal>).
-  </para>
+  
+  <note>
+    <para>
+      This function is not called in assignments by reference and otherwise
+      indirect changes to array dimensions overloaded with
+      <classname>ArrayAccess</classname> (indirect in the sense they are
+      made not by changing the dimension directly, but by changing a
+      sub-dimension or sub-property or assigning the array dimension by
+      reference to another variable).
+      Instead, <function>ArrayAccess::offsetGet</function> is called. The
+      operation will only be successful if that method returns by reference,
+      which is only possible since PHP 5.3.4.
+    </para>
+  </note>
  </refsect1>
 
 <!--