Make DeepCopy API final and immutable

.travis.yml

@@ -30,7 +30,7 @@ before_script:
   - mkdir -p build/logs
 
 script:
-  - vendor/bin/phpstan analyse -l 7 src/ tests/ fixtures/
+  - vendor/bin/phpstan analyse -l7 -cphpstan.neon src/ tests/ fixtures/
   - vendor/bin/phpunit --coverage-clover build/logs/clover.xml
 
 after_script:

README.md

@@ -111,7 +111,7 @@ function deep_copy($var)
     static $copier = null;
 
     if (null === $copier) {
-        $copier = new DeepCopy(true);
+        $copier = new DeepCopy();
     }
 
     return $copier->copy($var);
@@ -124,8 +124,11 @@ function deep_copy($var)
 You can add filters to customize the copy process by adding filters:
 
 ```php
-$copier = new DeepCopy();
-$copier->addFilter($filter, $matcher);
+$copier = new DeepCopy(
+    false,
+    false,
+    [[$filter, $matcher]]
+);
 ```
 
 During the copy process, when a property is matched by a [matcher][matcher], then the [filter][filter] associated to
@@ -203,8 +206,11 @@ use DeepCopy\Filter\SetNullFilter;
 $object = MyClass::load(123);
 echo $object->id; // 123
 
-$copier = new DeepCopy();
-$copier->addFilter(new SetNullFilter(), new PropertyNameMatcher('id'));
+$copier = new DeepCopy(
+    false,
+    false,
+    [[new SetNullFilter(), new PropertyNameMatcher('id')]]
+);
 
 $copy = $copier->copy($object);
 
@@ -221,10 +227,10 @@ use DeepCopy\DeepCopy;
 use DeepCopy\Filter\KeepFilter;
 use DeepCopy\Matcher\PropertyMatcher;
 
-$copier = new DeepCopy();
-$copier->addFilter(
-    new KeepFilter(),
-    new PropertyMatcher(MyClass::class, 'category')
+$copier = new DeepCopy(
+    false,
+    false,
+    [[new KeepFilter(), new PropertyMatcher(MyClass::class, 'category')]]
 );
 
 $copy = $copier->copy($object); // $object is an instance of MyClass
@@ -242,10 +248,10 @@ use DeepCopy\Filter\Doctrine\DoctrineCollectionFilter;
 use DeepCopy\Matcher\PropertyTypeMatcher;
 use Doctrine\Common\Collections\Collection;
 
-$copier = new DeepCopy();
-$copier->addFilter(
-    new DoctrineCollectionFilter(),
-    new PropertyTypeMatcher(Collection::class)
+$copier = new DeepCopy(
+    false,
+    false,
+    [[new DoctrineCollectionFilter(), new PropertyTypeMatcher(Collection::class)]]
 );
 
 $copy = $copier->copy($object);
@@ -262,10 +268,10 @@ use DeepCopy\DeepCopy;
 use DeepCopy\Filter\Doctrine\DoctrineEmptyCollectionFilter;
 use DeepCopy\Matcher\PropertyMatcher;
 
-$copier = new DeepCopy();
-$copier->addFilter(
-    new DoctrineEmptyCollectionFilter(),
-    new PropertyMatcher(MyClass::class, 'myProperty')
+$copier = new DeepCopy(
+    false,
+    false,
+    [[new DoctrineEmptyCollectionFilter(), new PropertyMatcher(MyClass::class, 'myProperty')]]
 );
 
 $copy = $copier->copy($object);
@@ -292,9 +298,14 @@ use DeepCopy\Filter\SetNullFilter;
 use DeepCopy\Matcher\Doctrine\DoctrineProxyMatcher;
 use DeepCopy\Matcher\PropertyNameMatcher;
 
-$copier = new DeepCopy();
-$copier->addFilter(new DoctrineProxyFilter(), new DoctrineProxyMatcher());
-$copier->addFilter(new SetNullFilter(), new PropertyNameMatcher('id'));
+$copier = new DeepCopy(
+    false,
+    false,
+    [
+        [new DoctrineProxyFilter(), new DoctrineProxyMatcher()],
+        [new SetNullFilter(), new PropertyNameMatcher('id')],
+    ]
+);
 
 $copy = $copier->copy($object);
 
@@ -311,14 +322,19 @@ use DeepCopy\DeepCopy;
 use DeepCopy\Filter\ReplaceFilter;
 use DeepCopy\Matcher\PropertyMatcher;
 
-$copier = new DeepCopy();
-$copier->addFilter(
-    new ReplaceFilter(
-        function ($currentValue): string {
-            return $currentValue . ' (copy)'
-        }
-    ),
-    new PropertyMatcher(MyClass::class, 'title')
+$copier = new DeepCopy(
+    false,
+    false,
+    [
+        [
+            new ReplaceFilter(
+                 function ($currentValue): string {
+                     return $currentValue . ' (copy)'
+                 }
+            ),
+            new PropertyMatcher(MyClass::class, 'title'),
+        ],
+    ]
 );
 
 $copy = $copier->copy($object); // $object is an instance of MyClass
@@ -333,14 +349,19 @@ use DeepCopy\DeepCopy;
 use DeepCopy\TypeFilter\ReplaceFilter;
 use DeepCopy\TypeMatcher\TypeMatcher;
 
-$copier = new DeepCopy();
-$copier->addFilter(
-    new ReplaceFilter(
-        function (MyClass $myClass): string {
-            return get_class($myClass)
-        }
-    ),
-    new TypeMatcher(MyClass::class)
+$copier = new DeepCopy(
+    false,
+    false,
+    [
+        [
+            new ReplaceFilter(
+                function (MyClass $myClass): string {
+                    return get_class($myClass)
+                }
+            ),
+            new TypeMatcher(MyClass::class),
+        ],
+    ]
 );
 
 $copy = $copier->copy([new MyClass, 'some string', new MyClass]);
@@ -359,10 +380,11 @@ use DeepCopy\TypeFilter\ShallowCopyFilter;
 use DeepCopy\TypeMatcher\TypeMatcher;
 use Mockery as m;
 
-$copier = new DeepCopy();
-$copier->addTypeFilter(
-	new ShallowCopyFilter,
-	new TypeMatcher(m\MockInterface::class)
+$copier = new DeepCopy(
+    false,
+    false,
+    [],
+    [[new ShallowCopyFilter, new TypeMatcher(m\MockInterface::class)]]
 );
 
 $myServiceWithMocks = new MyService(

phpstan.neon

@@ -0,0 +1,4 @@
+parameters:
+    ignoreErrors:
+        - '#PHPDoc tag \@param has invalid value \(Array\<Filter\, Matcher\>#'
+        - '#PHPDoc tag \@param has invalid value \(Array\<TypeFilter\, TypeMatcher\>#'

src/DeepCopy/DeepCopy.php

@@ -21,7 +21,6 @@
 use function is_object;
 use function is_resource;
 use function spl_object_id;
-use function sprintf;
 
 final class DeepCopy
 {
@@ -40,35 +39,43 @@ final class DeepCopy
      */
     private $typeFilters = [];
 
-    private $skipUncloneable = false;
+    private $skipUncloneable;
     private $useCloneMethod;
 
     /**
-     * @param bool $useCloneMethod If set to true, when an object implements the __clone() function, it will be used
-     *                             instead of the regular deep cloning.
+     * @param bool $useCloneMethod           If set to true, when an object implements the __clone() function, it will
+     *                                       be used instead of the regular deep cloning.
+     * @param bool $skipUncloneable          If enabled, will not throw an exception when coming across an uncloneable
+     *                                       property.
+     * @param Array<Filter, Matcher>         List of filter-matcher pairs
+     * @param Array<TypeFilter, TypeMatcher> List of type filter-matcher pairs
      */
-    public function __construct(bool $useCloneMethod = false)
-    {
+    public function __construct(
+        bool $useCloneMethod = false,
+        bool $skipUncloneable = false,
+        array $filters = [],
+        array $typeFilters = []
+    ) {
         $this->useCloneMethod = $useCloneMethod;
 
-        $this->addTypeFilter(
+        foreach ($filters as [$filter, $matcher]) {
+            $this->addFilter($filter, $matcher);
+        }
+
+        $typeFilters[] = [
             new DateIntervalFilter(),
             new TypeMatcher(DateInterval::class)
-        );
-        $this->addTypeFilter(
+        ];
+        $typeFilters[] = [
             new SplDoublyLinkedListFilter($this),
             new TypeMatcher(SplDoublyLinkedList::class)
-        );
-    }
+        ];
 
-    /**
-     * If enabled, will not throw an exception when coming across an uncloneable property.
-     */
-    public function skipUncloneable(bool $skipUncloneable = true): self
-    {
-        $this->skipUncloneable = $skipUncloneable;
+        foreach ($typeFilters as [$filter, $matcher]) {
+            $this->addTypeFilter($filter, $matcher);
+        }
 
-        return $this;
+        $this->skipUncloneable = $skipUncloneable;
     }
 
     /**
@@ -85,16 +92,6 @@ public function copy($value)
         return $this->recursiveCopy($value);
     }
 
-    public function addFilter(Filter $filter, Matcher $matcher): void
-    {
-        $this->filters[] = [$matcher, $filter];
-    }
-
-    public function addTypeFilter(TypeFilter $filter, TypeMatcher $matcher): void
-    {
-        $this->typeFilters[] = [$matcher, $filter];
-    }
-
     /**
      * @return mixed
      */
@@ -146,12 +143,7 @@ private function copyObject(object $object): object
                 return $object;
             }
 
-            throw new CloneException(
-                sprintf(
-                    'The class "%s" is not cloneable.',
-                    $reflectedObject->getName()
-                )
-            );
+            throw CloneException::unclonableClass($reflectedObject->getName());
         }
 
         $newObject = clone $object;
@@ -217,6 +209,16 @@ function ($object) {
         $property->setValue($object, $this->recursiveCopy($propertyValue));
     }
 
+    private function addFilter(Filter $filter, Matcher $matcher): void
+    {
+        $this->filters[] = [$matcher, $filter];
+    }
+
+    private function addTypeFilter(TypeFilter $filter, TypeMatcher $matcher): void
+    {
+        $this->typeFilters[] = [$matcher, $filter];
+    }
+
     /**
      * @return TypeFilter|null The first filter that matches variable or `null` if no such filter found
      */

src/DeepCopy/Exception/CloneException.php

@@ -6,4 +6,13 @@
 
 class CloneException extends UnexpectedValueException
 {
+    final public static function unclonableClass(string $class): self
+    {
+        return new self(
+            sprintf(
+                'The class "%s" is not cloneable.',
+                $class
+            )
+        );
+    }
 }

src/DeepCopy/deep_copy.php

@@ -6,11 +6,20 @@
  * Deep copies the given value.
  *
  * @param mixed $value
- * @param bool  $useCloneMethod
- *
- * @return mixed
+ * @param bool $useCloneMethod           If set to true, when an object implements the __clone() function, it will
+ *                                       be used instead of the regular deep cloning.
+ * @param bool $skipUncloneable          If enabled, will not throw an exception when coming across an uncloneable
+ *                                       property.
+ * @param Array<Filter, Matcher>         List of filter-matcher pairs
+ * @param Array<TypeFilter, TypeMatcher> List of type filter-matcher pairs
  */
-function deep_copy($value, $useCloneMethod = false)
+function deep_copy(
+    $value,
+    bool $useCloneMethod = false,
+    bool $skipUncloneable = false,
+    array $filters = [],
+    array $typeFilters = []
+)
 {
-    return (new DeepCopy($useCloneMethod))->copy($value);
+    return (new DeepCopy($useCloneMethod, $skipUncloneable, $filters, $typeFilters))->copy($value);
 }