Review date and time interfaces and classes

- Review `DateFormatter`
- Review `IDateFormatter` and rename to `DateFormatterInterface`
- Review `IDateParser` and rename to `DateParserInterface`
- Review `CreateFromFormatDateParser` and rename to `DateFormatParser`
- Review `TextualDateParser` and rename to `DateParser`
- Move `RegexDateParser::dotNet()` to `DotNetDateParser`
- Remove unused `RegexDateParser`
- Move aforementioned to `Lkrms\Support\Date`

Author: lkrms

src/Concept/Provider.php

@@ -3,9 +3,9 @@
 namespace Lkrms\Concept;
 
 use Lkrms\Contract\IContainer;
-use Lkrms\Contract\IDateFormatter;
 use Lkrms\Contract\IProvider;
 use Lkrms\Exception\MethodNotImplementedException;
+use Lkrms\Support\Date\DateFormatterInterface;
 use Lkrms\Support\ProviderContext;
 
 /**
@@ -17,7 +17,7 @@ abstract class Provider implements IProvider
 {
     protected IContainer $App;
 
-    private IDateFormatter $DateFormatter;
+    private DateFormatterInterface $DateFormatter;
 
     /**
      * Creates a new provider object
@@ -31,10 +31,10 @@ public function __construct(IContainer $app)
      * Get a date formatter to work with the backend's date and time format
      * and/or timezone
      *
-     * The {@see IDateFormatter} returned will be cached for the lifetime of the
-     * {@see Provider} instance.
+     * The {@see DateFormatterInterface} returned will be cached for the
+     * lifetime of the {@see Provider} instance.
      */
-    abstract protected function getDateFormatter(): IDateFormatter;
+    abstract protected function getDateFormatter(): DateFormatterInterface;
 
     /**
      * @inheritDoc
@@ -79,7 +79,7 @@ final public function container(): IContainer
     /**
      * @inheritDoc
      */
-    final public function dateFormatter(): IDateFormatter
+    final public function dateFormatter(): DateFormatterInterface
     {
         return $this->DateFormatter
             ?? ($this->DateFormatter = $this->getDateFormatter());
@@ -89,7 +89,7 @@ final public function dateFormatter(): IDateFormatter
      * Get the date formatter cached by dateFormatter(), or null if it hasn't
      * been cached
      */
-    final protected function getCachedDateFormatter(): ?IDateFormatter
+    final protected function getCachedDateFormatter(): ?DateFormatterInterface
     {
         return $this->DateFormatter ?? null;
     }
@@ -99,7 +99,7 @@ final protected function getCachedDateFormatter(): ?IDateFormatter
      *
      * @return $this
      */
-    final protected function setDateFormatter(?IDateFormatter $formatter)
+    final protected function setDateFormatter(?DateFormatterInterface $formatter)
     {
         if ($formatter === null) {
             unset($this->DateFormatter);

src/Contract/IProvider.php

@@ -3,6 +3,7 @@
 namespace Lkrms\Contract;
 
 use Lkrms\Exception\MethodNotImplementedException;
+use Lkrms\Support\Date\DateFormatterInterface;
 use Stringable;
 
 /**
@@ -64,7 +65,7 @@ public function getBackendIdentifier(): array;
      * Get a date formatter to work with the backend's date and time format
      * and/or timezone
      */
-    public function dateFormatter(): IDateFormatter;
+    public function dateFormatter(): DateFormatterInterface;
 
     /**
      * Throw an exception if the backend isn't reachable

src/Contract/ISerializeRules.php

@@ -2,7 +2,7 @@
 
 namespace Lkrms\Contract;
 
-use Lkrms\Support\DateFormatter;
+use Lkrms\Support\Date\DateFormatter;
 
 /**
  * Instructions for serializing nested entities

src/Curler/Curler.php

@@ -8,7 +8,6 @@
 use Lkrms\Concern\TWritable;
 use Lkrms\Contract\Buildable;
 use Lkrms\Contract\ICollection;
-use Lkrms\Contract\IDateFormatter;
 use Lkrms\Contract\IReadable;
 use Lkrms\Contract\IWritable;
 use Lkrms\Curler\Catalog\CurlerProperty;
@@ -28,7 +27,8 @@
 use Lkrms\Iterator\RecursiveMutableGraphIterator;
 use Lkrms\Store\CacheStore;
 use Lkrms\Support\Catalog\MimeType;
-use Lkrms\Support\DateFormatter;
+use Lkrms\Support\Date\DateFormatter;
+use Lkrms\Support\Date\DateFormatterInterface;
 use Lkrms\Utility\Arr;
 use Lkrms\Utility\Compute;
 use Lkrms\Utility\Convert;
@@ -78,7 +78,7 @@
  * @property bool $ExpectJson Request JSON from upstream?
  * @property bool $PostJson Use JSON to serialize POST/PUT/PATCH/DELETE data?
  * @property bool $PreserveKeys Suppress removal of numeric indices from serialized lists?
- * @property IDateFormatter|null $DateFormatter Specify the date format and timezone used upstream
+ * @property DateFormatterInterface|null $DateFormatter Specify the date format and timezone used upstream
  * @property string|null $UserAgent Override the default User-Agent header
  * @property bool $AlwaysPaginate Pass every response to the pager?
  * @property bool $ObjectAsArray Return deserialized objects as associative arrays?
@@ -359,7 +359,7 @@ final class Curler implements IReadable, IWritable, Buildable
     /**
      * Specify the date format and timezone used upstream
      *
-     * @var IDateFormatter|null
+     * @var DateFormatterInterface|null
      */
     protected $DateFormatter;
 
@@ -465,7 +465,7 @@ public function __construct(
         bool $expectJson = true,
         bool $postJson = true,
         bool $preserveKeys = false,
-        ?IDateFormatter $dateFormatter = null,
+        ?DateFormatterInterface $dateFormatter = null,
         ?string $userAgent = null,
         bool $alwaysPaginate = false,
         bool $objectAsArray = true
@@ -924,7 +924,7 @@ private function getCookieKey(): ?string
             : null;
     }
 
-    private function getDateFormatter(): IDateFormatter
+    private function getDateFormatter(): DateFormatterInterface
     {
         return $this->DateFormatter
             ?: ($this->DateFormatter = new DateFormatter());

src/Curler/CurlerBuilder.php

@@ -1,34 +1,44 @@
 <?php declare(strict_types=1);
 
-namespace Lkrms\Support\DateParser;
+namespace Lkrms\Support\Date;
 
-use Lkrms\Contract\IDateParser;
 use DateTimeImmutable;
 use DateTimeZone;
 
 /**
- * A wrapper around DateTimeImmutable::createFromFormat()
+ * Parses date and time strings with a given format
+ *
+ * @api
  */
-final class CreateFromFormatDateParser implements IDateParser
+final class DateFormatParser implements DateParserInterface
 {
+    private string $Format;
+
     /**
-     * @var string
+     * Creates a new CreateFromFormatDateParser object
+     *
+     * @see DateTimeImmutable::createFromFormat()
      */
-    private $Format;
-
     public function __construct(string $format)
     {
-        // Reset fields that don't appear in the format string to zero,
-        // otherwise they default to the current time
+        // Reset fields that don't appear in the format string to zero-like
+        // values, otherwise they will be set to the current date and time
         if (strpos($format, '!') === false && strpos($format, '|') === false) {
             $format .= '|';
         }
 
         $this->Format = $format;
     }
 
+    /**
+     * @inheritDoc
+     */
     public function parse(string $value, ?DateTimeZone $timezone = null): ?DateTimeImmutable
     {
-        return DateTimeImmutable::createFromFormat($this->Format, $value, $timezone) ?: null;
+        $date = DateTimeImmutable::createFromFormat($this->Format, $value, $timezone);
+        if ($date === false) {
+            return null;
+        }
+        return $date;
     }
 }

src/Support/Date/DateFormatParser.php

@@ -1,83 +1,62 @@
 <?php declare(strict_types=1);
 
-namespace Lkrms\Support;
+namespace Lkrms\Support\Date;
 
-use Lkrms\Concern\TFullyReadable;
-use Lkrms\Contract\IDateFormatter;
-use Lkrms\Contract\IDateParser;
-use Lkrms\Contract\IImmutable;
-use Lkrms\Contract\IReadable;
-use Lkrms\Support\DateParser\CreateFromFormatDateParser;
 use Lkrms\Utility\Date;
 use DateTimeImmutable;
 use DateTimeInterface;
 use DateTimeZone;
 
 /**
- * An immutable date formatter and parser that optionally applies a preferred
- * timezone to both operations
+ * Formats and parses dates, optionally applying a preferred timezone to both
+ * operations
  *
- * @property-read string $Format
- * @property-read DateTimeZone|null $Timezone
- * @property-read IDateParser[] $Parsers
+ * @api
  */
-final class DateFormatter implements IDateFormatter, IImmutable, IReadable
+final class DateFormatter implements DateFormatterInterface
 {
-    use TFullyReadable;
+    private string $Format;
 
-    /**
-     * @var string
-     */
-    protected $Format;
-
-    /**
-     * @var DateTimeZone|null
-     */
-    protected $Timezone;
+    private ?DateTimeZone $Timezone;
 
     /**
-     * @var IDateParser[]
+     * @var DateParserInterface[]
      */
-    protected $Parsers;
+    private array $Parsers;
 
     /**
      * @param DateTimeZone|string|null $timezone
      */
-    public function __construct(string $format = DateTimeInterface::ATOM, $timezone = null, IDateParser ...$parsers)
+    public function __construct(string $format = DateTimeInterface::ATOM, $timezone = null, DateParserInterface ...$parsers)
     {
         $this->Format = $format;
-        $this->Timezone = $timezone === null ? null : Date::timezone($timezone);
-        $this->Parsers = $parsers ?: [new CreateFromFormatDateParser($format)];
+        $this->Timezone = is_string($timezone) ? new DateTimeZone($timezone) : $timezone;
+        $this->Parsers = $parsers ?: [new DateFormatParser($format)];
     }
 
     /**
-     * Format a date after optionally applying the preferred timezone
-     *
-     * If `$date` is a `DateTime` object, {@see DateFormatter::$Timezone} is
-     * set, and `$date->Timezone` has a different value, `$date` is converted to
-     * a `DateTimeImmutable` before applying the timezone. The original
-     * `DateTime` object is not modified.
+     * @inheritDoc
      */
     public function format(DateTimeInterface $date): string
     {
-        if ($this->Timezone &&
-                $this->Timezone->getName() !== $date->getTimezone()->getName()) {
+        if (
+            $this->Timezone &&
+            $this->Timezone->getName() !== $date->getTimezone()->getName()
+        ) {
             $date = Date::immutable($date)->setTimezone($this->Timezone);
         }
 
         return $date->format($this->Format);
     }
 
     /**
-     * Convert a string to a date, if possible
-     *
-     * @return DateTimeImmutable|null a `DateTimeImmutable` object on success or
-     * `null` on failure.
+     * @inheritDoc
      */
     public function parse(string $value): ?DateTimeImmutable
     {
         foreach ($this->Parsers as $parser) {
-            if ($date = $parser->parse($value, $this->Timezone)) {
+            $date = $parser->parse($value, $this->Timezone);
+            if ($date) {
                 return $date;
             }
         }

src/Support/Date/DateFormatter.php

@@ -1,14 +1,14 @@
 <?php declare(strict_types=1);
 
-namespace Lkrms\Contract;
+namespace Lkrms\Support\Date;
 
 use DateTimeImmutable;
 use DateTimeInterface;
 
 /**
- * Formats and parses date and time values
+ * @api
  */
-interface IDateFormatter
+interface DateFormatterInterface
 {
     /**
      * Format a date and time
@@ -17,6 +17,8 @@ public function format(DateTimeInterface $date): string;
 
     /**
      * Convert a string to a date and time, if possible
+     *
+     * Returns `null` if `$value` cannot be parsed.
      */
     public function parse(string $value): ?DateTimeImmutable;
 }

src/Support/Date/DateFormatterInterface.php

@@ -1,18 +1,26 @@
 <?php declare(strict_types=1);
 
-namespace Lkrms\Support\DateParser;
+namespace Lkrms\Support\Date;
 
-use Lkrms\Contract\IDateParser;
 use DateTimeImmutable;
 use DateTimeZone;
 
 /**
- * A wrapper around date_create_immutable()
+ * Parses date and time strings understood by strtotime()
+ *
+ * @api
  */
-final class TextualDateParser implements IDateParser
+final class DateParser implements DateParserInterface
 {
+    /**
+     * @inheritDoc
+     */
     public function parse(string $value, ?DateTimeZone $timezone = null): ?DateTimeImmutable
     {
-        return date_create_immutable($value, $timezone) ?: null;
+        $date = date_create_immutable($value, $timezone);
+        if ($date === false) {
+            return null;
+        }
+        return $date;
     }
 }