Fix #81383: Locale::lookup / locale_lookup incorrectly returns null i…

…nstead of default INTL_MAX_LOCALE_LEN limits the length of accepted locale. Anything longer than that will result in a failure and the value returned will either be `null` or `false`. So documentation must reflect that in the return types. Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de> Closes GH-883.
php · Aug 27, 2021 · 235297d · 235297d
1 parent 0612680
commit 235297d
Show file tree

Hide file tree

Showing 10 changed files with 46 additions and 31 deletions.
diff --git a/language-snippets.ent b/language-snippets.ent
@@ -1010,6 +1010,8 @@ Passing untrusted data to this parameter is <emphasis>insecure</emphasis>, unles
 
 <!ENTITY intl.codepoint.example 'Testing different code points'>
 
+<!ENTITY intl.locale-len.return '<para xmlns="http://docbook.org/ns/docbook">Returns &null; when the length of <parameter>locale</parameter> exceeds <constant>INTL_MAX_LOCALE_LEN</constant>.</para>'>
+
 <!ENTITY intl.property.parameter '<para xmlns="http://docbook.org/ns/docbook">The Unicode property to lookup (see the <literal>IntlChar::PROPERTY_*</literal> constants).</para>'>
 
 <!ENTITY intl.property.example 'Testing different properties'>

diff --git a/reference/intl/locale/accept-from-http.xml b/reference/intl/locale/accept-from-http.xml
@@ -15,15 +15,15 @@
   <methodsynopsis>
    <modifier>public</modifier>
    <modifier>static</modifier>
-   <type>string</type>
+   <type class="union"><type>string</type><type>false</type></type>
    <methodname>Locale::acceptFromHttp</methodname>
    <methodparam><type>string</type><parameter>header</parameter></methodparam>
   </methodsynopsis>
   <para>
    &style.procedural;
   </para>
   <methodsynopsis>
-   <type>string</type>
+   <type class="union"><type>string</type><type>false</type></type>
    <methodname>locale_accept_from_http</methodname>
    <methodparam><type>string</type><parameter>header</parameter></methodparam>
   </methodsynopsis>
@@ -55,6 +55,10 @@
   <para>
    The corresponding locale identifier.
   </para>
+  <para>
+   Returns &false; when the length of <parameter>header</parameter> exceeds
+   <constant>INTL_MAX_LOCALE_LEN</constant>.
+  </para>
  </refsect1>
 
  <refsect1 role="examples">

diff --git a/reference/intl/locale/canonicalize.xml b/reference/intl/locale/canonicalize.xml
@@ -11,7 +11,9 @@
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <modifier>public</modifier> <modifier>static</modifier> <type>string</type><methodname>Locale::canonicalize</methodname>
+   <modifier>public</modifier> <modifier>static</modifier>
+   <type class="union"><type>string</type><type>null</type></type>
+   <methodname>Locale::canonicalize</methodname>
    <methodparam><type>string</type><parameter>locale</parameter></methodparam>
   </methodsynopsis>
   <para>
@@ -29,7 +31,7 @@
     <term><parameter>locale</parameter></term>
     <listitem>
      <para>
-      
+
      </para>
     </listitem>
    </varlistentry>
@@ -39,8 +41,9 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-
+   Canonicalized locale string.
   </para>
+  &intl.locale-len.return;
  </refsect1>
 
 

diff --git a/reference/intl/locale/filter-matches.xml b/reference/intl/locale/filter-matches.xml
@@ -15,7 +15,7 @@
   <methodsynopsis>
    <modifier>public</modifier>
    <modifier>static</modifier>
-   <type>bool</type>
+   <type class="union"><type>bool</type><type>null</type></type>
    <methodname>Locale::filterMatches</methodname>
    <methodparam><type>string</type><parameter>langtag</parameter></methodparam>
    <methodparam><type>string</type><parameter>locale</parameter></methodparam>
@@ -25,7 +25,7 @@
    &style.procedural;
   </para>
   <methodsynopsis>
-   <type>bool</type>
+   <type class="union"><type>bool</type><type>null</type></type>
    <methodname>locale_filter_matches</methodname>
    <methodparam><type>string</type><parameter>langtag</parameter></methodparam>
    <methodparam><type>string</type><parameter>locale</parameter></methodparam>
@@ -62,7 +62,7 @@
      <listitem>
      <para>
       If true, the arguments will be converted to canonical form before
-      matching. 
+      matching.
      </para>
      </listitem>
     </varlistentry>
@@ -76,6 +76,7 @@
   <para>
    &true; if $locale matches $langtag &false; otherwise.
   </para>
+  &intl.locale-len.return;
  </refsect1>
 
  <refsect1 role="examples">
@@ -85,9 +86,9 @@
    <programlisting role="php">
 <![CDATA[
 <?php
-echo (locale_filter_matches('de-DEVA','de-DE', false)) ? "Matches" : "Does not match"; 
+echo (locale_filter_matches('de-DEVA','de-DE', false)) ? "Matches" : "Does not match";
 echo '; ';
-echo (locale_filter_matches('de-DE_1996','de-DE', false)) ? "Matches" : "Does not match"; 
+echo (locale_filter_matches('de-DE_1996','de-DE', false)) ? "Matches" : "Does not match";
 ?>
 ]]>
    </programlisting>
@@ -97,9 +98,9 @@ echo (locale_filter_matches('de-DE_1996','de-DE', false)) ? "Matches" : "Does no
    <programlisting role="php">
 <![CDATA[
 <?php
-echo (Locale::filterMatches('de-DEVA','de-DE', false)) ? "Matches" : "Does not match"; 
+echo (Locale::filterMatches('de-DEVA','de-DE', false)) ? "Matches" : "Does not match";
 echo '; ';
-echo (Locale::filterMatches('de-DE-1996','de-DE', false)) ? "Matches" : "Does not match"; 
+echo (Locale::filterMatches('de-DE-1996','de-DE', false)) ? "Matches" : "Does not match";
 ?>
 ]]>
    </programlisting>

diff --git a/reference/intl/locale/get-all-variants.xml b/reference/intl/locale/get-all-variants.xml
@@ -15,15 +15,15 @@
   <methodsynopsis>
    <modifier>public</modifier>
    <modifier>static</modifier>
-   <type>array</type>
+   <type class="union"><type>array</type><type>null</type></type>
    <methodname>Locale::getAllVariants</methodname>
    <methodparam><type>string</type><parameter>locale</parameter></methodparam>
   </methodsynopsis>
   <para>
    &style.procedural;
   </para>
   <methodsynopsis>
-   <type>array</type>
+   <type class="union"><type>array</type><type>null</type></type>
    <methodname>locale_get_all_variants</methodname>
    <methodparam><type>string</type><parameter>locale</parameter></methodparam>
   </methodsynopsis>
@@ -52,9 +52,10 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   The <type>array</type> containing the list of all variants subtag for the locale 
+   The <type>array</type> containing the list of all variants subtag for the locale
    or &null; if not present
   </para>
+  &intl.locale-len.return;
  </refsect1>
 
  <refsect1 role="examples">

diff --git a/reference/intl/locale/get-keywords.xml b/reference/intl/locale/get-keywords.xml
@@ -15,15 +15,15 @@
   <methodsynopsis>
    <modifier>public</modifier>
    <modifier>static</modifier>
-   <type>array</type>
+   <type class="union"><type>array</type><type>null</type></type>
    <methodname>Locale::getKeywords</methodname>
    <methodparam><type>string</type><parameter>locale</parameter></methodparam>
   </methodsynopsis>
   <para>
    &style.procedural;
   </para>
   <methodsynopsis>
-   <type>array</type>
+   <type class="union"><type>array</type><type>null</type></type>
    <methodname>locale_get_keywords</methodname>
    <methodparam><type>string</type><parameter>locale</parameter></methodparam>
   </methodsynopsis>
@@ -54,6 +54,7 @@
   <para>
    Associative <type>array</type> containing the keyword-value pairs for this locale
   </para>
+  &intl.locale-len.return;
  </refsect1>
 
  <refsect1 role="examples">
@@ -66,7 +67,7 @@
 $keywords_arr = locale_get_keywords('de_DE@currency=EUR;collation=PHONEBOOK');
 if ($keywords_arr) {
     foreach ($keywords_arr as $key => $value) {
-        echo "$key = $value\n"; 
+        echo "$key = $value\n";
     }
 }
 ?>
@@ -81,7 +82,7 @@ if ($keywords_arr) {
 $keywords_arr = Locale::getKeywords('de_DE@currency=EUR;collation=PHONEBOOK');
 if ($keywords_arr) {
     foreach ($keywords_arr as $key => $value) {
-        echo "$key = $value\n"; 
+        echo "$key = $value\n";
     }
 }
 ?>

diff --git a/reference/intl/locale/get-primary-language.xml b/reference/intl/locale/get-primary-language.xml
@@ -15,15 +15,15 @@
   <methodsynopsis>
    <modifier>public</modifier>
    <modifier>static</modifier>
-   <type>string</type>
+   <type class="union"><type>string</type><type>null</type></type>
    <methodname>Locale::getPrimaryLanguage</methodname>
    <methodparam><type>string</type><parameter>locale</parameter></methodparam>
   </methodsynopsis>
   <para>
    &style.procedural;
   </para>
   <methodsynopsis>
-   <type>string</type>
+   <type class="union"><type>string</type><type>null</type></type>
    <methodname>locale_get_primary_language</methodname>
    <methodparam><type>string</type><parameter>locale</parameter></methodparam>
   </methodsynopsis>
@@ -52,8 +52,9 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   The language code associated with the language or &null; in case of error.
+   The language code associated with the language.
   </para>
+  &intl.locale-len.return;
  </refsect1>
 
  <refsect1 role="examples">

diff --git a/reference/intl/locale/get-region.xml b/reference/intl/locale/get-region.xml
@@ -15,15 +15,15 @@
   <methodsynopsis>
    <modifier>public</modifier>
    <modifier>static</modifier>
-   <type>string</type>
+   <type class="union"><type>string</type><type>null</type></type>
    <methodname>Locale::getRegion</methodname>
    <methodparam><type>string</type><parameter>locale</parameter></methodparam>
   </methodsynopsis>
   <para>
    &style.procedural;
   </para>
   <methodsynopsis>
-   <type>string</type>
+   <type class="union"><type>string</type><type>null</type></type>
    <methodname>locale_get_region</methodname>
    <methodparam><type>string</type><parameter>locale</parameter></methodparam>
   </methodsynopsis>
@@ -54,6 +54,7 @@
   <para>
    The region subtag for the locale or &null; if not present
   </para>
+  &intl.locale-len.return;
  </refsect1>
 
  <refsect1 role="examples">

diff --git a/reference/intl/locale/lookup.xml b/reference/intl/locale/lookup.xml
@@ -15,7 +15,7 @@
   <methodsynopsis>
    <modifier>public</modifier>
    <modifier>static</modifier>
-   <type>string</type>
+   <type class="union"><type>string</type><type>null</type></type>
    <methodname>Locale::lookup</methodname>
    <methodparam><type>array</type><parameter>langtag</parameter></methodparam>
    <methodparam><type>string</type><parameter>locale</parameter></methodparam>
@@ -26,17 +26,17 @@
    &style.procedural;
   </para>
   <methodsynopsis>
-   <type>string</type>
+   <type class="union"><type>string</type><type>null</type></type>
    <methodname>locale_lookup</methodname>
    <methodparam><type>array</type><parameter>langtag</parameter></methodparam>
    <methodparam><type>string</type><parameter>locale</parameter></methodparam>
    <methodparam choice="opt"><type>bool</type><parameter>canonicalize</parameter><initializer>&false;</initializer></methodparam>
    <methodparam choice="opt"><type>string</type><parameter>default</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Searches the items in <parameter>langtag</parameter> for the best match to 
+   Searches the items in <parameter>langtag</parameter> for the best match to
    the language range specified in <parameter>locale</parameter> according to
-   RFC 4647's lookup algorithm. 
+   RFC 4647's lookup algorithm.
   </para>
  </refsect1>
 
@@ -48,7 +48,7 @@
      <term><parameter>langtag</parameter></term>
      <listitem>
       <para>
-       An <type>array</type> containing a list of language tags to compare to 
+       An <type>array</type> containing a list of language tags to compare to
        <parameter>locale</parameter>. Maximum 100 items allowed.
       </para>
      </listitem>
@@ -90,6 +90,7 @@
   <para>
    The closest matching language tag or default value.
   </para>
+  &intl.locale-len.return;
  </refsect1>
 
  <refsect1 role="examples">

diff --git a/reference/intl/locale/parse-locale.xml b/reference/intl/locale/parse-locale.xml
@@ -15,15 +15,15 @@
   <methodsynopsis>
    <modifier>public</modifier>
    <modifier>static</modifier>
-   <type>array</type>
+   <type class="union"><type>array</type><type>null</type></type>
    <methodname>Locale::parseLocale</methodname>
    <methodparam><type>string</type><parameter>locale</parameter></methodparam>
   </methodsynopsis>
   <para>
    &style.procedural;
   </para>
   <methodsynopsis>
-   <type>array</type>
+   <type class="union"><type>array</type><type>null</type></type>
    <methodname>locale_parse</methodname>
    <methodparam><type>string</type><parameter>locale</parameter></methodparam>
   </methodsynopsis>