[Sync-En] Document clone(), PHP 8.5 BC changes and attribute signatures

language/oop5/changelog.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: dff848b17dafaabfb7662ffb5fecfcb04e3b771d Maintainer: PhilDaiguille Status: ready -->
+<!-- EN-Revision: 4fc9f9ea7ba36a383613ede343a0820f5cc46aa2 Maintainer: PhilDaiguille Status: ready -->
 <sect1 xml:id="language.oop5.changelog" xmlns="http://docbook.org/ns/docbook">
  <title>Modificaciones en POO (Programación orientada a objetos)</title>
  <para>
@@ -16,6 +16,23 @@
      </row>
     </thead>
     <tbody>
+     <row>
+      <entry>8.5.0</entry>
+      <entry>
+       Cambio: Un método que devuelve <type>static</type> puede ahora ser
+       sobrescrito en una clase <modifier>final</modifier> para declarar
+       <type>self</type> o el tipo de la propia clase como tipo de retorno, ya
+       que estos son equivalentes a <type>static</type> en una clase que no
+       puede ser extendida.
+      </entry>
+     </row>
+     <row>
+      <entry>8.5.0</entry>
+      <entry>
+       Cambio: Los <link linkend="language.oop5.traits">traits</link> se ligan
+       ahora a una clase antes que su clase padre.
+      </entry>
+     </row>
      <row>
       <entry>8.4.0</entry>
       <entry>
@@ -32,7 +49,7 @@
       <entry>8.1.0</entry>
       <entry>
        Adición: Soporte para el modificador <modifier>final</modifier> para las constantes de clase.
-       Además, las constantes de interfaces pueden ser redefinidas por omisión.
+       Además, las constantes de interfaces pueden ser redefinidas por defecto.
       </entry>
      </row>
      <row>
@@ -68,7 +85,7 @@
       <entry>7.3.0</entry>
       <entry>
        Incompatibilidad: El desempaquetado de argumento de
-       <classname>Traversable</classname>s con claves no-&integer;es ya no es soportado. Este comportamiento no estaba previsto y por consiguiente
+       <classname>Traversable</classname>s con claves no-&integer; ya no es soportado. Este comportamiento no estaba previsto y por consiguiente
        fue eliminado.
       </entry>
      </row>
@@ -229,18 +246,18 @@
        no afecta a las clases sin espacio de nombres.
       </entry>
      </row>
-      <row>
+     <row>
       <entry>5.3.0</entry>
       <entry>
-       Cambio: Las clases que implementan una interfaz con métodos que tienen valores por omisión definidos en sus prototipos ya no están obligadas a respetar los valores por omisión definidos en la interfaz.
+       Cambio: Las clases que implementan una interfaz con métodos que tienen valores por defecto definidos en sus prototipos ya no están obligadas a respetar los valores por defecto definidos en la interfaz.
       </entry>
      </row>
      <row>
       <entry>5.3.0</entry>
       <entry>
-       Cambio: Es ahora posible referenciar una clase utilizando una variable (e.g. :
+       Cambio: Es ahora posible referenciar una clase utilizando una variable (p. ej.,
        <literal>echo $classname::constant;</literal>).
-       El valor de la variable no puede ser una palabra clave (e.g. :
+       El valor de la variable no puede ser una palabra clave (p. ej.,
        <literal>self</literal>,
        <literal>parent</literal> o <literal>static</literal>).
       </entry>

language/oop5/cloning.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: dff848b17dafaabfb7662ffb5fecfcb04e3b771d Maintainer: PhilDaiguille Status: ready -->
+<!-- EN-Revision: 09c650422aec6f59dca08d1c65eaa633d391a525 Maintainer: PhilDaiguille Status: ready -->
 <sect1 xml:id="language.oop5.cloning" xmlns="http://docbook.org/ns/docbook">
   <title>Clonación de objetos</title>
 
@@ -11,6 +11,10 @@
    contiene el recurso que representa esa ventana GTK, al crear una copia,
    se puede desear crear una nueva ventana con las mismas propiedades,
    pero que el nuevo objeto contenga un recurso que represente la nueva ventana.
+   Otro ejemplo: si el objeto contiene una referencia a otro objeto que
+   utiliza, al replicar el objeto padre se puede desear crear una nueva
+   instancia de ese otro objeto, de modo que la réplica tenga su propia copia
+   independiente.
   </simpara>
 
   <para>
@@ -83,10 +87,10 @@ $obj->object2 = new SubObject();
 
 $obj2 = clone $obj;
 
-print "Objeto original :\n";
+print "Objeto original:\n";
 print_r($obj);
 
-print "Objeto clonado :\n";
+print "Objeto clonado:\n";
 print_r($obj2);
 
 ?>
@@ -95,7 +99,7 @@ print_r($obj2);
    &example.outputs;
    <screen role="php">
 <![CDATA[
-Objeto original :
+Objeto original:
 MyCloneable Object
 (
     [object1] => SubObject Object
@@ -109,7 +113,7 @@ MyCloneable Object
         )
 
 )
-Objeto clonado :
+Objeto clonado:
 MyCloneable Object
 (
     [object1] => SubObject Object
@@ -150,6 +154,61 @@ echo (clone $dateTime)->format('Y');
 ]]>
    </screen>
   </example>
+
+  <sect2 xml:id="language.oop5.cloning.with-properties">
+   <title>Clonación con sustitución de propiedades</title>
+
+   <simpara>
+    A partir de PHP 8.5.0, <literal>clone</literal> también está disponible como
+    función, cuyo segundo parámetro <parameter>withProperties</parameter> acepta
+    un array que asocia nombres de propiedades con los valores que recibe la
+    copia. Solo se sustituyen las propiedades indicadas; las demás conservan el
+    valor con el que fueron copiadas.
+   </simpara>
+
+   <simpara>
+    Las sustituciones se aplican después de la ejecución de
+    <link linkend="object.clone">__clone()</link> y respetan la visibilidad de
+    todas las propiedades.
+    Las <link linkend="language.oop5.properties.readonly-properties">propiedades readonly</link>
+    pueden modificarse en la copia aunque ya estuvieran inicializadas en el
+    objeto original, lo que hace que la función resulte adecuada para los
+    métodos que devuelven una copia modificada.
+   </simpara>
+
+   <example>
+    <title>Clonación de un objeto con sustitución de propiedades</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
 Local variables:

language/oop5/traits.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: dff848b17dafaabfb7662ffb5fecfcb04e3b771d Maintainer: PhilDaiguille Status: ready -->
+<!-- EN-Revision: 4fc9f9ea7ba36a383613ede343a0820f5cc46aa2 Maintainer: PhilDaiguille Status: ready -->
 <sect1 xml:id="language.oop5.traits" xmlns="http://docbook.org/ns/docbook">
  <title>Traits</title>
  <para>
@@ -8,12 +8,12 @@
  <para>
   Los traits son un mecanismo de reutilización de código en un lenguaje de herencia simple
   como PHP. Un trait intenta reducir ciertas limitaciones de la herencia simple, permitiendo
-  al desarrollador reutilizar un cierto número de métodos en clases independientes. La sémantica entre las clases y los traits reduce la complejidad y evita los problemas
+  al desarrollador reutilizar un cierto número de métodos en clases independientes. La semántica entre las clases y los traits reduce la complejidad y evita los problemas
   típicos de la herencia múltiple y los Mixins.
  </para>
  <para>
   Un trait es similar a una clase, pero solo sirve para agrupar funcionalidades de una
-  manera interesante. No es posible instanciar un Trait en sí mismo. Es un
+  manera granular y coherente. No es posible instanciar un Trait en sí mismo. Es un
   añadido a la herencia tradicional, que permite la composición horizontal de comportamientos,
   es decir, el uso de métodos de clase sin necesidad de herencia.
  </para>
@@ -67,13 +67,29 @@ Hello World!
   <para>
    Un método heredado desde una clase madre es sobrescrito por un método proveniente de un Trait.
    El orden de precedencia hace que los métodos de la clase actual
-   sobrescriban los métodos provenientes de un Trait, ellos mismos sobrecargando los métodos heredados.
+   sobrescriban los métodos provenientes de un Trait, que a su vez sobrescriben los métodos heredados.
   </para>
+  <note>
+   <simpara>
+    A partir de PHP 8.5.0, los traits se ligan a una clase antes que su clase
+    madre; anteriormente se ligaban después. Esto refleja con mayor fidelidad
+    la semántica de copiar y pegar de los traits. En particular, cuando un trait
+    y la clase madre declaran ambos una propiedad o una constante con el mismo
+    nombre, la definición del trait prevalece ahora sobre la heredada, mientras
+    que las versiones anteriores generaban un error fatal por composición
+    incompatible. La resolución de métodos no se ve afectada. Consulte
+    <link linkend="migration85.incompatible.core.trait-binding">la guía de
+    migración</link> para más detalles.
+   </simpara>
+  </note>
   <example xml:id="language.oop5.traits.precedence.examples.ex1">
    <title>Ejemplo con el orden de precedencia</title>
    <para>
-    Un método heredado desde la clase base es sobrescrito por el que proviene
-    del Trait. No es el caso de los métodos reales, escritos en la clase base.
+    Un método heredado desde la clase base es sobrescrito por el método
+    insertado en MyHelloWorld desde el Trait SayWorld. El comportamiento es
+    el mismo para los métodos definidos en la clase MyHelloWorld. El orden de
+    precedencia hace que los métodos de la clase actual sobrescriban los métodos
+    del Trait, que a su vez sobrescriben los métodos de la clase base.
    </para>
    <programlisting role="php">
 <![CDATA[
@@ -341,7 +357,7 @@ Hello World!
    Los traits soportan el uso de métodos abstractos para imponer
    restricciones a las clases subyacentes. Se soportan los métodos públicos, protegidos,
    y privados.
-   Anterior a PHP 8.0.0, solo se soportaban los métodos públicos y protegidos abstractos.
+   Antes de PHP 8.0.0, solo se soportaban los métodos públicos y protegidos abstractos.
   </para>
   <caution>
     <simpara>
@@ -478,7 +494,7 @@ Doing something
 <![CDATA[
 <?php
 
-trait StaticExample
+trait T
 {
     public static $counter = 1;
 }
@@ -607,7 +623,7 @@ echo $example::FLAG_MUTABLE;
   <para>
    Si un trait define una constante, entonces una clase no puede definir una
    constante con el mismo nombre, a menos que sea compatible (misma
-   visibilidad, mismo valor, etc.), de lo contrario se produce un error fatal.
+   visibilidad, valor inicial y carácter final), de lo contrario se produce un error fatal.
   </para>
   <example xml:id="language.oop5.traits.constants.conflicts">
    <title>Resolución de conflicto</title>
@@ -634,8 +650,8 @@ class ConstantsExample {
     A partir de PHP 8.3.0, el modificador <link linkend="language.oop5.final">final</link>
     puede ser aplicado usando el operador <literal>as</literal>
     a los métodos importados desde los traits. Esto puede ser usado para impedir
-    que las clases hijas sobrecarguen el método. Sin embargo, la clase que usa
-    el trait puede seguir sobrecargando el método.
+    que las clases hijas sobrescriban el método. Sin embargo, la clase que usa
+    el trait puede seguir sobrescribiendo el método.
    </simpara>
    <example xml:id="language.oop5.traits.final-methods.example">
     <title>Definir un método proveniente de un trait como <literal>final</literal></title>
@@ -654,7 +670,7 @@ trait CommonTrait
 class FinalExampleA
 {
     use CommonTrait {
-        CommonTrait::method as final; // El 'final' impide que las clases hijas sobrecarguen el método
+        CommonTrait::method as final; // El 'final' impide que las clases hijas sobrescriban el método
     }
 }
 

language/oop5/variance.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: dff848b17dafaabfb7662ffb5fecfcb04e3b771d Maintainer: PhilDaiguille Status: ready -->
+<!-- EN-Revision: 4fc9f9ea7ba36a383613ede343a0820f5cc46aa2 Maintainer: PhilDaiguille Status: ready -->
 <sect1 xml:id="language.oop5.variance" xmlns="http://docbook.org/ns/docbook">
  <title>Covarianza y Contravarianza</title>
 
@@ -18,7 +18,7 @@
    <listitem>
     <simpara>
      Un tipo es retirado de un
-    <link linkend="language.types.type-system.composite.union">tipo union</link>
+    <link linkend="language.types.type-system.composite.union">tipo unión</link>
     </simpara>
    </listitem>
    <listitem>
@@ -39,7 +39,7 @@
    </listitem>
   </itemizedlist>
 
-  Un tipo de clase se considera menos específico si lo contrario es cierto.
+  Una declaración de tipo se considera menos específica si lo contrario es cierto.
  </para>
 
  <sect2 xml:id="language.oop5.variance.covariance">
@@ -135,6 +135,17 @@ Mavrick barks
 ]]>
    </screen>
   </informalexample>
+  <note>
+   <simpara>
+    A partir de PHP 8.5.0, cuando un método padre declara <type>static</type> como
+    tipo de retorno, un método que lo sobrescribe en una clase <modifier>final</modifier>
+    puede declarar en su lugar <type>self</type> o el tipo de la propia clase como
+    tipo de retorno, ya que estos son equivalentes a <type>static</type> en una clase
+    que no puede extenderse más. Consulte
+    <link linkend="migration85.incompatible.core.substitute-final-subclasses">la
+    guía de migración</link> para más detalles.
+   </simpara>
+  </note>
  </sect2>
 
  <sect2 xml:id="language.oop5.variance.contravariance">
@@ -176,8 +187,8 @@ abstract class Animal
   </informalexample>
 
   <para>
-   Para ver el comportamiento de la contravarianza, el método
-   método <varname>eat</varname> es sobrecargado en la clase <varname>Dog</varname> para permitir
+   Para ver el comportamiento de la contravarianza, el
+   método <varname>eat</varname> es sobrescrito en la clase <varname>Dog</varname> para permitir
    cualquier objeto de tipo <varname>Food</varname>. La clase <varname>Cat</varname> permanece sin cambios.
   </para>
 
@@ -223,10 +234,10 @@ Mavrick eats Food
 ]]>
    </screen>
 
-  <para>
-   Pero, ¿qué sucede si <varname>$kitty</varname> intenta comer (<methodname>eat</methodname>) la
-   banana (<varname>$banana</varname>) ?
-  </para>
+   <para>
+    Pero, ¿qué sucede si <varname>$kitty</varname> intenta comer (<methodname>eat</methodname>) la
+    banana (<varname>$banana</varname>)?
+   </para>
 
    <programlisting role="php">
 <![CDATA[