1# DeepCopy 2 3DeepCopy helps you create deep copies (clones) of your objects. It is designed to handle cycles in the association graph. 4 5[![Build Status](https://travis-ci.org/myclabs/DeepCopy.png?branch=1.x)](https://travis-ci.org/myclabs/DeepCopy) 6[![Coverage Status](https://coveralls.io/repos/myclabs/DeepCopy/badge.png?branch=1.x)](https://coveralls.io/r/myclabs/DeepCopy?branch=1.x) 7[![Scrutinizer Quality Score](https://scrutinizer-ci.com/g/myclabs/DeepCopy/badges/quality-score.png?s=2747100c19b275f93a777e3297c6c12d1b68b934)](https://scrutinizer-ci.com/g/myclabs/DeepCopy/) 8[![Total Downloads](https://poser.pugx.org/myclabs/deep-copy/downloads.svg)](https://packagist.org/packages/myclabs/deep-copy) 9 10## Table of Contents 11 121. [How](#how) 131. [Why](#why) 14 1. [Using simply `clone`](#using-simply-clone) 15 1. [Overridding `__clone()`](#overridding-__clone) 16 1. [With `DeepCopy`](#with-deepcopy) 171. [How it works](#how-it-works) 181. [Going further](#going-further) 19 1. [Matchers](#matchers) 20 1. [Property name](#property-name) 21 1. [Specific property](#specific-property) 22 1. [Type](#type) 23 1. [Filters](#filters) 24 1. [`SetNullFilter`](#setnullfilter-filter) 25 1. [`KeepFilter`](#keepfilter-filter) 26 1. [`DoctrineCollectionFilter`](#doctrinecollectionfilter-filter) 27 1. [`DoctrineEmptyCollectionFilter`](#doctrineemptycollectionfilter-filter) 28 1. [`DoctrineProxyFilter`](#doctrineproxyfilter-filter) 29 1. [`ReplaceFilter`](#replacefilter-type-filter) 30 1. [`ShallowCopyFilter`](#shallowcopyfilter-type-filter) 311. [Edge cases](#edge-cases) 321. [Contributing](#contributing) 33 1. [Tests](#tests) 34 35 36## How? 37 38Install with Composer: 39 40```json 41composer require myclabs/deep-copy 42``` 43 44Use simply: 45 46```php 47use DeepCopy\DeepCopy; 48 49$copier = new DeepCopy(); 50$myCopy = $copier->copy($myObject); 51``` 52 53 54## Why? 55 56- How do you create copies of your objects? 57 58```php 59$myCopy = clone $myObject; 60``` 61 62- How do you create **deep** copies of your objects (i.e. copying also all the objects referenced in the properties)? 63 64You use [`__clone()`](http://www.php.net/manual/en/language.oop5.cloning.php#object.clone) and implement the behavior 65yourself. 66 67- But how do you handle **cycles** in the association graph? 68 69Now you're in for a big mess :( 70 71![association graph](doc/graph.png) 72 73 74### Using simply `clone` 75 76![Using clone](doc/clone.png) 77 78 79### Overridding `__clone()` 80 81![Overridding __clone](doc/deep-clone.png) 82 83 84### With `DeepCopy` 85 86![With DeepCopy](doc/deep-copy.png) 87 88 89## How it works 90 91DeepCopy recursively traverses all the object's properties and clones them. To avoid cloning the same object twice it 92keeps a hash map of all instances and thus preserves the object graph. 93 94To use it: 95 96```php 97use function DeepCopy\deep_copy; 98 99$copy = deep_copy($var); 100``` 101 102Alternatively, you can create your own `DeepCopy` instance to configure it differently for example: 103 104```php 105use DeepCopy\DeepCopy; 106 107$copier = new DeepCopy(true); 108 109$copy = $copier->copy($var); 110``` 111 112You may want to roll your own deep copy function: 113 114```php 115namespace Acme; 116 117use DeepCopy\DeepCopy; 118 119function deep_copy($var) 120{ 121 static $copier = null; 122 123 if (null === $copier) { 124 $copier = new DeepCopy(true); 125 } 126 127 return $copier->copy($var); 128} 129``` 130 131 132## Going further 133 134You can add filters to customize the copy process. 135 136The method to add a filter is `DeepCopy\DeepCopy::addFilter($filter, $matcher)`, 137with `$filter` implementing `DeepCopy\Filter\Filter` 138and `$matcher` implementing `DeepCopy\Matcher\Matcher`. 139 140We provide some generic filters and matchers. 141 142 143### Matchers 144 145 - `DeepCopy\Matcher` applies on a object attribute. 146 - `DeepCopy\TypeMatcher` applies on any element found in graph, including array elements. 147 148 149#### Property name 150 151The `PropertyNameMatcher` will match a property by its name: 152 153```php 154use DeepCopy\Matcher\PropertyNameMatcher; 155 156// Will apply a filter to any property of any objects named "id" 157$matcher = new PropertyNameMatcher('id'); 158``` 159 160 161#### Specific property 162 163The `PropertyMatcher` will match a specific property of a specific class: 164 165```php 166use DeepCopy\Matcher\PropertyMatcher; 167 168// Will apply a filter to the property "id" of any objects of the class "MyClass" 169$matcher = new PropertyMatcher('MyClass', 'id'); 170``` 171 172 173#### Type 174 175The `TypeMatcher` will match any element by its type (instance of a class or any value that could be parameter of 176[gettype()](http://php.net/manual/en/function.gettype.php) function): 177 178```php 179use DeepCopy\TypeMatcher\TypeMatcher; 180 181// Will apply a filter to any object that is an instance of Doctrine\Common\Collections\Collection 182$matcher = new TypeMatcher('Doctrine\Common\Collections\Collection'); 183``` 184 185 186### Filters 187 188- `DeepCopy\Filter` applies a transformation to the object attribute matched by `DeepCopy\Matcher` 189- `DeepCopy\TypeFilter` applies a transformation to any element matched by `DeepCopy\TypeMatcher` 190 191 192#### `SetNullFilter` (filter) 193 194Let's say for example that you are copying a database record (or a Doctrine entity), so you want the copy not to have 195any ID: 196 197```php 198use DeepCopy\DeepCopy; 199use DeepCopy\Filter\SetNullFilter; 200use DeepCopy\Matcher\PropertyNameMatcher; 201 202$object = MyClass::load(123); 203echo $object->id; // 123 204 205$copier = new DeepCopy(); 206$copier->addFilter(new SetNullFilter(), new PropertyNameMatcher('id')); 207 208$copy = $copier->copy($object); 209 210echo $copy->id; // null 211``` 212 213 214#### `KeepFilter` (filter) 215 216If you want a property to remain untouched (for example, an association to an object): 217 218```php 219use DeepCopy\DeepCopy; 220use DeepCopy\Filter\KeepFilter; 221use DeepCopy\Matcher\PropertyMatcher; 222 223$copier = new DeepCopy(); 224$copier->addFilter(new KeepFilter(), new PropertyMatcher('MyClass', 'category')); 225 226$copy = $copier->copy($object); 227// $copy->category has not been touched 228``` 229 230 231#### `DoctrineCollectionFilter` (filter) 232 233If you use Doctrine and want to copy an entity, you will need to use the `DoctrineCollectionFilter`: 234 235```php 236use DeepCopy\DeepCopy; 237use DeepCopy\Filter\Doctrine\DoctrineCollectionFilter; 238use DeepCopy\Matcher\PropertyTypeMatcher; 239 240$copier = new DeepCopy(); 241$copier->addFilter(new DoctrineCollectionFilter(), new PropertyTypeMatcher('Doctrine\Common\Collections\Collection')); 242 243$copy = $copier->copy($object); 244``` 245 246 247#### `DoctrineEmptyCollectionFilter` (filter) 248 249If you use Doctrine and want to copy an entity who contains a `Collection` that you want to be reset, you can use the 250`DoctrineEmptyCollectionFilter` 251 252```php 253use DeepCopy\DeepCopy; 254use DeepCopy\Filter\Doctrine\DoctrineEmptyCollectionFilter; 255use DeepCopy\Matcher\PropertyMatcher; 256 257$copier = new DeepCopy(); 258$copier->addFilter(new DoctrineEmptyCollectionFilter(), new PropertyMatcher('MyClass', 'myProperty')); 259 260$copy = $copier->copy($object); 261 262// $copy->myProperty will return an empty collection 263``` 264 265 266#### `DoctrineProxyFilter` (filter) 267 268If you use Doctrine and use cloning on lazy loaded entities, you might encounter errors mentioning missing fields on a 269Doctrine proxy class (...\\\_\_CG\_\_\Proxy). 270You can use the `DoctrineProxyFilter` to load the actual entity behind the Doctrine proxy class. 271**Make sure, though, to put this as one of your very first filters in the filter chain so that the entity is loaded 272before other filters are applied!** 273 274```php 275use DeepCopy\DeepCopy; 276use DeepCopy\Filter\Doctrine\DoctrineProxyFilter; 277use DeepCopy\Matcher\Doctrine\DoctrineProxyMatcher; 278 279$copier = new DeepCopy(); 280$copier->addFilter(new DoctrineProxyFilter(), new DoctrineProxyMatcher()); 281 282$copy = $copier->copy($object); 283 284// $copy should now contain a clone of all entities, including those that were not yet fully loaded. 285``` 286 287 288#### `ReplaceFilter` (type filter) 289 2901. If you want to replace the value of a property: 291 292```php 293use DeepCopy\DeepCopy; 294use DeepCopy\Filter\ReplaceFilter; 295use DeepCopy\Matcher\PropertyMatcher; 296 297$copier = new DeepCopy(); 298$callback = function ($currentValue) { 299 return $currentValue . ' (copy)' 300}; 301$copier->addFilter(new ReplaceFilter($callback), new PropertyMatcher('MyClass', 'title')); 302 303$copy = $copier->copy($object); 304 305// $copy->title will contain the data returned by the callback, e.g. 'The title (copy)' 306``` 307 3082. If you want to replace whole element: 309 310```php 311use DeepCopy\DeepCopy; 312use DeepCopy\TypeFilter\ReplaceFilter; 313use DeepCopy\TypeMatcher\TypeMatcher; 314 315$copier = new DeepCopy(); 316$callback = function (MyClass $myClass) { 317 return get_class($myClass); 318}; 319$copier->addTypeFilter(new ReplaceFilter($callback), new TypeMatcher('MyClass')); 320 321$copy = $copier->copy([new MyClass, 'some string', new MyClass]); 322 323// $copy will contain ['MyClass', 'some string', 'MyClass'] 324``` 325 326 327The `$callback` parameter of the `ReplaceFilter` constructor accepts any PHP callable. 328 329 330#### `ShallowCopyFilter` (type filter) 331 332Stop *DeepCopy* from recursively copying element, using standard `clone` instead: 333 334```php 335use DeepCopy\DeepCopy; 336use DeepCopy\TypeFilter\ShallowCopyFilter; 337use DeepCopy\TypeMatcher\TypeMatcher; 338use Mockery as m; 339 340$this->deepCopy = new DeepCopy(); 341$this->deepCopy->addTypeFilter( 342 new ShallowCopyFilter, 343 new TypeMatcher(m\MockInterface::class) 344); 345 346$myServiceWithMocks = new MyService(m::mock(MyDependency1::class), m::mock(MyDependency2::class)); 347// All mocks will be just cloned, not deep copied 348``` 349 350 351## Edge cases 352 353The following structures cannot be deep-copied with PHP Reflection. As a result they are shallow cloned and filters are 354not applied. There is two ways for you to handle them: 355 356- Implement your own `__clone()` method 357- Use a filter with a type matcher 358 359 360## Contributing 361 362DeepCopy is distributed under the MIT license. 363 364 365### Tests 366 367Running the tests is simple: 368 369```php 370vendor/bin/phpunit 371``` 372 373### Support 374 375Get professional support via [the Tidelift Subscription](https://tidelift.com/subscription/pkg/packagist-myclabs-deep-copy?utm_source=packagist-myclabs-deep-copy&utm_medium=referral&utm_campaign=readme). 376