From ef05457faa8045529ef7d0ec97309667838feb44 Mon Sep 17 00:00:00 2001
From: Christoph Michael Becker <cmb@php.net>
Date: Wed, 4 Nov 2020 10:08:57 +0000
Subject: [PATCH] Fix #60314: Metaphone returns fewer phonemes than defined

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@351215 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/strings/functions/metaphone.xml | 32 ++++++++++++++++++++---
 1 file changed, 29 insertions(+), 3 deletions(-)

diff --git a/reference/strings/functions/metaphone.xml b/reference/strings/functions/metaphone.xml
index 7da251bfc3..f1485aa80f 100644
--- a/reference/strings/functions/metaphone.xml
+++ b/reference/strings/functions/metaphone.xml
@@ -47,7 +47,9 @@
      <listitem>
       <para>
        This parameter restricts the returned metaphone key to 
-       <parameter>phonemes</parameter> characters in length.
+       <parameter>phonemes</parameter> <emphasis>characters</emphasis> in length.
+       However, the resulting phonemes are always transcribed completely, so the
+       resulting string length may be slightly longer than <parameter>phonemes</parameter>.
        The default value of <literal>0</literal> means no restriction.
       </para>
      </listitem>
@@ -76,7 +78,7 @@ var_dump(metaphone('programmer'));
 ?>
 ]]>
     </programlisting>
-    &example.outputs.similar;
+    &example.outputs;
     <screen>
 <![CDATA[
 string(7) "PRKRMNK"
@@ -96,7 +98,7 @@ var_dump(metaphone('programmer', 5));
 ?>
 ]]>
     </programlisting>
-    &example.outputs.similar;
+    &example.outputs;
     <screen>
 <![CDATA[
 string(5) "PRKRM"
@@ -105,6 +107,30 @@ string(5) "PRKRM"
     </screen>
    </example><!-- }}} -->
   </para>
+  <para>
+   <example xml:id="metaphone.example.phonemes-overlong">
+    <title>Using the <parameter>phonemes</parameter> parameter</title>
+    <simpara>
+     In this example, <function>metaphone</function> is advised to produce a string
+     of five characters, but that would require to split the final phoneme
+     (<literal>'x'</literal> is supposed to be transcribed to <literal>'KS'</literal>),
+     so the function returns a string with six characters.
+    </simpara>
+    <programlisting role="php">
+<![CDATA[
+<?php
+var_dump(metaphone('Asterix', 5));
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+string(6) "ASTRKS"
+]]>
+    </screen>
+   </example>
+  </para>
  </refsect1><!-- }}} -->
 
 </refentry>