annotate vendor/myclabs/deep-copy/README.md @ 19:fa3358dc1485 tip

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