====== PHP RFC: Clone with v2 ======
  * Version: 1.1
  * Date: 2025-03-30
  * Author: Volker Dusch (volker@tideways-gmbh.com), Tim Düsterhus (tim@tideways-gmbh.com)
  * Status: Voting
  * First Published at: https://wiki.php.net/rfc/clone_with_v2

===== Introduction =====

Both <php>readonly</php> properties and the cloning of objects are commonplace in a lot of PHP applications, but these two concepts don’t fully work together in all cases. 

This RFC proposes to address this issue by allowing the <php>clone</php> language construct to work well with <php>readonly</php> properties.

One common usage pattern for object cloning is “immutable value-objects” having <php>->withProperty()</php> methods returning a new object with some property changed. This doesn’t work smoothly with <php>readonly</php> properties at the moment.

<PHP>
<?php

final readonly class Response {
    public function __construct(
        public int $statusCode,
        public string $reasonPhrase,
        // ...
    ) {}

    public function withStatus($code, $reasonPhrase = ''): Response
    {
        // Only works if all properties are assignable via __construct
        $values = get_object_vars($this);
        $values['statusCode'] = $code;
        $values['reasonPhrase'] = $reasonPhrase;
        return new self(
            ...$values
        );
    }
}
</PHP>

To address this, we propose what we consider a simple change that makes <php>clone</php> look and mostly behave like a regular function call. This will align <php>clone</php> with current PHP users' expectations regarding syntax and semantics, while still respecting property visibility rules.

<PHP>
    public function withStatus($code, $reasonPhrase = ''): Response {
        return clone($this, [
            "statusCode" => $code,
            "reasonPhrase" => $reasonPhrase,
        ]);
    }</PHP>

The main reason we think a <php>clone()</php> function that directly updates the properties is preferable to one that passes the updated properties to the magic <php>__clone()</php> method of an object, is that it allows objects with public properties to be cloned with changed properties from the outside without assistance by the object. Furthermore, within a class changes can be localized in appropriate methods rather than centralized in the <php>__clone()</php> method.

===== Prior Works =====

This change was proposed in https://wiki.php.net/rfc/clone_with and discussed https://externals.io/message/120048

Máté, the original RFC author, dropped the RFC and had no objections to us proposing this continuation trying to address the same need.


===== Proposal =====

We propose to change <php>clone</php> from a standalone keyword to a language construct that optionally accepts a second <php>array</php> parameter.

<PHP>
function clone(object $object, array $withProperties = []): object {}
</PHP>

This allows all the following syntax examples to be valid:

<PHP>
$y = clone $x;
$y = clone($x);
$y = \clone($x);
$y = clone($x, []);
$y = clone($x, [
    "foo" => $foo,
    "bar" => $bar,
]);
$y = clone($x, $array);
</PHP>

By promoting <php>clone</php> to a function, it will also be possible to use it as a callable. E.g., in <php>array_map</php>. Promoting <php>clone</php> to a function also simplifies the implementation considerably.

==== Technical Details ====

  * A magic <php>__clone()</php> method will be called before the new properties are assigned.
    * Calling <php>__clone()</php> afterward would mean the new properties would already be set and the old ones gone, contrasting existing behavior and thus users' expectations.
  * Assignment of new properties happens in iteration order of the array parameter. As a result, should there be an error during the assignment (e.g., because of property hooks), the error will be raised for the first impacted property.
  * Property assignments are made just as a regular assignment would be. Meaning all regular PHP rules apply with only the <php>readonly</php> state being "unlocked".
    * Visibility rules for property access are enforced. Clone can't be used to modify the internal state of objects from outside.
    * Property hooks work as expected. Setters are called during <php>clone</php> calls.
    * Dynamic properties respect <php>#[AllowDynamicProperties]</php>.
    * <php>__set</php> works as expected and is called during clone as it would be during normal assignments.
    * The behavior of Lazy Objects is not affected; as before, they will be de-lazyfied and cloned. 

A userland implementation of this would be replacing the <php>clone</php> call with the following code:

<PHP>
<?php

$cloned = clone $object;
foreach ($withProperties as $key => $value) {
    $cloned->{$key} = $value;
}
return $cloned;
</PHP>

The <php>clone</php> keyword (and T_CLONE token) will be kept and it will remain impossible to create a <php>clone</php> function within a namespace. It will also not be possible to disable the <php>clone()</php> function with the ''disable_functions=clone'' INI setting.

==== Design Goals ====

When re-proposing this RFC, one of our goals was to take all previous discussion into account and propose something that is small in scope and cognitive load.

This RFC explicitly rejects any BC impacting syntax choices like the previously proposed <php>with</php> keyword, as we don't feel the scope of the feature warrants any BC impact.

Likewise, all syntax has to exist in PHP already, to not add cognitive load to readers when they come across it. A simple PHP array feels like the most ubiquitous syntax in PHP.

Furthermore, this RFC considers touching how <php>__clone</php> works (e.g. by adding parameters to it) to be a non-goal due to the increased complexity and [[#backward_incompatible_changes|BC considerations]].

==== Examples ====

=== Using clone as a callable ===

<PHP>
<?php

$x = [new stdClass, new stdClass];

var_dump(array_map(clone(...), $x));
array_map('clone', $x); // Works as well

// array(2) {
//  [0] => object(stdClass)#4 (0) {}
//  [1] => object(stdClass)#5 (0) {}
// }

</PHP>


=== Cloning with new properties ===

<PHP>
<?php

class Foo {

    public function __construct(
        private readonly int $c = 1,
    ) {}

    public function just_clone() {
        return clone $this;
    }

    public function clone_with($newC) {
        return clone($this, ["c" => $newC]);
    }
}

$x = new Foo();
// object(Foo)#2 (1) { ["c":"Foo":private]=> int(1) }
var_dump($x->just_clone());

// object(Foo)#2 (1) { ["c":"Foo":private]=> int(5) }
var_dump($x->clone_with(5));
</PHP>

=== Visibility rules ===

Public properties can be changed from the outside during cloning.

<PHP>
<?php

class Foo {
    public int $pub = 1;
}

$foo = new Foo();
// object(Foo)#2 (1) { ["pub"]=> int(5) }
var_dump(clone($foo, ["pub" => 5]));
</PHP>

Public <php>readonly</php> properties can be changed during cloning from within the class.

<PHP>
<?php

class Foo {
    public readonly int $pub;

    public function withPub($newPub) {
        return clone($this, ["pub" => $newPub]);
    }
}

$foo = new Foo();
// object(Foo)#2 (1) { ["pub"]=> int(5) }
var_dump($foo->withPub(5));
</PHP>


Public readonly properties need a <php>public(set)</php> to be able to be cloned from outside the class, as the property is <php>protected(set)</php> by default.
This is existing PHP behavior and unchanged by this RFC. Changing the visibility of <php>readonly</php> properties is outside the scope of this RFC, and this example is provided for sake of completeness and to thoroughly explain the existing edge cases.

<PHP>
<?php

class Foo {
    public readonly int $pub;
}

$foo = new Foo();
var_dump(clone($foo, ["pub" => 5]));
// Fatal error: Uncaught Error: Cannot modify protected(set) readonly property Foo::$pub from global scope in ...
</PHP>

Protected and private properties can be changed from within their respective scopes.

<PHP>
<?php

class Foo {
    protected readonly int $prot;
    private readonly int $priv;

    public function withPriv(int $priv) {
        return clone($this, ["priv" => $priv]);
    }
}

class Bar extends Foo {
    public function withProt(int $prot) {
        return clone($this, ["prot" => $prot]);
    }
}

$foo = new Foo();
// object(Foo)#2 (1) { ["prot":protected]=> uninitialized(int) ["priv":"Foo":private]=> int(10) }
var_dump($foo->withPriv(10));

$bar = new Bar();
// object(Bar)#3 (1) { ["prot":protected]=> int(5) ["priv":"Foo":private]=> uninitialized(int) }
var_dump($bar->withProt(5));

// Fatal error: Uncaught Error: Cannot access protected property Bar::$prot in
clone($bar, ["prot" => 5]);
</PHP>

=== Assignment order and property hooks ===

Property hooks are executed just as they would be with normal setters.

<PHP>
<?php

class Foo {
    public string $hooked = 'default' {
        set (string $value) {
            $this->hooked = strtoupper($value);
        }
    }
}

$x = new Foo();

// object(Foo)#1 (1) { ["hooked"] => string(7) "default" }
var_dump($x);

// object(Foo)#2 (1) { ["hooked"] => string(7) "UPDATED" }
var_dump(clone($x, ["hooked" => 'updated']));

</PHP>

=== Throw order ===

Properties are set in the order they are passed in. The first error/exception raised cancels the rest of the clone operation.

<PHP>
<?php

class Foo {

    public function __construct(
        private int $a,
        private int $b,
        private int $c,
    ) {}

    public function withInvalidValues() {
        return clone($this, [
            "a" => 5,
            "b" => 'invalid argument',
            "c" => 'also invalid'
        ]);
    }
}

$foo = new Foo(1,2,3);
$foo->withInvalidValues();

// Fatal error: Uncaught TypeError: Cannot assign string to property Foo::$b of type int in ...
</PHP>

Combined with property hooks:

<PHP>
<?php

class Foo {

    public function __construct(
        private int $a {
            set (int $value) {
                echo "Got $value", PHP_EOL;
            }
        },
        private int $b {
            set (int $value) {	
                if ($value > 3) {
                    throw new InvalidArgumentException("Rejecting $value");
                }
            }
        },
        private int $c {
            set (int $value) {
                echo "Got $value", PHP_EOL;
            }
        },
    ) {}

    public function withInvalidValues() {
        return clone($this, [
            "a" => 5,
            "b" => 6,
            "c" => 7,
        ]);
    }
}

$foo = new Foo(1,2,3);
$foo->withInvalidValues();

// Got 1
// Got 2
// Got 3
// Got 5

// Fatal error: Uncaught InvalidArgumentException: Rejecting 6 in ...

</PHP>

=== Readonly ===

<PHP>
<?php

class Foo {
    public function __construct(
        public(set) readonly int $c,
    ) {}
}

$x = new Foo(1);

var_dump($x); // object(Foo)#1 (1) { ["c"]=> int(1) }
var_dump(clone($x, ["c" => 2])); // object(Foo)#2 (1) { ["c"]=> int(2) }

// Without the (set) modifier on public, we'd get:
// Fatal error: Uncaught Error: Cannot modify protected(set) readonly property Foo::$c from global scope in example.php:12
// Note that this is how readonly properties work in PHP currently and any change would be outside the scope of this RFC

</PHP>

=== Dynamic Properties ===

Since property assignments are made just as a regular assignment would be, dynamic property creation follows established PHP rules:

<PHP>
<?php

class Foo {
}


$x = new Foo();
// Deprecated: Creation of dynamic property Foo::$propertyThatDoesNotExist is deprecated in ...
// object(Foo)#2 (1) { ["propertyThatDoesNotExist"]=> int(2) }
var_dump(clone($x, ["propertyThatDoesNotExist" => 2]));

#[AllowDynamicProperties]
class Bar {
}

$y = new Bar();
// object(Bar)#3 (1) { ["propertyThatDoesNotExist"]=> int(2) }
var_dump(clone($y, ["propertyThatDoesNotExist" => 2]));
</PHP>

=== Numeric Arrays ===

Given the function signature <php>clone(object $object, array $withProperties): object {}</php> it follows that numeric parameters derive their key from their implicit position as they would for any other PHP array. For <php>clone</php> this is usually not useful and is documented here for completeness.

<PHP>
<?php

var_dump(
    clone(new stdClass, [1, 2])
);

// object(stdClass)#2 (2) {
//   ["0"]=>
//   int(1)
//   ["1"]=>
//   int(2)
// }

</PHP>

Omitting the array keys for most objects will lead to deprecation notices, as shown in the "Dynamic Properties" section.

===== Backward Incompatible Changes =====

No BC break is expected. The new syntax is optional and the old syntax will continue to work as before.

By not touching how <php>__clone()</php> works, we also avoid any BC impact for users of this function.

===== Proposed PHP Version(s) =====

Next PHP 8.x (8.5)

===== RFC Impact =====
==== To SAPIs ====

None

==== To Existing Extensions ====

The current implementation adds a new ''clone_obj_with'' object handler that needs to be implemented to make internal classes compatible with clone with when custom cloning behavior is already implemented with ''clone_obj''. If the default ''clone_obj'' handler is used, clone with will transparently work.

The existing behavior of ''clone_obj'' when no properties are given remains fully compatible. Thus, the only impact is that extensions that are not updated will be incompatible with clone with, but cloning behavior without properties remains compatible for existing PHP programs.

==== To Opcache ====

None

==== New Constants ====

None

==== php.ini Defaults ====

None

===== Open Issues =====

None

===== Unaffected PHP Functionality =====


===== Future Scope =====

  * Allow <php>__clone()</php> to inspect the <php>$withProperties</php> array to skip deep-cloning properties that will be overridden.

===== Proposed Voting Choices =====

<doodle title="Implement clone-with as outlined in the RFC?" auth="edorian" voteType="single" closed="false" closeon="2025-06-18T15:30:00Z">
   * Yes
   * No
</doodle>

===== Patches and Tests =====

  * https://github.com/php/php-src/pull/18747

===== Implementation =====

TBD

===== References =====

  * https://wiki.php.net/rfc/clone_with
  * https://externals.io/message/120048

===== Rejected Features =====

For the reasons mentioned in the introduction and the Backwards Incompatible Changes section, changes to the magic <php>__clone()</php> method are out of scope for this RFC.

===== Changelog =====

Earlier versions of this RFC proposed a <php>clone</php> method with named-parameters. This was dropped in favor of less complex functions with more familiar syntax and no newly invented concepts not seen anywhere else in php-src. The RFC, the implementation and the documentation efforts needed were significantly reduced by this change.