[DOC-CVS] [doc-en] master: DateTime::__(un)serialize Improve the examples, add an Error warning, amend method names in the Example section (#4661)

Author: Mikhail Alferov (mmalferov)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-08-19T12:01:14+02:00

Commit: https://github.com/php/doc-en/commit/d0a271b7ed3149b465a364fadd3f1212d01efd22
Raw diff: https://github.com/php/doc-en/commit/d0a271b7ed3149b465a364fadd3f1212d01efd22.diff

DateTime::__(un)serialize Improve the examples, add an Error warning, amend method names in the Example section (#4661)

* serialize.xml Show how the method works

* serialize.xml Add an Error warning if __unserialize() is missing

* unserialize.xml Show how the method works

* unserialize.xml No value is returned

* unserialize.xml Add an Error warning

* Update unserialize.xml

I think an explicit reference to calling the parent constructor better reflects the essence of the method's work

* Fix the documented output and use simpara in the warnings

* Use simpara in the return values section too

---------

Co-authored-by: lacatoire <[email protected]>

Changed paths:
  M  reference/datetime/datetimeinterface/serialize.xml
  M  reference/datetime/datetimeinterface/unserialize.xml


Diff:

diff --git a/reference/datetime/datetimeinterface/serialize.xml b/reference/datetime/datetimeinterface/serialize.xml
index 090575572e98..bafd57fb53fc 100644
--- a/reference/datetime/datetimeinterface/serialize.xml
+++ b/reference/datetime/datetimeinterface/serialize.xml
@@ -43,23 +43,50 @@
  <refsect1 role="examples">
   &reftitle.examples;
   <example>
-   <title><function>DateTime::serialize</function> example</title>
+   <title><methodname>DateTime::__serialize</methodname> example</title>
    <programlisting role="php">
 <![CDATA[
 <?php
-$date = new DateTime('2025-03-27');
+
+class CustomDateTimeImmutable extends DateTimeImmutable
+{
+    #[\Override]
+    public function __serialize(): array
+    {
+        return [
+            'date' => $this->format(DateTimeInterface::W3C),
+            'timestamp' => $this->getTimestamp(),
+            'timezone' => $this->getTimeZone()->getName(),
+            'to' => 'Drink a cup of coffee',
+        ];
+    }
+}
+
+$date = new CustomDateTimeImmutable('2025-03-27');
 var_dump(serialize($date));
 ]]>
    </programlisting>
    &example.outputs;
    <screen>
 <![CDATA[
-string(114) "O:8:"DateTime":3:{s:4:"date";s:26:"2025-03-27 00:00:00.000000";s:13:"timezone_type";i:3;s:8:"timezone";s:3:"UTC";}"
+string(171) "O:23:"CustomDateTimeImmutable":4:{s:4:"date";s:25:"2025-03-27T00:00:00+00:00";s:9:"timestamp";i:1743033600;s:8:"timezone";s:3:"UTC";s:2:"to";s:21:"Drink a cup of coffee";}"
 ]]>
    </screen>
   </example>
  </refsect1>
 
+ <refsect1 role="notes">
+  &reftitle.notes;
+  <warning>
+   <simpara>
+    An <exceptionname>Error</exceptionname> is thrown when attempting to
+    unserialize a custom <classname>DateTime</classname> object if
+    <link linkend="object.serialize">__serialize()</link> is defined but
+    <link linkend="object.unserialize">__unserialize()</link> is missing.
+   </simpara>
+  </warning>
+ </refsect1>
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <simplelist>
diff --git a/reference/datetime/datetimeinterface/unserialize.xml b/reference/datetime/datetimeinterface/unserialize.xml
index 4af5fb5dab72..0f0ed168f408 100644
--- a/reference/datetime/datetimeinterface/unserialize.xml
+++ b/reference/datetime/datetimeinterface/unserialize.xml
@@ -43,38 +43,66 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   The <classname>DateTime</classname> object.
-  </para>
+  <simpara>
+   &return.void;
+  </simpara>
  </refsect1>
 
  <refsect1 role="examples">
   &reftitle.examples;
   <example>
-   <title><function>DateTime::unserialize</function> example</title>
+   <title><methodname>DateTime::__unserialize</methodname> example</title>
    <programlisting role="php">
 <![CDATA[
 <?php
-$serializedDate = 'O:8:"DateTime":3:{s:4:"date";s:26:"2025-03-27 00:00:00.000000";s:13:"timezone_type";i:3;s:8:"timezone";s:3:"UTC";}';
-var_dump(unserialize($serializedDate));
+
+class CustomDateTimeImmutable extends DateTimeImmutable
+{
+    #[\Override]
+    public function __unserialize(array $data): void
+    {
+        echo "Time to `{$data['to']}`:\n\n";
+
+        parent::__construct($data['date'], new DateTimeZone($data['timezone']));
+    }
+}
+
+$serializedData = 'O:23:"CustomDateTimeImmutable":4:{s:4:"date";s:25:"2025-03-27T00:00:00+00:00";s:9:"timestamp";i:1743033600;s:8:"timezone";s:3:"UTC";s:2:"to";s:21:"Drink a cup of coffee";}';
+
+var_dump(unserialize($serializedData));
+
 ]]>
    </programlisting>
    &example.outputs;
    <screen>
 <![CDATA[
-object(DateTime)#1 (3) {
+Time to `Drink a cup of coffee`:
+
+object(CustomDateTimeImmutable)#1 (3) {
   ["date"]=>
   string(26) "2025-03-27 00:00:00.000000"
   ["timezone_type"]=>
-  int(3)
+  int(1)
   ["timezone"]=>
-  string(3) "UTC"
+  string(6) "+00:00"
 }
 ]]>
    </screen>
   </example>
  </refsect1>
 
+ <refsect1 role="notes">
+  &reftitle.notes;
+  <warning>
+   <simpara>
+    An <exceptionname>Error</exceptionname> is thrown when attempting to
+    unserialize a custom <classname>DateTime</classname> object if
+    <link linkend="object.serialize">__serialize()</link> is defined but
+    <link linkend="object.unserialize">__unserialize()</link> is missing.
+   </simpara>
+  </warning>
+ </refsect1>
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <simplelist>