in PHP
is a creational design pattern that allows cloning objects, even complex ones, without coupling to their specific classes.
All classes should have a common interface that makes it possible to copy objects even if their concrete classes are unknown. objects can produce full copies since objects of the same class can access each other’s private fields.
Complexity:
Popularity:
Usage examples: The pattern is available in PHP out of the box. You can use the clone keyword to create an exact copy of an object. To add cloning support to a class, you need to implement a __clone method.
Identification: The can be easily recognized by a clone or copy methods, etc.
Conceptual Example
This example illustrates the structure of the design pattern and focuses on the following questions:
- What classes does it consist of?
- What roles do these classes play?
- In what way the elements of the pattern are related?
After learning about the pattern’s structure it’ll be easier for you to grasp the following example, based on a real-world PHP use case.
index.php: Conceptual example
<?php
namespace RefactoringGuru\\Conceptual;
/**
* The example class that has cloning ability. We'll see how the values of field
* with different types will be cloned.
*/
class
{
public $primitive;
public $component;
public $circularReference;
/**
* PHP has built-in cloning support. You can `clone` an object without
* defining any special methods as long as it has fields of primitive types.
* Fields containing objects retain their references in a cloned object.
* Therefore, in some cases, you might want to clone those referenced
* objects as well. You can do this in a special `__clone()` method.
*/
public function __clone()
{
$this->component = clone $this->component;
// Cloning an object that has a nested object with backreference
// requires special treatment. After the cloning is completed, the
// nested object should point to the cloned object, instead of the
// original object.
$this->circularReference = clone $this->circularReference;
$this->circularReference-> = $this;
}
}
class ComponentWithBackReference
{
public $;
/**
* Note that the constructor won't be executed during cloning. If you have
* complex logic inside the constructor, you may need to execute it in the
* `__clone` method as well.
*/
public function __construct( $)
{
$this-> = $;
}
}
/**
* The client code.
*/
function clientCode()
{
$p1 = new ();
$p1->primitive = 245;
$p1->component = new \DateTime();
$p1->circularReference = new ComponentWithBackReference($p1);
$p2 = clone $p1;
if ($p1->primitive === $p2->primitive) {
echo "Primitive field values have been carried over to a clone. Yay!\n";
} else {
echo "Primitive field values have not been copied. Booo!\n";
}
if ($p1->component === $p2->component) {
echo "Simple component has not been cloned. Booo!\n";
} else {
echo "Simple component has been cloned. Yay!\n";
}
if ($p1->circularReference === $p2->circularReference) {
echo "Component with back reference has not been cloned. Booo!\n";
} else {
echo "Component with back reference has been cloned. Yay!\n";
}
if ($p1->circularReference-> === $p2->circularReference->) {
echo "Component with back reference is linked to original object. Booo!\n";
} else {
echo "Component with back reference is linked to the clone. Yay!\n";
}
}
clientCode();
Output.txt: Execution result
Primitive field values have been carried over to a clone. Yay!
Simple component has been cloned. Yay!
Component with back reference has been cloned. Yay!
Component with back reference is linked to the clone. Yay!
Real World Example
The pattern provides a convenient way of replicating existing objects instead of trying to reconstruct the objects by copying all of their fields directly. The direct approach not only couples you to the classes of the objects being cloned, but also doesn’t allow you to copy the contents of the private fields. The pattern lets you perform the cloning within the context of the cloned class, where the access to the class’ private fields isn’t restricted.
This example shows you how to clone a complex Page object using the pattern. The Page class has lots of private fields, which will be carried over to the cloned object thanks to the pattern.
index.php: Real world example
<?php
namespace RefactoringGuru\\RealWorld;
/**
* .
*/
class Page
{
private $title;
private $body;
/**
* @var Author
*/
private $author;
private $comments = [];
/**
* @var \DateTime
*/
private $date;
// +100 private fields.
public function __construct(string $title, string $body, Author $author)
{
$this->title = $title;
$this->body = $body;
$this->author = $author;
$this->author->addToPage($this);
$this->date = new \DateTime();
}
public function addComment(string $comment): void
{
$this->comments[] = $comment;
}
/**
* You can control what data you want to carry over to the cloned object.
*
* For instance, when a page is cloned:
* - It gets a new "Copy of ..." title.
* - The author of the page remains the same. Therefore we leave the
* reference to the existing object while adding the cloned page to the list
* of the author's pages.
* - We don't carry over the comments from the old page.
* - We also attach a new date object to the page.
*/
public function __clone()
{
$this->title = "Copy of " . $this->title;
$this->author->addToPage($this);
$this->comments = [];
$this->date = new \DateTime();
}
}
class Author
{
private $name;
/**
* @var Page[]
*/
private $pages = [];
public function __construct(string $name)
{
$this->name = $name;
}
public function addToPage(Page $page): void
{
$this->pages[] = $page;
}
}
/**
* The client code.
*/
function clientCode()
{
$author = new Author("John Smith");
$page = new Page("Tip of the day", "Keep calm and carry on.", $author);
// ...
$page->addComment("Nice tip, thanks!");
// ...
$draft = clone $page;
echo "Dump of the clone. Note that the author is now referencing two objects.\n\n";
print_r($draft);
}
clientCode();
Output.txt: Execution result
Dump of the clone. Note that the author is now referencing two objects.
RefactoringGuru\\RealWorld\Page Object
(
[title:RefactoringGuru\\RealWorld\Page:private] => Copy of Tip of the day
[body:RefactoringGuru\\RealWorld\Page:private] => Keep calm and carry on.
[author:RefactoringGuru\\RealWorld\Page:private] => RefactoringGuru\\RealWorld\Author Object
(
[name:RefactoringGuru\\RealWorld\Author:private] => John Smith
[pages:RefactoringGuru\\RealWorld\Author:private] => Array
(
[0] => RefactoringGuru\\RealWorld\Page Object
(
[title:RefactoringGuru\\RealWorld\Page:private] => Tip of the day
[body:RefactoringGuru\\RealWorld\Page:private] => Keep calm and carry on.
[author:RefactoringGuru\\RealWorld\Page:private] => RefactoringGuru\\RealWorld\Author Object
*RECURSION*
[comments:RefactoringGuru\\RealWorld\Page:private] => Array
(
[0] => Nice tip, thanks!
)
[date:RefactoringGuru\\RealWorld\Page:private] => DateTime Object
(
[date] => 2018-06-04 14:50:39.306237
[timezone_type] => 3
[timezone] => UTC
)
)
[1] => RefactoringGuru\\RealWorld\Page Object
*RECURSION*
)
)
[comments:RefactoringGuru\\RealWorld\Page:private] => Array
(
)
[date:RefactoringGuru\\RealWorld\Page:private] => DateTime Object
(
[date] => 2018-06-04 14:50:39.306272
[timezone_type] => 3
[timezone] => UTC
)
)
