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/AbstractField.php

@@ -69,8 +69,8 @@ public function evaluate(mixed $value): int
         return null !== $this->parse($value) ? 1 : -1;
     }
 
-    public function metadata(): Metadata
+    public function metadata(): FieldMetadata
     {
-        return new Metadata();
+        return new FieldMetadata();
     }
 }

src/Schema/CustomField.php

@@ -18,34 +18,50 @@
 
 use function preg_match;
 
+/**
+ * @template T
+ */
 final class CustomField extends AbstractField
 {
-    /**
-     * 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 $parser;
     /** @var non-empty-string */
     public readonly string $name;
 
     public function __construct(
-        callable $parser,
+        FieldParser|Closure|callable $parser,
         string $name,
         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.');
+        $fieldParser = self::resolveParser($parser);
         parent::__construct($confidenceThreshold);
 
-        $this->parser = !$parser instanceof Closure
-            ? $parser(...)
-            : $parser;
-
+        $this->parser = $fieldParser;
         $this->name = $name;
     }
 
+    private static function resolveParser(FieldParser|Closure|callable $parser): FieldParser
+    {
+        if ($parser instanceof FieldParser) {
+            return $parser;
+        }
+
+        if (!$parser instanceof Closure) {
+            $parser = Closure::fromCallable($parser);
+        }
+
+        return new class ($parser) implements FieldParser {
+            public function __construct(private Closure $parser)
+            {
+            }
+
+            public function parse(mixed $value): mixed
+            {
+                return ($this->parser)($value);
+            }
+        };
+    }
+
     public function type(): FieldType
     {
         return FieldType::Custom;
@@ -56,8 +72,11 @@ public function name(): string
         return $this->name;
     }
 
+    /**
+     * @return ?T
+     */
     public function parse(mixed $value): mixed
     {
-        return ($this->parser)($value);
+        return $this->parser->parse($value);
     }
 }

src/Schema/DateField.php

@@ -15,6 +15,7 @@
 
 use DateTimeImmutable;
 use DateTimeInterface;
+use DateTimeZone;
 use Exception;
 use ValueError;
 
@@ -23,22 +24,85 @@
 
 final class DateField extends AbstractField
 {
-    public function __construct(public readonly string $format = '', float $confidenceThreshold = 0.8)
+    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 = [
+            'd/m/Y',
+            'd-m-Y',
+            'd.m.Y',
+            '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 {
+
+        $fields = [];
+        foreach ($formats as $format) {
+            $fields[] = new DateField($format, $timezone, $confidenceThreshold);
+        }
+
+        return new FieldList(...$fields);
+    }
 
-        return new self(format: $format, confidenceThreshold: $confidenceThreshold);
+    private static function filterTimezone(DateTimeZone|string|null $timeZone): ?DateTimeZone
+    {
+        if (null === $timeZone) {
+            return null;
+        }
+
+        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 +115,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 +131,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);

src/Schema/EnumField.php

@@ -107,9 +107,9 @@ public function parse(mixed $value): ?UnitEnum
         return $enumClass::tryFrom($value);
     }
 
-    public function metadata(): Metadata
+    public function metadata(): FieldMetadata
     {
-        return new Metadata([
+        return new FieldMetadata([
             'class' => $this->enumClass,
         ]);
     }