diff --git a/reference/strings/functions/str-replace.xml b/reference/strings/functions/str-replace.xml
index 474f368998..819b644459 100644
--- a/reference/strings/functions/str-replace.xml
+++ b/reference/strings/functions/str-replace.xml
@@ -50,6 +50,8 @@
      <term><parameter>search</parameter></term>
      <listitem>
       <para>
+       The value being searched for, otherwise known as the <emphasis>needle</emphasis>.
+       An array may be used to designate multiple needles.
       </para>
      </listitem>
     </varlistentry>
@@ -57,12 +59,18 @@
      <term><parameter>replace</parameter></term>
      <listitem>
       <para>
+       The replacement value that replaces found <parameter>search</parameter>
+       values. An array may be used to designate multiple replacements.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>subject</parameter></term>
      <listitem>
+      <para>
+       The string or array being searched and replaced on,
+       otherwise known as the <emphasis>haystack</emphasis>.
+      </para>
       <para>
        If <parameter>subject</parameter> is an array, then the search and
        replace is performed with every entry of
@@ -139,7 +147,7 @@
   &reftitle.examples;
   <para>
    <example>
-    <title><function>str_replace</function> examples</title>
+    <title>Basic <function>str_replace</function> examples</title>
     <programlisting role="php">
 <![CDATA[
 <?php
@@ -157,18 +165,37 @@ $yummy   = array("pizza", "beer", "ice cream");
 
 $newphrase = str_replace($healthy, $yummy, $phrase);
 
-// Use of the count parameter is available as of PHP 5.0.0
+// Provides: 2
 $str = str_replace("ll", "", "good golly miss molly!", $count);
-echo $count; // 2
-
+echo $count;
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+  <para>
+   <example>
+    <title>Examples of potential <function>str_replace</function> gotchas</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
 // Order of replacement
 $str     = "Line 1\nLine 2\rLine 3\r\nLine 4\n";
 $order   = array("\r\n", "\n", "\r");
 $replace = '<br />';
+
 // Processes \r\n's first so they aren't converted twice.
 $newstr = str_replace($order, $replace, $str);
 
+// Outputs F because A is replaced with B, then B is replaced with C, and so on...
+// Finally E is replaced with F, because of left to right replacements.
+$search  = array('A', 'B', 'C', 'D', 'E');
+$replace = array('B', 'C', 'D', 'E', 'F');
+$subject = 'A';
+echo str_replace($search, $replace, $subject);
+
 // Outputs: apearpearle pear
+// For the same reason mentioned above
 $letters = array('a', 'p');
 $fruit   = array('apple', 'pear');
 $text    = 'a p';
@@ -184,6 +211,14 @@ echo $output;
  <refsect1 role="notes">
   &reftitle.notes;
   &note.bin-safe;
+  <caution>
+   <title>Replacement order gotcha</title>
+   <para>
+    Because <function>str_replace</function> replaces left to right, it might
+    replace a previously inserted value when doing multiple replacements.
+    See also the examples in this document.
+   </para>
+  </caution>
   <note>
    <para>
     This function is case-sensitive. Use <function>str_ireplace</function>