[doc-en] master: Document clone(), the new #[\Deprecated] targets and hrtime() on macOS (#5839)

Author: Louis-Arnaud (lacatoire) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-09-10T15:41:20+02:00 Commit: https://github.com/php/doc-en/commit/2594e1b8a9dc9c4afad73e1a6b260cabc378db17 Raw diff: https://github.com/php/doc-en/commit/2594e1b8a9dc9c4afad73e1a6b260cabc378db17.diff Document clone(), the new #[\Deprecated] targets and hrtime() on macOS (#5839) * Document clone(), the new #[\Deprecated] targets and hrtime() on macOS Add the clone() function and its withProperties parameter to the cloning page, the new #[\Deprecated] targets to the attribute page, and the macOS hrtime() implementation change to its changelog. Changed paths: M language/oop5/cloning.xml M language/predefined/attributes/deprecated.xml M reference/misc/functions/hrtime.xml Diff: diff --git a/language/oop5/cloning.xml b/language/oop5/cloning.xml index 5b7b91cfed02..91e31b4b1551 100644 --- a/language/oop5/cloning.xml +++ b/language/oop5/cloning.xml @@ -154,6 +154,59 @@ echo (clone $dateTime)->format('Y'); </screen> </example> + <sect2 xml:id="language.oop5.cloning.with-properties"> + <title>Cloning with property overrides</title> + + <simpara> + As of PHP 8.5.0, <literal>clone</literal> is also available as a function, + whose second parameter <parameter>withProperties</parameter> takes an array + mapping property names to the values the copy receives. Only the listed + properties are overridden, every other property keeps the value it was + copied with. + </simpara> + + <simpara> + The overrides are applied after + <link linkend="object.clone">__clone()</link> has run, and they honour the + visibility of the properties: a + <link linkend="language.oop5.properties.readonly-properties">readonly</link> + property can only be overridden from a scope that is allowed to write it, + which makes the function suited to methods returning a modified copy. + </simpara> + + <example> + <title>Cloning an object with property overrides</title> + <programlisting role="php"> +<![CDATA[ +<?php +class Point { + public function __construct( + public readonly int $x, + public readonly int $y, + ) {} + + public function withX(int $x): static + { + return clone($this, ['x' => $x]); + } +} + +$p = new Point(1, 2); +$q = $p->withX(10); + +echo $q->x, ' ', $q->y; +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +10 2 +]]> + </screen> + </example> + </sect2> + </sect1> <!-- Keep this comment at the end of the file diff --git a/language/predefined/attributes/deprecated.xml b/language/predefined/attributes/deprecated.xml index dcb0cef89b54..ec4b125fa7b0 100644 --- a/language/predefined/attributes/deprecated.xml +++ b/language/predefined/attributes/deprecated.xml @@ -11,6 +11,10 @@ This attribute is used to mark functionality as deprecated. Using deprecated functionality will cause an <constant>E_USER_DEPRECATED</constant> error to be emitted. </simpara> + <simpara> + As of PHP 8.5.0, this attribute can also be applied to traits and to + compile-time constants declared outside of a class. + </simpara> </section> <section xml:id="deprecated.synopsis"> @@ -100,6 +104,30 @@ This is unsafe </informalexample> </section> + <section role="changelog"> + &reftitle.changelog; + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>8.5.0</entry> + <entry> + <classname>Deprecated</classname> can now be applied to traits and to + compile-time constants declared outside of a class, the latter through + the new <constant>Attribute::TARGET_CONSTANT</constant> target. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> + <section xml:id="deprecated.seealso"> &reftitle.seealso; <simplelist> diff --git a/reference/misc/functions/hrtime.xml b/reference/misc/functions/hrtime.xml index b588082a8e5f..70f93f2e8704 100644 --- a/reference/misc/functions/hrtime.xml +++ b/reference/misc/functions/hrtime.xml @@ -46,6 +46,30 @@ </para> </refsect1> + <refsect1 role="changelog"> + &reftitle.changelog; + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>8.5.0</entry> + <entry> + On macOS, the implementation now uses + <code>clock_gettime_nsec_np(CLOCK_UPTIME_RAW)</code> instead of + <code>mach_absolute_time()</code>. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </refsect1> + <refsect1 role="examples"> &reftitle.examples; <para> @@ -79,6 +103,7 @@ Array <simplelist> <member>The <link linkend="book.hrtime">High resolution timing</link> extension</member> <member><function>microtime</function></member> + <member><function>time_nanosleep</function></member> </simplelist> </refsect1>