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 [](https://travis-ci.org/myclabs/DeepCopy)
|
Chris@14
|
6 [](https://coveralls.io/r/myclabs/DeepCopy?branch=master)
|
Chris@14
|
7 [](https://scrutinizer-ci.com/g/myclabs/DeepCopy/)
|
Chris@14
|
8 [](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 
|
Chris@14
|
73
|
Chris@14
|
74
|
Chris@14
|
75 ### Using simply `clone`
|
Chris@14
|
76
|
Chris@14
|
77 
|
Chris@14
|
78
|
Chris@14
|
79
|
Chris@14
|
80 ### Overridding `__clone()`
|
Chris@14
|
81
|
Chris@14
|
82 
|
Chris@14
|
83
|
Chris@14
|
84
|
Chris@14
|
85 ### With `DeepCopy`
|
Chris@14
|
86
|
Chris@14
|
87 
|
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 ```
|