[doc-en] master: Document the missing ValueErrors for the gettext functions (#6044)

Author: Alejandro Borrego (abp002) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-11-08T20:03:40+01:00 Commit: https://github.com/php/doc-en/commit/2a1443c84d0a3eae93612e5385156fd99c7f37cd Raw diff: https://github.com/php/doc-en/commit/2a1443c84d0a3eae93612e5385156fd99c7f37cd.diff Document the missing ValueErrors for the gettext functions (#6044) * Document the missing ValueErrors for the gettext functions * Document the null byte ValueError in bindtextdomain() --------- Co-authored-by: Alejandro Borrego <210245044+abp002@users.noreply.github.com> Changed paths: M reference/gettext/functions/bind-textdomain-codeset.xml M reference/gettext/functions/bindtextdomain.xml M reference/gettext/functions/dcgettext.xml M reference/gettext/functions/dcngettext.xml M reference/gettext/functions/gettext.xml M reference/gettext/functions/ngettext.xml M reference/gettext/functions/textdomain.xml Diff: diff --git a/reference/gettext/functions/bind-textdomain-codeset.xml b/reference/gettext/functions/bind-textdomain-codeset.xml index 7cb7e9929f1e..0bc60033ac93 100644 --- a/reference/gettext/functions/bind-textdomain-codeset.xml +++ b/reference/gettext/functions/bind-textdomain-codeset.xml @@ -47,16 +47,18 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; - <para> - A <type>string</type> on success. - </para> + <simpara> + Returns the encoding currently set for <parameter>domain</parameter>, + or &false; if none has been set or on failure. + On musl prior to 1.2.6, &false; is always returned. + </simpara> </refsect1> <refsect1 role="errors"> &reftitle.errors; <simpara> Throws a <exceptionname>ValueError</exceptionname> if <parameter>domain</parameter> - is the empty <type>string</type>. + is the empty <type>string</type> or longer than 1024 bytes. </simpara> </refsect1> @@ -92,6 +94,14 @@ Previously, it was not possible to retrieve the currently set encoding. </entry> </row> + <row> + <entry>8.0.0</entry> + <entry> + Now throws a <exceptionname>ValueError</exceptionname> if <parameter>domain</parameter> + is too long. Previously, an <constant>E_WARNING</constant> was raised + and &false; was returned. + </entry> + </row> </tbody> </tgroup> </informaltable> diff --git a/reference/gettext/functions/bindtextdomain.xml b/reference/gettext/functions/bindtextdomain.xml index e7aa75aaef50..d230e7640bf0 100644 --- a/reference/gettext/functions/bindtextdomain.xml +++ b/reference/gettext/functions/bindtextdomain.xml @@ -34,11 +34,11 @@ <varlistentry> <term><parameter>directory</parameter></term> <listitem> - <para> + <simpara> The directory path. - An empty string means the current directory. + An empty <type>string</type> or <literal>"0"</literal> means the current directory. If &null;, the currently set directory is returned. - </para> + </simpara> </listitem> </varlistentry> </variablelist> @@ -47,10 +47,23 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; - <para> + <simpara> The full pathname for the <parameter>domain</parameter> currently being set, &return.falseforfailure;. - </para> + &false; is also returned if <parameter>directory</parameter> does not exist. + </simpara> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>domain</parameter> + is the empty <type>string</type> or longer than 1024 bytes. + </simpara> + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>domain</parameter> + or <parameter>directory</parameter> contains null bytes. + </simpara> </refsect1> <refsect1 role="changelog"> @@ -64,6 +77,13 @@ </row> </thead> <tbody> + <row> + <entry>8.4.4</entry> + <entry> + Now throws a <exceptionname>ValueError</exceptionname> if <parameter>domain</parameter> + or <parameter>directory</parameter> contains null bytes. + </entry> + </row> <row> <entry>8.4.0</entry> <entry> @@ -78,6 +98,14 @@ Previously, it was not possible to retrieve the currently set directory. </entry> </row> + <row> + <entry>8.0.0</entry> + <entry> + Now throws a <exceptionname>ValueError</exceptionname> if <parameter>domain</parameter> + is the empty <type>string</type> or too long. Previously, an + <constant>E_WARNING</constant> was raised and &false; was returned. + </entry> + </row> </tbody> </tgroup> </informaltable> diff --git a/reference/gettext/functions/dcgettext.xml b/reference/gettext/functions/dcgettext.xml index 8471b904af47..8b8eb35541f9 100644 --- a/reference/gettext/functions/dcgettext.xml +++ b/reference/gettext/functions/dcgettext.xml @@ -58,6 +58,54 @@ A <type>string</type> on success. </para> </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>domain</parameter> + is the empty <type>string</type> or longer than 1024 bytes. + </simpara> + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>message</parameter> + is longer than 4096 bytes. + </simpara> + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>category</parameter> + is <constant>LC_ALL</constant>. + </simpara> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>8.4.0</entry> + <entry> + Now throws a <exceptionname>ValueError</exceptionname> if <parameter>domain</parameter> + is the empty <type>string</type> or <parameter>category</parameter> + is <constant>LC_ALL</constant>. + </entry> + </row> + <row> + <entry>8.0.0</entry> + <entry> + Now throws a <exceptionname>ValueError</exceptionname> if an argument + is too long. Previously, an <constant>E_WARNING</constant> was raised + and &false; was returned. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </refsect1> <refsect1 role="seealso"> &reftitle.seealso; diff --git a/reference/gettext/functions/dcngettext.xml b/reference/gettext/functions/dcngettext.xml index 83b20edf2aaa..ad542d9ed9d7 100644 --- a/reference/gettext/functions/dcngettext.xml +++ b/reference/gettext/functions/dcngettext.xml @@ -71,6 +71,54 @@ A <type>string</type> on success. </para> </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>domain</parameter> + is the empty <type>string</type> or longer than 1024 bytes. + </simpara> + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>singular</parameter> + or <parameter>plural</parameter> is longer than 4096 bytes. + </simpara> + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>category</parameter> + is <constant>LC_ALL</constant>. + </simpara> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>8.4.0</entry> + <entry> + Now throws a <exceptionname>ValueError</exceptionname> if <parameter>domain</parameter> + is the empty <type>string</type> or <parameter>category</parameter> + is <constant>LC_ALL</constant>. + </entry> + </row> + <row> + <entry>8.0.0</entry> + <entry> + Now throws a <exceptionname>ValueError</exceptionname> if an argument + is too long. Previously, an <constant>E_WARNING</constant> was raised + and &false; was returned. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </refsect1> <refsect1 role="seealso"> &reftitle.seealso; diff --git a/reference/gettext/functions/gettext.xml b/reference/gettext/functions/gettext.xml index f7d232e753fa..989a6217681f 100644 --- a/reference/gettext/functions/gettext.xml +++ b/reference/gettext/functions/gettext.xml @@ -41,6 +41,38 @@ </para> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>message</parameter> + is longer than 4096 bytes. + </simpara> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>8.0.0</entry> + <entry> + Now throws a <exceptionname>ValueError</exceptionname> if an argument + is too long. Previously, an <constant>E_WARNING</constant> was raised + and &false; was returned. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </refsect1> + <refsect1 role="examples"> &reftitle.examples; <para> diff --git a/reference/gettext/functions/ngettext.xml b/reference/gettext/functions/ngettext.xml index 0e0ae8378f2f..36360509d49c 100644 --- a/reference/gettext/functions/ngettext.xml +++ b/reference/gettext/functions/ngettext.xml @@ -62,6 +62,38 @@ </para> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>singular</parameter> + or <parameter>plural</parameter> is longer than 4096 bytes. + </simpara> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>8.0.0</entry> + <entry> + Now throws a <exceptionname>ValueError</exceptionname> if an argument + is too long. Previously, an <constant>E_WARNING</constant> was raised + and &false; was returned. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </refsect1> + <refsect1 role="examples"> &reftitle.examples; <para> diff --git a/reference/gettext/functions/textdomain.xml b/reference/gettext/functions/textdomain.xml index c552dbee38af..d1975528af47 100644 --- a/reference/gettext/functions/textdomain.xml +++ b/reference/gettext/functions/textdomain.xml @@ -48,7 +48,11 @@ &reftitle.errors; <simpara> Throws a <exceptionname>ValueError</exceptionname> if <parameter>domain</parameter> - is the empty <type>string</type>. + is the empty <type>string</type> or longer than 1024 bytes. + </simpara> + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>domain</parameter> + is <literal>"0"</literal>. </simpara> </refsect1> @@ -67,7 +71,8 @@ <entry>8.4.0</entry> <entry> Now throws a <exceptionname>ValueError</exceptionname> if <parameter>domain</parameter> - is the empty <type>string</type>. + is the empty <type>string</type> or <literal>"0"</literal>. + Previously, both returned the current message domain without changing it. </entry> </row> <row> @@ -77,6 +82,14 @@ Previously, the parameter always had to be specified. </entry> </row> + <row> + <entry>8.0.0</entry> + <entry> + Now throws a <exceptionname>ValueError</exceptionname> if an argument + is too long. Previously, an <constant>E_WARNING</constant> was raised + and &false; was returned. + </entry> + </row> </tbody> </tgroup> </informaltable>