Improve Schema API and DateField 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,14 +224,14 @@ public function reduce(callable $callback, mixed $initial = null): mixed
         return $initial;
     }
 
-    public function schema(?Inspector $inspector = null, array $header = []): Schema
+    public function inferSchema(?Inspector $inspector = null, array $header = []): Schema
     {
         return ($inspector ?? Inspector::default())->schema($this, $header);
     }
 
-    public function getTypedRecords(?Inspector $inspector = null, array $header = []): Iterator
+    public function inferRecords(?Inspector $inspector = null, array $header = []): Iterator
     {
-        return $this->schema($inspector)->parse($this, $header);
+        return $this->inferSchema($inspector, $header)->parse($this, $header);
     }
 
     /**

src/Reader.php

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

src/ResultSet.php

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

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

@@ -15,6 +15,7 @@
 
 use DateTimeImmutable;
 use DateTimeInterface;
+use DateTimeZone;
 use Exception;
 use ValueError;
 
@@ -24,14 +25,34 @@
 final class DateField extends AbstractField
 {
     public readonly string $format;
+    public readonly ?DateTimeZone $timeZone;
 
-    public function __construct(string $format, float $confidenceThreshold = 0.8)
+    public function __construct(string $format, DateTimeZone|string|null $timeZone = null, float $confidenceThreshold = 0.8)
     {
         $format = trim($format);
-        '' !== $format || throw new ValueError('The date field strategy format can not be empty.');
+        '' !== $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;
+    }
+
+    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
@@ -44,11 +65,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) {
@@ -65,18 +81,30 @@ public function parse(mixed $value): ?DateTimeImmutable
         }
 
         try {
-            $value = DateTimeImmutable::createFromFormat($this->format, $value);
-
-            return false === $value ? null : $value;
-        } catch (Exception) {
+            $value = DateTimeImmutable::createFromFormat($this->format, $value, $this->timeZone);
+            if (false === $value) {
+                return null;
+            }
+
+            $errors = DateTimeImmutable::getLastErrors();
+            if (
+                (isset($errors['warning_count']) && 0 < $errors['warning_count']) ||
+                (isset($errors['error_count']) && 0 < $errors['error_count'])
+            ) {
+                return null;
+            }
+
+            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/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,
         ]);
     }

src/Schema/Field.php

@@ -34,6 +34,11 @@ public function name(): string;
      */
     public function parse(mixed $value): mixed;
 
+    /**
+     * Returns the confidence on the field value
+     *
+     * The range of valide value is from 0.0 up to including 1.0
+     */
     public function confidenceThreshold(): float;
 
     /**
@@ -58,5 +63,5 @@ public function score(iterable $values): float;
      */
     public function evaluate(mixed $value): int;
 
-    public function metadata(): Metadata;
+    public function metadata(): FieldMetadata;
 }

src/Schema/FieldListTest.php

@@ -48,9 +48,9 @@ public function name(): string
                 return $this->type->name;
             }
 
-            public function metadata(): Metadata
+            public function metadata(): FieldMetadata
             {
-                return new Metadata();
+                return new FieldMetadata();
             }
 
             public function confidenceThreshold(): float