Chris@14: # DeepCopy
Chris@14: 
Chris@14: DeepCopy helps you create deep copies (clones) of your objects. It is designed to handle cycles in the association graph.
Chris@14: 
Chris@14: [![Build Status](https://travis-ci.org/myclabs/DeepCopy.png?branch=master)](https://travis-ci.org/myclabs/DeepCopy)
Chris@14: [![Coverage Status](https://coveralls.io/repos/myclabs/DeepCopy/badge.png?branch=master)](https://coveralls.io/r/myclabs/DeepCopy?branch=master)
Chris@14: [![Scrutinizer Quality Score](https://scrutinizer-ci.com/g/myclabs/DeepCopy/badges/quality-score.png?s=2747100c19b275f93a777e3297c6c12d1b68b934)](https://scrutinizer-ci.com/g/myclabs/DeepCopy/)
Chris@14: [![Total Downloads](https://poser.pugx.org/myclabs/deep-copy/downloads.svg)](https://packagist.org/packages/myclabs/deep-copy)
Chris@14: 
Chris@14: 
Chris@14: ## Table of Contents
Chris@14: 
Chris@14: 1. [How](#how)
Chris@14: 1. [Why](#why)
Chris@14:     1. [Using simply `clone`](#using-simply-clone)
Chris@14:     1. [Overridding `__clone()`](#overridding-__clone)
Chris@14:     1. [With `DeepCopy`](#with-deepcopy)
Chris@14: 1. [How it works](#how-it-works)
Chris@14: 1. [Going further](#going-further)
Chris@14:     1. [Matchers](#matchers)
Chris@14:         1. [Property name](#property-name)
Chris@14:         1. [Specific property](#specific-property)
Chris@14:         1. [Type](#type)
Chris@14:     1. [Filters](#filters)
Chris@14:         1. [`SetNullFilter`](#setnullfilter-filter)
Chris@14:         1. [`KeepFilter`](#keepfilter-filter)
Chris@14:         1. [`DoctrineCollectionFilter`](#doctrinecollectionfilter-filter)
Chris@14:         1. [`DoctrineEmptyCollectionFilter`](#doctrineemptycollectionfilter-filter)
Chris@14:         1. [`DoctrineProxyFilter`](#doctrineproxyfilter-filter)
Chris@14:         1. [`ReplaceFilter`](#replacefilter-type-filter)
Chris@14:         1. [`ShallowCopyFilter`](#doctrinecollectionfilter-type-filter)
Chris@14: 1. [Edge cases](#edge-cases)
Chris@14: 1. [Contributing](#contributing)
Chris@14:     1. [Tests](#tests)
Chris@14: 
Chris@14: 
Chris@14: ## How?
Chris@14: 
Chris@14: Install with Composer:
Chris@14: 
Chris@14: ```json
Chris@14: composer require myclabs/deep-copy
Chris@14: ```
Chris@14: 
Chris@14: Use simply:
Chris@14: 
Chris@14: ```php
Chris@14: use DeepCopy\DeepCopy;
Chris@14: 
Chris@14: $copier = new DeepCopy();
Chris@14: $myCopy = $copier->copy($myObject);
Chris@14: ```
Chris@14: 
Chris@14: 
Chris@14: ## Why?
Chris@14: 
Chris@14: - How do you create copies of your objects?
Chris@14: 
Chris@14: ```php
Chris@14: $myCopy = clone $myObject;
Chris@14: ```
Chris@14: 
Chris@14: - How do you create **deep** copies of your objects (i.e. copying also all the objects referenced in the properties)?
Chris@14: 
Chris@14: You use [`__clone()`](http://www.php.net/manual/en/language.oop5.cloning.php#object.clone) and implement the behavior
Chris@14: yourself.
Chris@14: 
Chris@14: - But how do you handle **cycles** in the association graph?
Chris@14: 
Chris@14: Now you're in for a big mess :(
Chris@14: 
Chris@14: ![association graph](doc/graph.png)
Chris@14: 
Chris@14: 
Chris@14: ### Using simply `clone`
Chris@14: 
Chris@14: ![Using clone](doc/clone.png)
Chris@14: 
Chris@14: 
Chris@14: ### Overridding `__clone()`
Chris@14: 
Chris@14: ![Overridding __clone](doc/deep-clone.png)
Chris@14: 
Chris@14: 
Chris@14: ### With `DeepCopy`
Chris@14: 
Chris@14: ![With DeepCopy](doc/deep-copy.png)
Chris@14: 
Chris@14: 
Chris@14: ## How it works
Chris@14: 
Chris@14: DeepCopy recursively traverses all the object's properties and clones them. To avoid cloning the same object twice it
Chris@14: keeps a hash map of all instances and thus preserves the object graph.
Chris@14: 
Chris@14: To use it:
Chris@14: 
Chris@14: ```php
Chris@14: use function DeepCopy\deep_copy;
Chris@14: 
Chris@14: $copy = deep_copy($var);
Chris@14: ```
Chris@14: 
Chris@14: Alternatively, you can create your own `DeepCopy` instance to configure it differently for example:
Chris@14: 
Chris@14: ```php
Chris@14: use DeepCopy\DeepCopy;
Chris@14: 
Chris@14: $copier = new DeepCopy(true);
Chris@14: 
Chris@14: $copy = $copier->copy($var);
Chris@14: ```
Chris@14: 
Chris@14: You may want to roll your own deep copy function:
Chris@14: 
Chris@14: ```php
Chris@14: namespace Acme;
Chris@14: 
Chris@14: use DeepCopy\DeepCopy;
Chris@14: 
Chris@14: function deep_copy($var)
Chris@14: {
Chris@14:     static $copier = null;
Chris@14:     
Chris@14:     if (null === $copier) {
Chris@14:         $copier = new DeepCopy(true);
Chris@14:     }
Chris@14:     
Chris@14:     return $copier->copy($var);
Chris@14: }
Chris@14: ```
Chris@14: 
Chris@14: 
Chris@14: ## Going further
Chris@14: 
Chris@14: You can add filters to customize the copy process.
Chris@14: 
Chris@14: The method to add a filter is `DeepCopy\DeepCopy::addFilter($filter, $matcher)`,
Chris@14: with `$filter` implementing `DeepCopy\Filter\Filter`
Chris@14: and `$matcher` implementing `DeepCopy\Matcher\Matcher`.
Chris@14: 
Chris@14: We provide some generic filters and matchers.
Chris@14: 
Chris@14: 
Chris@14: ### Matchers
Chris@14: 
Chris@14:   - `DeepCopy\Matcher` applies on a object attribute.
Chris@14:   - `DeepCopy\TypeMatcher` applies on any element found in graph, including array elements.
Chris@14: 
Chris@14: 
Chris@14: #### Property name
Chris@14: 
Chris@14: The `PropertyNameMatcher` will match a property by its name:
Chris@14: 
Chris@14: ```php
Chris@14: use DeepCopy\Matcher\PropertyNameMatcher;
Chris@14: 
Chris@14: // Will apply a filter to any property of any objects named "id"
Chris@14: $matcher = new PropertyNameMatcher('id');
Chris@14: ```
Chris@14: 
Chris@14: 
Chris@14: #### Specific property
Chris@14: 
Chris@14: The `PropertyMatcher` will match a specific property of a specific class:
Chris@14: 
Chris@14: ```php
Chris@14: use DeepCopy\Matcher\PropertyMatcher;
Chris@14: 
Chris@14: // Will apply a filter to the property "id" of any objects of the class "MyClass"
Chris@14: $matcher = new PropertyMatcher('MyClass', 'id');
Chris@14: ```
Chris@14: 
Chris@14: 
Chris@14: #### Type
Chris@14: 
Chris@14: The `TypeMatcher` will match any element by its type (instance of a class or any value that could be parameter of
Chris@14: [gettype()](http://php.net/manual/en/function.gettype.php) function):
Chris@14: 
Chris@14: ```php
Chris@14: use DeepCopy\TypeMatcher\TypeMatcher;
Chris@14: 
Chris@14: // Will apply a filter to any object that is an instance of Doctrine\Common\Collections\Collection
Chris@14: $matcher = new TypeMatcher('Doctrine\Common\Collections\Collection');
Chris@14: ```
Chris@14: 
Chris@14: 
Chris@14: ### Filters
Chris@14: 
Chris@14: - `DeepCopy\Filter` applies a transformation to the object attribute matched by `DeepCopy\Matcher`
Chris@14: - `DeepCopy\TypeFilter` applies a transformation to any element matched by `DeepCopy\TypeMatcher`
Chris@14: 
Chris@14: 
Chris@14: #### `SetNullFilter` (filter)
Chris@14: 
Chris@14: Let's say for example that you are copying a database record (or a Doctrine entity), so you want the copy not to have
Chris@14: any ID:
Chris@14: 
Chris@14: ```php
Chris@14: use DeepCopy\DeepCopy;
Chris@14: use DeepCopy\Filter\SetNullFilter;
Chris@14: use DeepCopy\Matcher\PropertyNameMatcher;
Chris@14: 
Chris@14: $object = MyClass::load(123);
Chris@14: echo $object->id; // 123
Chris@14: 
Chris@14: $copier = new DeepCopy();
Chris@14: $copier->addFilter(new SetNullFilter(), new PropertyNameMatcher('id'));
Chris@14: 
Chris@14: $copy = $copier->copy($object);
Chris@14: 
Chris@14: echo $copy->id; // null
Chris@14: ```
Chris@14: 
Chris@14: 
Chris@14: #### `KeepFilter` (filter)
Chris@14: 
Chris@14: If you want a property to remain untouched (for example, an association to an object):
Chris@14: 
Chris@14: ```php
Chris@14: use DeepCopy\DeepCopy;
Chris@14: use DeepCopy\Filter\KeepFilter;
Chris@14: use DeepCopy\Matcher\PropertyMatcher;
Chris@14: 
Chris@14: $copier = new DeepCopy();
Chris@14: $copier->addFilter(new KeepFilter(), new PropertyMatcher('MyClass', 'category'));
Chris@14: 
Chris@14: $copy = $copier->copy($object);
Chris@14: // $copy->category has not been touched
Chris@14: ```
Chris@14: 
Chris@14: 
Chris@14: #### `DoctrineCollectionFilter` (filter)
Chris@14: 
Chris@14: If you use Doctrine and want to copy an entity, you will need to use the `DoctrineCollectionFilter`:
Chris@14: 
Chris@14: ```php
Chris@14: use DeepCopy\DeepCopy;
Chris@14: use DeepCopy\Filter\Doctrine\DoctrineCollectionFilter;
Chris@14: use DeepCopy\Matcher\PropertyTypeMatcher;
Chris@14: 
Chris@14: $copier = new DeepCopy();
Chris@14: $copier->addFilter(new DoctrineCollectionFilter(), new PropertyTypeMatcher('Doctrine\Common\Collections\Collection'));
Chris@14: 
Chris@14: $copy = $copier->copy($object);
Chris@14: ```
Chris@14: 
Chris@14: 
Chris@14: #### `DoctrineEmptyCollectionFilter` (filter)
Chris@14: 
Chris@14: If you use Doctrine and want to copy an entity who contains a `Collection` that you want to be reset, you can use the
Chris@14: `DoctrineEmptyCollectionFilter`
Chris@14: 
Chris@14: ```php
Chris@14: use DeepCopy\DeepCopy;
Chris@14: use DeepCopy\Filter\Doctrine\DoctrineEmptyCollectionFilter;
Chris@14: use DeepCopy\Matcher\PropertyMatcher;
Chris@14: 
Chris@14: $copier = new DeepCopy();
Chris@14: $copier->addFilter(new DoctrineEmptyCollectionFilter(), new PropertyMatcher('MyClass', 'myProperty'));
Chris@14: 
Chris@14: $copy = $copier->copy($object);
Chris@14: 
Chris@14: // $copy->myProperty will return an empty collection
Chris@14: ```
Chris@14: 
Chris@14: 
Chris@14: #### `DoctrineProxyFilter` (filter)
Chris@14: 
Chris@14: If you use Doctrine and use cloning on lazy loaded entities, you might encounter errors mentioning missing fields on a
Chris@14: Doctrine proxy class (...\\\_\_CG\_\_\Proxy).
Chris@14: You can use the `DoctrineProxyFilter` to load the actual entity behind the Doctrine proxy class.
Chris@14: **Make sure, though, to put this as one of your very first filters in the filter chain so that the entity is loaded
Chris@14: before other filters are applied!**
Chris@14: 
Chris@14: ```php
Chris@14: use DeepCopy\DeepCopy;
Chris@14: use DeepCopy\Filter\Doctrine\DoctrineProxyFilter;
Chris@14: use DeepCopy\Matcher\Doctrine\DoctrineProxyMatcher;
Chris@14: 
Chris@14: $copier = new DeepCopy();
Chris@14: $copier->addFilter(new DoctrineProxyFilter(), new DoctrineProxyMatcher());
Chris@14: 
Chris@14: $copy = $copier->copy($object);
Chris@14: 
Chris@14: // $copy should now contain a clone of all entities, including those that were not yet fully loaded.
Chris@14: ```
Chris@14: 
Chris@14: 
Chris@14: #### `ReplaceFilter` (type filter)
Chris@14: 
Chris@14: 1. If you want to replace the value of a property:
Chris@14: 
Chris@14: ```php
Chris@14: use DeepCopy\DeepCopy;
Chris@14: use DeepCopy\Filter\ReplaceFilter;
Chris@14: use DeepCopy\Matcher\PropertyMatcher;
Chris@14: 
Chris@14: $copier = new DeepCopy();
Chris@14: $callback = function ($currentValue) {
Chris@14:   return $currentValue . ' (copy)'
Chris@14: };
Chris@14: $copier->addFilter(new ReplaceFilter($callback), new PropertyMatcher('MyClass', 'title'));
Chris@14: 
Chris@14: $copy = $copier->copy($object);
Chris@14: 
Chris@14: // $copy->title will contain the data returned by the callback, e.g. 'The title (copy)'
Chris@14: ```
Chris@14: 
Chris@14: 2. If you want to replace whole element:
Chris@14: 
Chris@14: ```php
Chris@14: use DeepCopy\DeepCopy;
Chris@14: use DeepCopy\TypeFilter\ReplaceFilter;
Chris@14: use DeepCopy\TypeMatcher\TypeMatcher;
Chris@14: 
Chris@14: $copier = new DeepCopy();
Chris@14: $callback = function (MyClass $myClass) {
Chris@14:   return get_class($myClass);
Chris@14: };
Chris@14: $copier->addTypeFilter(new ReplaceFilter($callback), new TypeMatcher('MyClass'));
Chris@14: 
Chris@14: $copy = $copier->copy([new MyClass, 'some string', new MyClass]);
Chris@14: 
Chris@14: // $copy will contain ['MyClass', 'some string', 'MyClass']
Chris@14: ```
Chris@14: 
Chris@14: 
Chris@14: The `$callback` parameter of the `ReplaceFilter` constructor accepts any PHP callable.
Chris@14: 
Chris@14: 
Chris@14: #### `ShallowCopyFilter` (type filter)
Chris@14: 
Chris@14: Stop *DeepCopy* from recursively copying element, using standard `clone` instead:
Chris@14: 
Chris@14: ```php
Chris@14: use DeepCopy\DeepCopy;
Chris@14: use DeepCopy\TypeFilter\ShallowCopyFilter;
Chris@14: use DeepCopy\TypeMatcher\TypeMatcher;
Chris@14: use Mockery as m;
Chris@14: 
Chris@14: $this->deepCopy = new DeepCopy();
Chris@14: $this->deepCopy->addTypeFilter(
Chris@14: 	new ShallowCopyFilter,
Chris@14: 	new TypeMatcher(m\MockInterface::class)
Chris@14: );
Chris@14: 
Chris@14: $myServiceWithMocks = new MyService(m::mock(MyDependency1::class), m::mock(MyDependency2::class));
Chris@14: // All mocks will be just cloned, not deep copied
Chris@14: ```
Chris@14: 
Chris@14: 
Chris@14: ## Edge cases
Chris@14: 
Chris@14: The following structures cannot be deep-copied with PHP Reflection. As a result they are shallow cloned and filters are
Chris@14: not applied. There is two ways for you to handle them:
Chris@14: 
Chris@14: - Implement your own `__clone()` method
Chris@14: - Use a filter with a type matcher
Chris@14: 
Chris@14: 
Chris@14: ## Contributing
Chris@14: 
Chris@14: DeepCopy is distributed under the MIT license.
Chris@14: 
Chris@14: 
Chris@14: ### Tests
Chris@14: 
Chris@14: Running the tests is simple:
Chris@14: 
Chris@14: ```php
Chris@14: vendor/bin/phpunit
Chris@14: ```