From 765a590c606bb5af58c8a130c478d2c1a771d683 Mon Sep 17 00:00:00 2001
From: Jim Winstead <jimw@trainedmonkey.com>
Date: Sat, 28 Sep 2024 17:28:28 -0700
Subject: [PATCH 1/2] Simplify array_replace description and add nested array
 example

Based on discussion at PR #1470
---
 reference/array/functions/array-replace.xml | 49 ++++++++++++++++-----
 1 file changed, 39 insertions(+), 10 deletions(-)

diff --git a/reference/array/functions/array-replace.xml b/reference/array/functions/array-replace.xml
index 97fb5d8dbf5d..ce332baa4c1c 100644
--- a/reference/array/functions/array-replace.xml
+++ b/reference/array/functions/array-replace.xml
@@ -13,18 +13,13 @@
    <methodparam rep="repeat"><type>array</type><parameter>replacements</parameter></methodparam>
   </methodsynopsis>
   <para>
-   <function>array_replace</function> replaces the values of
-   <parameter>array</parameter> with values having the same keys in each of the following
-   arrays. If a key from the first array exists in the second array, its value
-   will be replaced by the value from the second array. If the key exists in the
-   second array, and not the first, it will be created in the first array.
-   If a key only exists in the first array, it will be left as is.
-   If several arrays are passed for replacement, they will be processed
-   in order, the later arrays overwriting the previous values.
+   <function>array_replace</function> creates a new array and assigns items into
+   it for each key in each of the provided arrays. If a key appears in multiple
+   input arrays, the value from the right-most input array will be used.
   </para>
   <para>
-   <function>array_replace</function> is not recursive : it will replace
-   values in the first array by whatever type is in the second array.
+   <function>array_replace</function> does not process elements items recursively,
+   it replaces the entire value for each key when it does a replacement.
   </para>
  </refsect1>
  <refsect1 role="parameters">
@@ -85,6 +80,40 @@ Array
     [3] => raspberry
     [4] => cherry
 )
+]]>
+    </screen>
+   </example>
+   <example>
+    <title>Example of how nested arrays are handled</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$base = [ 'citrus' => [ 'orange', 'lemon' ], 'pome' => [ 'apple' ] ];
+$replacements = [ 'citrus' => [ 'grapefruit' ] ];
+$replacements2 = [ 'citrus' => [ 'kumquat', 'citron' ], 'pome' => [ 'loquat' ] ];
+
+$basket = array_replace($base, $replacements, $replacements2);
+print_r($basket);
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen role="php">
+<![CDATA[
+Array
+(
+    [citrus] => Array
+        (
+            [0] => kumquat
+            [1] => citron
+        )
+
+    [pome] => Array
+        (
+            [0] => loquat
+        )
+
+)
 ]]>
     </screen>
    </example>

From a12437092fe98c8659a89667b76be26ded0c7551 Mon Sep 17 00:00:00 2001
From: Jim Winstead <jimw@trainedmonkey.com>
Date: Mon, 30 Sep 2024 11:59:20 -0700
Subject: [PATCH 2/2] Use var_dump() for examples

---
 reference/array/functions/array-replace.xml | 52 +++++++++++----------
 1 file changed, 28 insertions(+), 24 deletions(-)

diff --git a/reference/array/functions/array-replace.xml b/reference/array/functions/array-replace.xml
index ce332baa4c1c..f75604be4814 100644
--- a/reference/array/functions/array-replace.xml
+++ b/reference/array/functions/array-replace.xml
@@ -65,21 +65,25 @@ $replacements = array(0 => "pineapple", 4 => "cherry");
 $replacements2 = array(0 => "grape");
 
 $basket = array_replace($base, $replacements, $replacements2);
-print_r($basket);
+var_dump($basket);
 ?>
 ]]>
     </programlisting>
     &example.outputs;
     <screen role="php">
 <![CDATA[
-Array
-(
-    [0] => grape
-    [1] => banana
-    [2] => apple
-    [3] => raspberry
-    [4] => cherry
-)
+array(5) {
+  [0]=>
+  string(5) "grape"
+  [1]=>
+  string(6) "banana"
+  [2]=>
+  string(5) "apple"
+  [3]=>
+  string(9) "raspberry"
+  [4]=>
+  string(6) "cherry"
+}
 ]]>
     </screen>
    </example>
@@ -93,27 +97,27 @@ $replacements = [ 'citrus' => [ 'grapefruit' ] ];
 $replacements2 = [ 'citrus' => [ 'kumquat', 'citron' ], 'pome' => [ 'loquat' ] ];
 
 $basket = array_replace($base, $replacements, $replacements2);
-print_r($basket);
+var_dump($basket);
 ?>
 ]]>
     </programlisting>
     &example.outputs;
     <screen role="php">
 <![CDATA[
-Array
-(
-    [citrus] => Array
-        (
-            [0] => kumquat
-            [1] => citron
-        )
-
-    [pome] => Array
-        (
-            [0] => loquat
-        )
-
-)
+array(2) {
+  ["citrus"]=>
+  array(2) {
+    [0]=>
+    string(7) "kumquat"
+    [1]=>
+    string(6) "citron"
+  }
+  ["pome"]=>
+  array(1) {
+    [0]=>
+    string(6) "loquat"
+  }
+}
 ]]>
     </screen>
    </example>