• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..23-Jul-2021-

src/DeepCopy/H23-Jul-2021-989502

LICENSEH A D22-Jul-20211.1 KiB2116

README.mdH A D22-Jul-20219.7 KiB376237

composer.jsonH A D22-Jul-2021852 3935

README.md

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