Rename Serializer class to Deserializer

Author: nyamsprod

CHANGELOG.md

@@ -16,7 +16,7 @@ All Notable changes to `Csv` will be documented in this file
 - `ResultSet::fromRecords`
 - `Stream::setMaxLineLen`
 - `Stream::getMaxLineLen`
-- `League\Csv\Serializer` to allow casting records to objects [#508](https://github.com/thephpleague/csv/issues/508)
+- `League\Csv\Deserializer` to allow casting records to objects [#508](https://github.com/thephpleague/csv/issues/508)
 
 ### Deprecated
 

docs/9.0/reader/record-mapping.md

@@ -9,16 +9,16 @@ title: Deserializing a Tabular Data record into an object
 
 ## Assign an array to an object
 
-To work with objects instead of arrays the `Serializer` class is introduced to expose a
+To work with objects instead of arrays the `Deserializer` class is introduced to expose a
 text based deserialization mechanism for tabular data.
 
 The class exposes four (4) methods to ease `array` to `object` conversion:
 
-- `Serializer::deserializeAll` and `Serializer::assignAll` which convert a collection of records into a collection of instances of a specified class.
-- `Serializer::deserialize` and `Serializer::assign` which convert a single record into a new instance of the specified class.
+- `Deserializer::deserializeAll` and `Deserializer::assignAll` which convert a collection of records into a collection of instances of a specified class.
+- `Deserializer::deserialize` and `Deserializer::assign` which convert a single record into a new instance of the specified class.
 
 ```php
-use League\Csv\Serializer;
+use League\Csv\Deserializer;
 
 $record = [
     'date' => '2023-10-30',
@@ -29,7 +29,7 @@ $record = [
 //a complete collection of records as shown below
 $collection = [$record];
 //we first instantiate the serializer
-$serializer = new Serializer(Weather::class, ['date', 'temperature', 'place']);
+$serializer = new Deserializer(Weather::class, ['date', 'temperature', 'place']);
 
 $weather = $serializer->deserialize($record); //we convert 1 record into 1 instance
 foreach ($serializer->deserializeAll($collection) as $weather) {
@@ -38,9 +38,9 @@ foreach ($serializer->deserializeAll($collection) as $weather) {
 
 // you can use the alternate syntactic sugar methods 
 // if you only need the deserializing mechanism once
-$weather = Serializer::assign(Weather::class, $record);
+$weather = Deserializer::assign(Weather::class, $record);
 
-foreach (Serializer::assignAll(Weather::class, $collection, ['date', 'temperature', 'place']) as $weather) {
+foreach (Deserializer::assignAll(Weather::class, $collection, ['date', 'temperature', 'place']) as $weather) {
     // each $weather entry will be an instance of the Weather class;
 }
 ```
@@ -113,15 +113,15 @@ enum Place
 }
 ```
 
-To get instances of your object, you now can call one of the `Serializer` method as show below:
+To get instances of your object, you now can call one of the `Deserializer` method as show below:
 
 ```php
 use League\Csv\Reader;
-use League\Csv\Serializer
+use League\Csv\Deserializer
 
 $csv = Reader::createFromString($document);
 $csv->setHeaderOffset(0);
-$serializer = new Serializer(Weather::class, $csv->header());
+$serializer = new Deserializer(Weather::class, $csv->header());
 
 foreach ($csv as $record) {
    $weather = $serializer->deserialize($record);
@@ -135,7 +135,7 @@ foreach ($serializer->deserializeAll($csv) as $weather) {
 
 //or 
 
-foreach (Serializer::assignAll(Weather::class, $csv, $csv->getHeader()) as $weather) {
+foreach (Deserializer::assignAll(Weather::class, $csv, $csv->getHeader()) as $weather) {
     // each $weather entry will be an instance of the Weather class;
 }
 ```
@@ -197,31 +197,31 @@ The above rule can be translated in plain english like this:
 
 ### Handling the empty string
 
-Out of the box the `Serializer` makes no distinction between an empty string and the `null` value.
+Out of the box the `Deserializer` makes no distinction between an empty string and the `null` value.
 You can however change this behaviour using two (2) static methods:
 
-- `Serializer::allowEmptyStringAsNull`
-- `Serializer::disallowEmptyStringAsNull`
+- `Deserializer::allowEmptyStringAsNull`
+- `Deserializer::disallowEmptyStringAsNull`
 
 When called these methods will change the class behaviour when it comes to handling empty string.
-`Serializer::allowEmptyStringAsNull` will trigger conversion of all empty string into the `null` value
-before typecasting whereas `Serializer::disallowEmptyStringAsNull` will maintain the distinction.
-Using these methods will affect the `Serializer` usage throughout your codebase.
+`Deserializer::allowEmptyStringAsNull` will trigger conversion of all empty string into the `null` value
+before typecasting whereas `Deserializer::disallowEmptyStringAsNull` will maintain the distinction.
+Using these methods will affect the `Deserializer` usage throughout your codebase.
 
 ```php
-use League\Csv\Serializer;
+use League\Csv\Deserializer;
 
 $record = [
     'date' => '2023-10-30',
     'temperature' => '',
     'place' => 'Berkeley',
 ];
 
-$weather = Serializer::assign(Weather::class, $record);
+$weather = Deserializer::assign(Weather::class, $record);
 $weather->temperature; // returns null
 
-Serializer::disallowEmptyStringAsNull();
-Serializer::assign(Weather::class, $record);
+Deserializer::disallowEmptyStringAsNull();
+Deserializer::assign(Weather::class, $record);
 //a TypeCastingFailed exception is thrown because we
 //can not convert the empty string into a temperature property
 //which expects `null` or a non-empty string.
@@ -330,7 +330,7 @@ use League\Csv\Serializer;
 private array $data;
 ```
 
-In the above example, the array has a JSON value associated with the key `data` and the `Serializer` will convert the
+In the above example, the array has a JSON value associated with the key `data` and the `Deserializer` will convert the
 JSON string into an `array` and use the `JSON_BIGINT_AS_STRING` option of the `json_decode` function.
 
 If you use the array shape `list` or `csv` you can also typecast the `array` content using the
@@ -355,35 +355,37 @@ The `type` option only supports scalar type (`string`, `int`, `float` and `bool`
 
 ## Extending Type Casting capabilities
 
-We provide two mechanisms to extends typecasting. You can register a closure via the `Serializer` class
+We provide two mechanisms to extends typecasting. You can register a closure via the `Deserializer` class
 or create a fully fledge `TypeCasting` class. Of course, the choice will depend on your use case.
 
 ### Registering a closure
 
-You can register a closure using the `Serializer` class to convert a specific type. The type can be
+You can register a closure using the `Deserializer` class to convert a specific type. The type can be
 any built-in type or a specific class.
 
 ```php
 use App\Domain\Money;
-use League\Csv\Serializer;
+use League\Csv\Deserializer;
 
-Serializer::registerType(Money::class, fn (?string $value, bool $isNullable, ?int $default = null): Money => match (true) {
-    $isNullable && null === $value =>  Money::fromNaira($default ?? 20_00),
+$typeCasting = fn (?string $value, bool $isNullable, int $default = 20_00): Money => match (true) {
+    $isNullable && null === $value =>  Money::fromNaira($default),
     default => Money::fromNaira(filter_var($value, FILTER_VALIDATE_INT)),
-});
+};
+
+Deserializer::registerType(Money::class, $typeCasting);
 ```
 
-The Serializer will automatically call the closure for any `App\Domain\Money` conversion.
+The `Deserializer` will automatically call the closure for any `App\Domain\Money` conversion.
 
 ```php
-use League\Csv\Serializer;
+use League\Csv\Deserializer;
 
-Serializer::registerType('int', fn (?string $value): int => 42);
+Deserializer::registerType('int', fn (?string $value): int => 42);
 ```
 
 In the following example, the closure takes precedence over the `CastToInt` class to convert
 to the `int` type. If you still wish to use the `CastToInt` class you are require to
-explicitly declare it using the `Cell` attribute `cast` argument.
+explicitly declare it via the `Cell` attribute `cast` argument.
 
 The closure signature is the following:
 
@@ -399,7 +401,7 @@ where:
 
 To complete the feature you can use:
 
-- `Serializer::unregisterType` to remove the registered closure for a specific `type`;
+- `Deserializer::unregisterType` to remove the registered closure for a specific `type`;
 
 The two (2) methods are static.
 

src/Serializer.php renamed to src/Deserializer.php

@@ -31,7 +31,6 @@
 use League\Csv\Serializer\TypeCastingFailed;
 use ReflectionAttribute;
 use ReflectionClass;
-use ReflectionException;
 use ReflectionMethod;
 use ReflectionParameter;
 use ReflectionProperty;
@@ -42,10 +41,9 @@
 use function array_search;
 use function array_values;
 use function count;
-use function in_array;
 use function is_int;
 
-final class Serializer
+final class Deserializer
 {
     private static bool $emptyStringAsNull = true;
 
@@ -60,15 +58,33 @@ final class Serializer
      * @param array<string> $propertyNames
      *
      * @throws MappingFailed
-     * @throws ReflectionException
      */
     public function __construct(string $className, array $propertyNames = [])
     {
-        $this->class = new ReflectionClass($className);
+        $this->class = $this->filterClass($className);
         $this->properties = $this->class->getProperties();
         $this->propertySetters = $this->findPropertySetters($propertyNames);
     }
 
+    /**
+     * @param class-string $className
+     *
+     * @throws MappingFailed
+     */
+    private function filterClass(string $className): ReflectionClass
+    {
+        if (!class_exists($className)) {
+            throw new MappingFailed('The class `'.$className.'` does not exist or was not found.');
+        }
+
+        $class = new ReflectionClass($className);
+        if ($class->isInternal() && $class->isFinal()) {
+            throw new MappingFailed('The class `'.$className.'` can not be deserialize using `'.self::class.'`.');
+        }
+
+        return $class;
+    }
+
     public static function allowEmptyStringAsNull(): void
     {
         self::$emptyStringAsNull = true;
@@ -94,7 +110,6 @@ public static function unregisterType(string $type): void
      * @param array<?string> $record
      *
      * @throws MappingFailed
-     * @throws ReflectionException
      * @throws TypeCastingFailed
      */
     public static function assign(string $className, array $record): object
@@ -107,7 +122,6 @@ public static function assign(string $className, array $record): object
      * @param array<string> $propertyNames
      *
      * @throws MappingFailed
-     * @throws ReflectionException
      * @throws TypeCastingFailed
      */
     public static function assignAll(string $className, iterable $records, array $propertyNames = []): Iterator
@@ -134,7 +148,6 @@ public function deserializeAll(iterable $records): Iterator
     }
 
     /**
-     * @throws ReflectionException
      * @throws TypeCastingFailed
      */
     public function deserialize(array $record): object
@@ -186,32 +199,36 @@ private function assertObjectIsInValidState(object $object): void
      */
     private function findPropertySetters(array $propertyNames): array
     {
-        $propertySetters = [];
-        foreach ($this->class->getProperties(ReflectionProperty::IS_PUBLIC) as $property) {
+        $autoDiscoverPropertySetters = function (array $carry, ReflectionProperty $property) use ($propertyNames): array {
             if ($property->isStatic()) {
-                continue;
+                return $carry;
             }
 
             $attribute = $property->getAttributes(Cell::class, ReflectionAttribute::IS_INSTANCEOF);
             if ([] !== $attribute) {
-                continue;
+                return $carry;
             }
 
             /** @var int|false $offset */
             $offset = array_search($property->getName(), $propertyNames, true);
             if (false === $offset) {
-                continue;
+                return $carry;
             }
 
-            $propertySetters[] = new PropertySetter($property, $offset, $this->resolveTypeCasting($property));
-        }
+            return [...$carry, new PropertySetter($property, $offset, $this->resolveTypeCasting($property))];
+        };
 
-        $propertySetters = [...$propertySetters, ...$this->findPropertySettersByAttribute($propertyNames)];
-        if ([] === $propertySetters) {
-            throw new MappingFailed('No properties or method setters were found eligible on the class `'.$this->class->getName().'` to be used for type casting.');
-        }
+        $propertySetters = [...array_reduce(
+            $this->class->getProperties(ReflectionProperty::IS_PUBLIC),
+            $autoDiscoverPropertySetters,
+            []
+        ), ...$this->findPropertySettersByAttribute($propertyNames)];
 
-        return $propertySetters;
+        return match ([]) {
+            $propertySetters => throw new MappingFailed('No properties or method setters were found eligible on the class `'.$this->class->getName().'` to be used for type casting.'),
+            default => $propertySetters,
+
+        };
     }
 
     /**
@@ -223,13 +240,11 @@ private function findPropertySettersByAttribute(array $propertyNames): array
     {
         $addPropertySetter = function (array $carry, ReflectionProperty|ReflectionMethod $accessor) use ($propertyNames) {
             $propertySetter = $this->findPropertySetter($accessor, $propertyNames);
-            if (null === $propertySetter) {
-                return $carry;
-            }
-
-            $carry[] = $propertySetter;
 
-            return $carry;
+            return match (null) {
+                $propertySetter => $carry,
+                default => [...$carry, $propertySetter],
+            };
         };
 
         return array_reduce(
@@ -303,7 +318,7 @@ private function getTypeCasting(Cell $cell, ReflectionProperty|ReflectionMethod
             return $this->resolveTypeCasting($reflectionProperty, $cell->castArguments);
         }
 
-        if (!in_array(TypeCasting::class, class_implements($typeCaster), true)) {
+        if (!class_exists($typeCaster) || !(new ReflectionClass($typeCaster))->implementsInterface(TypeCasting::class)) {
             throw new MappingFailed('The class `'.$typeCaster.'` does not implements the `'.TypeCasting::class.'` interface.');
         }