Skip to content

Commit 71692b6

Browse files
derickrderickr
committed
Add Date/Time exception documentation
1 parent cd3868c commit 71692b6

23 files changed

+1042
-23
lines changed

‎reference/datetime/book.xml

Lines changed: 46 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
3+
44
<book xml:id="book.datetime" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
55
<?phpdoc extension-membership="core"?>
66
<title>Date and Time</title>
77
<titleabbrev>Date/Time</titleabbrev>
8-
8+
99
<!-- {{{ preface -->
1010
<preface xml:id="intro.datetime">
1111
&reftitle.intro;
@@ -41,22 +41,63 @@
4141
</note>
4242
</preface>
4343
<!-- }}} -->
44-
44+
4545
&reference.datetime.setup;
4646
&reference.datetime.constants;
4747
&reference.datetime.examples;
48-
48+
4949
&reference.datetime.datetime;
5050
&reference.datetime.datetimeimmutable;
5151
&reference.datetime.datetimeinterface;
5252
&reference.datetime.datetimezone;
5353
&reference.datetime.dateinterval;
5454
&reference.datetime.dateperiod;
55-
55+
5656
&reference.datetime.reference;
57+
58+
<article xml:id="datetime.error.tree">
59+
<title>Date/Time Errors and Exceptions</title>
60+
61+
<itemizedlist>
62+
<listitem>
63+
<simpara><exceptionname>DateError</exceptionname> (extends <exceptionname>Error</exceptionname>)</simpara>
64+
<itemizedlist>
65+
<listitem>
66+
<simpara><exceptionname>DateObjectError</exceptionname></simpara>
67+
<simpara><exceptionname>DateRangeError</exceptionname></simpara>
68+
</listitem>
69+
</itemizedlist>
70+
</listitem>
71+
<listitem>
72+
<simpara><exceptionname>DateException</exceptionname> (extends <exceptionname>Exception</exceptionname>)</simpara>
73+
<itemizedlist>
74+
<listitem>
75+
<itemizedlist>
76+
<listitem><simpara><exceptionname>DateInvalidOperationException</exceptionname></simpara></listitem>
77+
<listitem><simpara><exceptionname>DateInvalidTimezoneException</exceptionname></simpara></listitem>
78+
<listitem><simpara><exceptionname>DateMalformedIntervalStringException</exceptionname></simpara></listitem>
79+
<listitem><simpara><exceptionname>DateMalformedPeriodStringException</exceptionname></simpara></listitem>
80+
<listitem><simpara><exceptionname>DateMalformedStringException</exceptionname></simpara></listitem>
81+
</itemizedlist>
82+
</listitem>
83+
</itemizedlist>
84+
</listitem>
85+
</itemizedlist>
86+
</article>
87+
5788
&reference.datetime.formats;
5889
&reference.datetime.timezones;
5990

91+
&reference.datetime.dateerror;
92+
&reference.datetime.dateobjecterror;
93+
&reference.datetime.daterangeerror;
94+
&reference.datetime.dateexception;
95+
&reference.datetime.dateinvalidoperationexception;
96+
&reference.datetime.dateinvalidtimezoneexception;
97+
&reference.datetime.datemalformedintervalstringexception;
98+
&reference.datetime.datemalformedperiodstringexception;
99+
&reference.datetime.datemalformedstringexception;
100+
60101
</book>
61102

62103
<!-- Keep this comment at the end of the file

‎reference/datetime/dateerror.xml

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<phpdoc:exceptionref xml:id="class.dateerror" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
3+
<title>The DateError class</title>
4+
<titleabbrev>DateError</titleabbrev>
5+
6+
<partintro>
7+
8+
<!-- {{{ DateError intro -->
9+
<section xml:id="dateerror.intro">
10+
&reftitle.intro;
11+
<para>
12+
Thrown when the timezone database is not found, or contains invalid data.
13+
</para>
14+
<para>
15+
This error should never occur, and is not dependent on code. There are two
16+
child-exceptions (<exceptionname>DateObjectError</exceptionname> and
17+
<exceptionname>DateRangeError</exceptionname>) which are thrown depending
18+
on programmer error or range related issues.
19+
</para>
20+
</section>
21+
<!-- }}} -->
22+
23+
<section xml:id="dateerror.synopsis">
24+
&reftitle.classsynopsis;
25+
26+
<!-- {{{ Synopsis -->
27+
<classsynopsis>
28+
<ooclass><classname>DateError</classname></ooclass>
29+
30+
<!-- {{{ Class synopsis -->
31+
<classsynopsisinfo>
32+
<ooclass>
33+
<classname>DateError</classname>
34+
</ooclass>
35+
36+
<ooclass>
37+
<modifier>extends</modifier>
38+
<classname>Error</classname>
39+
</ooclass>
40+
41+
<oointerface>
42+
<interfacename>Throwable</interfacename>
43+
</oointerface>
44+
</classsynopsisinfo>
45+
<!-- }}} -->
46+
<classsynopsisinfo role="comment">&InheritedProperties;</classsynopsisinfo>
47+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('error.synopsis')/descendant::db:fieldsynopsis)"><xi:fallback/></xi:include>
48+
49+
<classsynopsisinfo role="comment">&InheritedMethods;</classsynopsisinfo>
50+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.error')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])"><xi:fallback/></xi:include>
51+
52+
</classsynopsis>
53+
<!-- }}} -->
54+
55+
</section>
56+
57+
<section role="seealso">
58+
&reftitle.seealso;
59+
<simplelist>
60+
<member><exceptionname>DateObjectError</exceptionname></member>
61+
<member><exceptionname>DateRangeError</exceptionname></member>
62+
</simplelist>
63+
</section>
64+
</partintro>
65+
66+
</phpdoc:exceptionref>
67+
<!-- Keep this comment at the end of the file
68+
Local variables:
69+
mode: sgml
70+
sgml-omittag:t
71+
sgml-shorttag:t
72+
sgml-minimize-attributes:nil
73+
sgml-always-quote-attributes:t
74+
sgml-indent-step:1
75+
sgml-indent-data:t
76+
indent-tabs-mode:nil
77+
sgml-parent-document:nil
78+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
79+
sgml-exposed-tags:nil
80+
sgml-local-catalogs:nil
81+
sgml-local-ecat-files:nil
82+
End:
83+
vim600: syn=xml fen fdm=syntax fdl=2 si
84+
vim: et tw=78 syn=sgml
85+
vi: ts=1 sw=1
86+
-->

‎reference/datetime/dateexception.xml

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<phpdoc:exceptionref xml:id="class.dateexception" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
3+
<title>The DateException class</title>
4+
<titleabbrev>DateException</titleabbrev>
5+
6+
<partintro>
7+
8+
<!-- {{{ DateException intro -->
9+
<section xml:id="dateexception.intro">
10+
&reftitle.intro;
11+
<para>
12+
Parent class of Date/Time exceptions, for issues that come to light due to
13+
user input, or free form text arguments that need to be parsed.
14+
</para>
15+
<para>
16+
The following child exceptions are thrown by the extension:
17+
<itemizedlist>
18+
<listitem><simpara><exceptionname>DateInvalidOperationException</exceptionname></simpara></listitem>
19+
<listitem><simpara><exceptionname>DateInvalidTimezoneException</exceptionname></simpara></listitem>
20+
<listitem><simpara><exceptionname>DateMalformedIntervalStringException</exceptionname></simpara></listitem>
21+
<listitem><simpara><exceptionname>DateMalformedPeriodStringException</exceptionname></simpara></listitem>
22+
<listitem><simpara><exceptionname>DateMalformedStringException</exceptionname></simpara></listitem>
23+
</itemizedlist>
24+
</para>
25+
</section>
26+
<!-- }}} -->
27+
28+
<section xml:id="dateexception.synopsis">
29+
&reftitle.classsynopsis;
30+
31+
<!-- {{{ Synopsis -->
32+
<classsynopsis>
33+
<ooclass><classname>DateException</classname></ooclass>
34+
35+
<!-- {{{ Class synopsis -->
36+
<classsynopsisinfo>
37+
<ooclass>
38+
<classname>DateException</classname>
39+
</ooclass>
40+
41+
<ooclass>
42+
<modifier>extends</modifier>
43+
<classname>Exception</classname>
44+
</ooclass>
45+
46+
<oointerface>
47+
<interfacename>Throwable</interfacename>
48+
</oointerface>
49+
</classsynopsisinfo>
50+
<!-- }}} -->
51+
<classsynopsisinfo role="comment">&InheritedProperties;</classsynopsisinfo>
52+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('exception.synopsis')/descendant::db:fieldsynopsis)"><xi:fallback/></xi:include>
53+
54+
<classsynopsisinfo role="comment">&InheritedMethods;</classsynopsisinfo>
55+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exception')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])"><xi:fallback/></xi:include>
56+
57+
</classsynopsis>
58+
<!-- }}} -->
59+
60+
</section>
61+
62+
</partintro>
63+
64+
</phpdoc:exceptionref>
65+
<!-- Keep this comment at the end of the file
66+
Local variables:
67+
mode: sgml
68+
sgml-omittag:t
69+
sgml-shorttag:t
70+
sgml-minimize-attributes:nil
71+
sgml-always-quote-attributes:t
72+
sgml-indent-step:1
73+
sgml-indent-data:t
74+
indent-tabs-mode:nil
75+
sgml-parent-document:nil
76+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
77+
sgml-exposed-tags:nil
78+
sgml-local-catalogs:nil
79+
sgml-local-ecat-files:nil
80+
End:
81+
vim600: syn=xml fen fdm=syntax fdl=2 si
82+
vim: et tw=78 syn=sgml
83+
vi: ts=1 sw=1
84+
-->

‎reference/datetime/dateinterval/construct.xml

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -121,8 +121,9 @@
121121
<refsect1 role="errors">
122122
&reftitle.errors;
123123
<para>
124-
Throws an <classname>Exception</classname> when the <parameter>duration</parameter>
125-
cannot be parsed as an interval.
124+
Throws an <classname>DateMalformedIntervalStringException</classname> when
125+
the <parameter>duration</parameter> cannot be parsed as an interval. Prior
126+
to PHP 8.3, this was <exceptionname>Exception</exceptionname>.
126127
</para>
127128
</refsect1>
128129

@@ -137,6 +138,14 @@
137138
</row>
138139
</thead>
139140
<tbody>
141+
<row>
142+
<entry>8.3.0</entry>
143+
<entry>
144+
Now throws
145+
<exceptionname>DateMalformedIntervalStringException</exceptionname>
146+
instead of <exceptionname>Exception</exceptionname>.
147+
</entry>
148+
</row>
140149
<row>
141150
<entry>8.2.0</entry>
142151
<entry>

‎reference/datetime/dateinvalidoperationexception.xml

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<phpdoc:exceptionref xml:id="class.dateinvalidoperationexception" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
3+
<title>The DateInvalidOperationException class</title>
4+
<titleabbrev>DateInvalidOperationException</titleabbrev>
5+
6+
<partintro>
7+
8+
<!-- {{{ DateInvalidOperationException intro -->
9+
<section xml:id="dateinvalidoperationexception.intro">
10+
&reftitle.intro;
11+
<para>
12+
Thrown by <methodname>DateTimeImmutable::sub</methodname> and
13+
<methodname>DateTime::sub</methodname> when an unsupported operation is
14+
attempted.
15+
</para>
16+
<para>
17+
An example of such an unsupported operation is using a
18+
<classname>DateInterval</classname> object representing relative time
19+
specifications such as <literal>next weekday</literal>, as no logical
20+
reversed statement can be constructed.
21+
</para>
22+
</section>
23+
<!-- }}} -->
24+
25+
<section xml:id="dateinvalidoperationexception.synopsis">
26+
&reftitle.classsynopsis;
27+
28+
<!-- {{{ Synopsis -->
29+
<classsynopsis>
30+
<ooclass><classname>DateInvalidOperationException</classname></ooclass>
31+
32+
<!-- {{{ Class synopsis -->
33+
<classsynopsisinfo>
34+
<ooclass>
35+
<classname>DateInvalidOperationException</classname>
36+
</ooclass>
37+
38+
<ooclass>
39+
<modifier>extends</modifier>
40+
<classname>DateException</classname>
41+
</ooclass>
42+
43+
<oointerface>
44+
<interfacename>Throwable</interfacename>
45+
</oointerface>
46+
</classsynopsisinfo>
47+
<!-- }}} -->
48+
<classsynopsisinfo role="comment">&InheritedProperties;</classsynopsisinfo>
49+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('exception.synopsis')/descendant::db:fieldsynopsis)"><xi:fallback/></xi:include>
50+
51+
<classsynopsisinfo role="comment">&InheritedMethods;</classsynopsisinfo>
52+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exception')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])"><xi:fallback/></xi:include>
53+
54+
</classsynopsis>
55+
<!-- }}} -->
56+
57+
</section>
58+
59+
</partintro>
60+
61+
</phpdoc:exceptionref>
62+
<!-- Keep this comment at the end of the file
63+
Local variables:
64+
mode: sgml
65+
sgml-omittag:t
66+
sgml-shorttag:t
67+
sgml-minimize-attributes:nil
68+
sgml-always-quote-attributes:t
69+
sgml-indent-step:1
70+
sgml-indent-data:t
71+
indent-tabs-mode:nil
72+
sgml-parent-document:nil
73+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
74+
sgml-exposed-tags:nil
75+
sgml-local-catalogs:nil
76+
sgml-local-ecat-files:nil
77+
End:
78+
vim600: syn=xml fen fdm=syntax fdl=2 si
79+
vim: et tw=78 syn=sgml
80+
vi: ts=1 sw=1
81+
-->

0 commit comments

Comments
 (0)