[doc-en] master: calendar: document the ValueErrors thrown for invalid calendar IDs and dates (#6005)

Author: qodelicious (qodelicious) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-10-24T08:34:55+02:00 Commit: https://github.com/php/doc-en/commit/c35163bad94fdaa1563b45c3c2c957eaa650a504 Raw diff: https://github.com/php/doc-en/commit/c35163bad94fdaa1563b45c3c2c957eaa650a504.diff calendar: document the ValueErrors thrown for invalid calendar IDs and dates (#6005) * calendar: document the ValueErrors thrown for invalid calendar IDs and dates * calendar: apply review suggestions * Mention the month less than 1 case for cal_to_jd Changed paths: M reference/calendar/functions/cal-days-in-month.xml M reference/calendar/functions/cal-from-jd.xml M reference/calendar/functions/cal-info.xml M reference/calendar/functions/cal-to-jd.xml M reference/calendar/functions/jdtojewish.xml M reference/calendar/functions/jewishtojd.xml M reference/calendar/functions/unixtojd.xml Diff: diff --git a/reference/calendar/functions/cal-days-in-month.xml b/reference/calendar/functions/cal-days-in-month.xml index 79ce982f404e..837a5998d24f 100644 --- a/reference/calendar/functions/cal-days-in-month.xml +++ b/reference/calendar/functions/cal-days-in-month.xml @@ -60,6 +60,40 @@ </para> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>calendar</parameter> + is not a valid calendar ID, if <parameter>month</parameter> or + <parameter>year</parameter> is outside the supported range, or if the date is not valid + in the given calendar. + </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 <parameter>calendar</parameter> + is not a valid calendar ID or the date is not valid. + 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/calendar/functions/cal-from-jd.xml b/reference/calendar/functions/cal-from-jd.xml index 7e9fcce5d91c..d645c4f3d6d6 100644 --- a/reference/calendar/functions/cal-from-jd.xml +++ b/reference/calendar/functions/cal-from-jd.xml @@ -60,6 +60,38 @@ </para> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>calendar</parameter> + is not a valid calendar ID. + </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 <parameter>calendar</parameter> + is not a valid calendar ID. + 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/calendar/functions/cal-info.xml b/reference/calendar/functions/cal-info.xml index 68d6abac438f..d8065b8e833f 100644 --- a/reference/calendar/functions/cal-info.xml +++ b/reference/calendar/functions/cal-info.xml @@ -74,6 +74,38 @@ </para> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>calendar</parameter> + is neither <literal>-1</literal> nor a valid calendar ID. + </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 <parameter>calendar</parameter> + is not a valid calendar ID. + 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/calendar/functions/cal-to-jd.xml b/reference/calendar/functions/cal-to-jd.xml index 8735264f37c8..7934b3e474ea 100644 --- a/reference/calendar/functions/cal-to-jd.xml +++ b/reference/calendar/functions/cal-to-jd.xml @@ -80,6 +80,40 @@ </para> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>calendar</parameter> + is not a valid calendar ID, if <parameter>month</parameter> is less than <literal>1</literal>, + or if <parameter>month</parameter>, <parameter>day</parameter> or <parameter>year</parameter> + exceeds the supported 32-bit range. Other invalid dates return <literal>0</literal>. + </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 <parameter>calendar</parameter> + is not a valid calendar ID. + Previously, an <constant>E_WARNING</constant> was raised and &false; was returned. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </refsect1> + <refsect1 role="seealso"> &reftitle.seealso; <para> diff --git a/reference/calendar/functions/jdtojewish.xml b/reference/calendar/functions/jdtojewish.xml index 45df170ad183..d33362d663d2 100644 --- a/reference/calendar/functions/jdtojewish.xml +++ b/reference/calendar/functions/jdtojewish.xml @@ -64,6 +64,38 @@ </para> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>hebrew</parameter> is &true; + and the year is not between <literal>1</literal> and <literal>9999</literal>. + </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 the year is out of range + when <parameter>hebrew</parameter> is &true;. + 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/calendar/functions/jewishtojd.xml b/reference/calendar/functions/jewishtojd.xml index cee336618610..8f1218c43b88 100644 --- a/reference/calendar/functions/jewishtojd.xml +++ b/reference/calendar/functions/jewishtojd.xml @@ -68,6 +68,14 @@ </para> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>year</parameter> + does not fit in a 32-bit integer. + </simpara> + </refsect1> + <refsect1 role="seealso"> &reftitle.seealso; <para> diff --git a/reference/calendar/functions/unixtojd.xml b/reference/calendar/functions/unixtojd.xml index b2d81aedf686..994373bcd340 100644 --- a/reference/calendar/functions/unixtojd.xml +++ b/reference/calendar/functions/unixtojd.xml @@ -43,6 +43,14 @@ </para> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>timestamp</parameter> + is negative. + </simpara> + </refsect1> + <refsect1 role="changelog"> &reftitle.changelog; <informaltable> @@ -54,6 +62,13 @@ </row> </thead> <tbody> + <row> + <entry>8.0.0</entry> + <entry> + Now throws a <exceptionname>ValueError</exceptionname> if <parameter>timestamp</parameter> + is negative. Previously, &false; was returned. + </entry> + </row> <row> <entry>8.0.0</entry> <entry>