From 235297daeda99773f68ee59e2efff048e98c1dc5 Mon Sep 17 00:00:00 2001
From: Adrien Crivelli <adrien.crivelli@gmail.com>
Date: Fri, 27 Aug 2021 14:49:11 +0900
Subject: [PATCH] Fix #81383: Locale::lookup / locale_lookup incorrectly
 returns null instead 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.
---
 language-snippets.ent                          |  2 ++
 reference/intl/locale/accept-from-http.xml     |  8 ++++++--
 reference/intl/locale/canonicalize.xml         |  9 ++++++---
 reference/intl/locale/filter-matches.xml       | 15 ++++++++-------
 reference/intl/locale/get-all-variants.xml     |  7 ++++---
 reference/intl/locale/get-keywords.xml         |  9 +++++----
 reference/intl/locale/get-primary-language.xml |  7 ++++---
 reference/intl/locale/get-region.xml           |  5 +++--
 reference/intl/locale/lookup.xml               | 11 ++++++-----
 reference/intl/locale/parse-locale.xml         |  4 ++--
 10 files changed, 46 insertions(+), 31 deletions(-)

diff --git a/language-snippets.ent b/language-snippets.ent
index e59c05dd5eae..de717575cf24 100644
--- 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
index b84ba84c0499..4553ec4c86a4 100644
--- a/reference/intl/locale/accept-from-http.xml
+++ b/reference/intl/locale/accept-from-http.xml
@@ -15,7 +15,7 @@
   <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>
@@ -23,7 +23,7 @@
    &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
index 501d6a46babe..af7d971e24a0 100644
--- 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
index ab72498c4ee7..30feb51cc3d9 100644
--- 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
index cd05ef1734c7..b841075af794 100644
--- a/reference/intl/locale/get-all-variants.xml
+++ b/reference/intl/locale/get-all-variants.xml
@@ -15,7 +15,7 @@
   <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>
@@ -23,7 +23,7 @@
    &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
index c546cdea9698..5832058b05fd 100644
--- a/reference/intl/locale/get-keywords.xml
+++ b/reference/intl/locale/get-keywords.xml
@@ -15,7 +15,7 @@
   <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>
@@ -23,7 +23,7 @@
    &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
index f25d63a86a9f..97d49898119b 100644
--- a/reference/intl/locale/get-primary-language.xml
+++ b/reference/intl/locale/get-primary-language.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::getPrimaryLanguage</methodname>
    <methodparam><type>string</type><parameter>locale</parameter></methodparam>
   </methodsynopsis>
@@ -23,7 +23,7 @@
    &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
index 1ecf758dae3c..eba93917d910 100644
--- a/reference/intl/locale/get-region.xml
+++ b/reference/intl/locale/get-region.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::getRegion</methodname>
    <methodparam><type>string</type><parameter>locale</parameter></methodparam>
   </methodsynopsis>
@@ -23,7 +23,7 @@
    &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
index fb1d90ddb2dd..9fd6ae7b8000 100644
--- 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,7 +26,7 @@
    &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>
@@ -34,9 +34,9 @@
    <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
index d6acbe7fc0c1..a615d07f5a25 100644
--- a/reference/intl/locale/parse-locale.xml
+++ b/reference/intl/locale/parse-locale.xml
@@ -15,7 +15,7 @@
   <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>
@@ -23,7 +23,7 @@
    &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>