Improve Schema API

Author: nyamsprod

docs/9.0/connections/instantiation.md

@@ -61,6 +61,7 @@ Alternatively, you can use the <code>fromStream</code> method.</p>
 ```php
 public static AbstractCsv::fromStream(SplFileObject|resource $stream): self
 ```
+
 Creates a new object from a stream resource or a streaming object.
 
 ```php

docs/9.0/reader/record-mapping.md

@@ -8,7 +8,7 @@ description: Converts your CSV records into PHP objects using PHP's powerful Ref
 
 <p class="message-notice">New in version <code>9.12.0</code></p>
 
-If you are working with a class which implements the `TabularDataReader` interface you can now deserialize
+If you are working with a class which implements the `TabularData` interface you can now deserialize
 your data using the `TabularDataReader::getRecordsAsObject` method. The method will convert your document records
 into objects using PHP's powerful Reflection API.
 

src/Buffer.php

@@ -224,9 +224,14 @@ public function reduce(callable $callback, mixed $initial = null): mixed
         return $initial;
     }
 
-    public function schema(?Inspector $inspector = null): Schema
+    public function inferSchema(?Inspector $inspector = null, array $header = []): Schema
     {
-        return ($inspector ?? Inspector::default())->schema($this);
+        return ($inspector ?? Inspector::default())->schema($this, $header);
+    }
+
+    public function inferRecords(?Inspector $inspector = null, array $header = []): Iterator
+    {
+        return $this->inferSchema($inspector, $header)->parse($this);
     }
 
     /**

src/Reader.php

@@ -418,9 +418,14 @@ public function map(callable $callback): Iterator
         return MapIterator::fromIterable($this, $callback);
     }
 
-    public function schema(?Inspector $inspector = null): Schema
+    public function inferSchema(?Inspector $inspector = null, array $header = []): Schema
     {
-        return ($inspector ?? Inspector::default())->schema($this);
+        return ($inspector ?? Inspector::default())->schema($this, $header);
+    }
+
+    public function inferRecords(?Inspector $inspector = null, array $header = []): Iterator
+    {
+        return $this->inferSchema($inspector, $header)->parse($this);
     }
 
     /**

src/ResultSet.php

@@ -208,9 +208,14 @@ public function map(callable $callback): Iterator
         return MapIterator::fromIterable($this, $callback);
     }
 
-    public function schema(?Inspector $inspector = null): Schema
+    public function inferSchema(?Inspector $inspector = null, array $header = []): Schema
     {
-        return ($inspector ?? Inspector::default())->schema($this);
+        return ($inspector ?? Inspector::default())->schema($this, $header);
+    }
+
+    public function inferRecords(?Inspector $inspector = null, array $header = []): Iterator
+    {
+        return $this->inferSchema($inspector, $header)->parse($this);
     }
 
     /**

src/Schema/BooleanField.php

@@ -22,7 +22,7 @@
 use const FILTER_NULL_ON_FAILURE;
 use const FILTER_VALIDATE_BOOLEAN;
 
-final class BooleanField extends AbstractField
+final class BooleanField extends FieldEvaluator implements Field
 {
     public function type(): FieldType
     {
@@ -51,4 +51,9 @@ public function parse(mixed $value): ?bool
 
         return filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE);
     }
+
+    public function metadata(): FieldMetadata
+    {
+        return new FieldMetadata();
+    }
 }

src/Schema/CallbackFieldParser.php

@@ -0,0 +1,45 @@
+<?php
+
+/**
+ * League.Csv (https://csv.thephpleague.com)
+ *
+ * (c) Ignace Nyamagana Butera <nyamsprod@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace League\Csv\Schema;
+
+use Closure;
+
+/**
+ * @template T
+ */
+final class CallbackFieldParser implements FieldParser
+{
+    /** @var Closure(mixed): ?T */
+    private Closure $callback;
+
+    /**
+     * @param (Closure(mixed): ?T)|(callable(mixed): ?T) $callback
+     */
+    public function __construct(Closure|callable $callback)
+    {
+        if (!$callback instanceof Closure) {
+            $callback = $callback(...);
+        }
+
+        $this->callback = $callback;
+    }
+
+    /**
+     * @returns ?T
+     */
+    public function parse(mixed $value): mixed
+    {
+        return ($this->callback)($value);
+    }
+}

src/Schema/CustomField.php

@@ -18,32 +18,31 @@
 
 use function preg_match;
 
-final class CustomField extends AbstractField
+/**
+ * @template T
+ */
+final class CustomField extends FieldEvaluator implements Field
 {
-    /**
-     * The closure MUST return null if it fails to parse the value.
-     * It should return the parsed value according to
-     * the callable logic.
-     *
-     * @var Closure(mixed): ?mixed
-     */
-    private readonly Closure $parser;
+    private readonly FieldParser $fieldParser;
     /** @var non-empty-string */
-    public readonly string $name;
+    private readonly string $fieldTypeName;
 
     public function __construct(
-        callable $parser,
-        string $name,
+        FieldParser|Closure|callable $fieldParser,
+        string $fieldTypeName,
         float $confidenceThreshold = 0.8
     ) {
-        ('' !== $name && 1 === preg_match('/^[a-z]+(?:_[a-z0-9]+)*$/', $name)) || throw new ValueError('The name "'.$name.'" is not a valid snake case variable name.');
+        ('' !== $fieldTypeName && 1 === preg_match('/^[a-z]+(?:_[a-z0-9]+)*$/', $fieldTypeName)) || throw new ValueError('The name "'.$fieldTypeName.'" is not a valid snake case variable name.');
+        $fieldParser = self::resolveFieldParser($fieldParser);
         parent::__construct($confidenceThreshold);
 
-        $this->parser = !$parser instanceof Closure
-            ? $parser(...)
-            : $parser;
+        $this->fieldParser = $fieldParser;
+        $this->fieldTypeName = $fieldTypeName;
+    }
 
-        $this->name = $name;
+    private static function resolveFieldParser(FieldParser|Closure|callable $parser): FieldParser
+    {
+        return $parser instanceof FieldParser ? $parser : new CallbackFieldParser($parser);
     }
 
     public function type(): FieldType
@@ -53,11 +52,19 @@ public function type(): FieldType
 
     public function name(): string
     {
-        return $this->name;
+        return $this->fieldTypeName;
     }
 
+    /**
+     * @return ?T
+     */
     public function parse(mixed $value): mixed
     {
-        return ($this->parser)($value);
+        return $this->fieldParser->parse($value);
+    }
+
+    public function metadata(): FieldMetadata
+    {
+        return new FieldMetadata();
     }
 }

src/Schema/DateField.php

@@ -15,30 +15,97 @@
 
 use DateTimeImmutable;
 use DateTimeInterface;
+use DateTimeZone;
 use Exception;
 use ValueError;
 
+use function array_map;
+use function array_values;
 use function is_string;
+use function iterator_to_array;
 use function trim;
 
-final class DateField extends AbstractField
+final class DateField extends FieldEvaluator implements Field
 {
-    public function __construct(public readonly string $format = '', float $confidenceThreshold = 0.8)
+    /** @var non-empty-string */
+    public readonly string $format;
+    public readonly ?DateTimeZone $timezone;
+
+    public function __construct(string $format, DateTimeZone|string|null $timezone = null, float $confidenceThreshold = 0.8)
     {
+        $format = trim($format);
+        '' !== $format || throw new ValueError('The date field format can not be empty.');
+        $timezone = self::filterTimezone($timezone);
+
         parent::__construct($confidenceThreshold);
+        $this->format = $format;
+        $this->timezone = $timezone;
     }
 
-    public static function native(float $confidenceThreshold = 0.8): self
+    public static function common(DateTimeZone|string|null $timezone = null): FieldList
     {
-        return new self(format: '', confidenceThreshold: $confidenceThreshold);
+        return self::machine($timezone)->append(self::localized($timezone));
     }
 
-    public static function withFormat(string $format, float $confidenceThreshold = 0.8): self
+    public static function machine(DateTimeZone|string|null $timezone = null): FieldList
     {
-        $format = trim($format);
-        '' !== $format || throw new ValueError('The date field strategy format can not be empty.');
+        $formats = [
+            'Y-m-d',
+            'Y-m-d H:i:s',
+            'Y-m-d\TH:i:s',
+            DateTimeInterface::RFC3339,
+            DateTimeInterface::RFC3339_EXTENDED,
+            DateTimeInterface::ISO8601_EXPANDED,
+        ];
+
+        return self::fromFormat($formats, $timezone, .8);
+    }
+
+    public static function localized(DateTimeZone|string|null $timezone = null): FieldList
+    {
+        $formats = [
+            // Europe Dates
+            'd/m/Y',
+            'd-m-Y',
+            'd.m.Y',
+            // American Dates
+            'm/d/Y',
+            'm-d-Y',
+            'm.d.Y',
+        ];
+
+        return self::fromFormat($formats, $timezone, .7);
+    }
+
+    /**
+     * @param iterable<non-empty-string> $formats
+     */
+    public static function fromFormat(
+        iterable $formats,
+        DateTimeZone|string|null $timezone = null,
+        float $confidenceThreshold = 0.8
+    ): FieldList {
+        return new FieldList(...array_values(array_map(
+            fn (string $format): DateField => new DateField($format, $timezone, $confidenceThreshold),
+            iterator_to_array($formats)
+        )));
+    }
+
+    private static function filterTimezone(DateTimeZone|string|null $timeZone): ?DateTimeZone
+    {
+        if (null === $timeZone) {
+            return null;
+        }
 
-        return new self(format: $format, confidenceThreshold: $confidenceThreshold);
+        if ($timeZone instanceof DateTimeZone) {
+            return $timeZone;
+        }
+
+        try {
+            return new DateTimeZone($timeZone);
+        } catch (Exception $exception) {
+            throw new ValueError('The date field timezone value `'.$timeZone.'` is invalid.', previous: $exception);
+        }
     }
 
     public function type(): FieldType
@@ -51,11 +118,6 @@ public function name(): string
         return FieldType::Date->value;
     }
 
-    public function format(): string
-    {
-        return $this->format;
-    }
-
     public function parse(mixed $value): ?DateTimeImmutable
     {
         if ($value instanceof DateTimeInterface) {
@@ -72,22 +134,30 @@ public function parse(mixed $value): ?DateTimeImmutable
         }
 
         try {
-            if ('' !== $this->format) {
-                $value = DateTimeImmutable::createFromFormat($this->format, $value);
+            $value = DateTimeImmutable::createFromFormat($this->format, $value, $this->timezone);
+            if (false === $value) {
+                return null;
+            }
 
-                return false === $value ? null : $value;
+            $errors = DateTimeImmutable::getLastErrors();
+            if (
+                (isset($errors['warning_count']) && 0 < $errors['warning_count']) ||
+                (isset($errors['error_count']) && 0 < $errors['error_count'])
+            ) {
+                return null;
             }
 
-            return new DateTimeImmutable($value);
-        } catch (Exception) {
+            return $value;
+        } catch (ValueError) {
             return null;
         }
     }
 
-    public function metadata(): Metadata
+    public function metadata(): FieldMetadata
     {
-        return new Metadata([
+        return new FieldMetadata([
             'format' => $this->format,
+            'timezone' => $this->timezone?->getName(),
         ]);
     }
 }

src/Schema/DateFieldTest.php

@@ -25,7 +25,7 @@ final class DateFieldTest extends TestCase
 
     protected function setUp(): void
     {
-        $this->field = DateField::native();
+        $this->field = new DateField('Y-m-d');
     }
 
     public function testParseUsesNativeConstructorWhenFormatIsEmpty(): void
@@ -38,7 +38,7 @@ public function testParseUsesNativeConstructorWhenFormatIsEmpty(): void
 
     public function testParseUsesCreateFromFormatWhenFormatIsProvided(): void
     {
-        $field = DateField::withFormat('d-m-Y');
+        $field = new DateField('d-m-Y');
         $result = $field->parse('01-01-2024');
 
         self::assertInstanceOf(DateTimeImmutable::class, $result);