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

@@ -15,6 +15,7 @@
 
 use DateTimeImmutable;
 use DateTimeInterface;
+use DateTimeZone;
 use Exception;
 use ValueError;
 
@@ -23,22 +24,35 @@
 
 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
+    private static function filterTimezone(DateTimeZone|string|null $timeZone): ?DateTimeZone
     {
-        return new self(format: '', confidenceThreshold: $confidenceThreshold);
-    }
+        if (null === $timeZone) {
+            return null;
+        }
 
-    public static function withFormat(string $format, float $confidenceThreshold = 0.8): self
-    {
-        $format = trim($format);
-        '' !== $format || throw new ValueError('The date field strategy format can not be empty.');
+        if ($timeZone instanceof DateTimeZone) {
+            return $timeZone;
+        }
 
-        return new self(format: $format, confidenceThreshold: $confidenceThreshold);
+        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 +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) {
@@ -72,22 +81,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,
         ]);
     }

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;
 }