- 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

@@ -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;

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>
 
 <!--