Merge branch 'review-date-formatter'

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/IDateParser.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/IProvider.php

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

src/Contract/ISerializeRules.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/Curler.php

@@ -0,0 +1,44 @@
+<?php declare(strict_types=1);
+
+namespace Lkrms\Support\Date;
+
+use DateTimeImmutable;
+use DateTimeZone;
+
+/**
+ * Parses date and time strings with a given format
+ *
+ * @api
+ */
+final class DateFormatParser implements DateParserInterface
+{
+    private string $Format;
+
+    /**
+     * Creates a new CreateFromFormatDateParser object
+     *
+     * @see DateTimeImmutable::createFromFormat()
+     */
+    public function __construct(string $format)
+    {
+        // 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
+    {
+        $date = DateTimeImmutable::createFromFormat($this->Format, $value, $timezone);
+        if ($date === false) {
+            return null;
+        }
+        return $date;
+    }
+}

src/Curler/CurlerBuilder.php

@@ -0,0 +1,66 @@
+<?php declare(strict_types=1);
+
+namespace Lkrms\Support\Date;
+
+use Lkrms\Utility\Date;
+use DateTimeImmutable;
+use DateTimeInterface;
+use DateTimeZone;
+
+/**
+ * Formats and parses dates, optionally applying a preferred timezone to both
+ * operations
+ *
+ * @api
+ */
+final class DateFormatter implements DateFormatterInterface
+{
+    private string $Format;
+
+    private ?DateTimeZone $Timezone;
+
+    /**
+     * @var DateParserInterface[]
+     */
+    private array $Parsers;
+
+    /**
+     * @param DateTimeZone|string|null $timezone
+     */
+    public function __construct(string $format = DateTimeInterface::ATOM, $timezone = null, DateParserInterface ...$parsers)
+    {
+        $this->Format = $format;
+        $this->Timezone = is_string($timezone) ? new DateTimeZone($timezone) : $timezone;
+        $this->Parsers = $parsers ?: [new DateFormatParser($format)];
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function format(DateTimeInterface $date): string
+    {
+        if (
+            $this->Timezone &&
+            $this->Timezone->getName() !== $date->getTimezone()->getName()
+        ) {
+            $date = Date::immutable($date)->setTimezone($this->Timezone);
+        }
+
+        return $date->format($this->Format);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function parse(string $value): ?DateTimeImmutable
+    {
+        foreach ($this->Parsers as $parser) {
+            $date = $parser->parse($value, $this->Timezone);
+            if ($date) {
+                return $date;
+            }
+        }
+
+        return null;
+    }
+}

src/Support/Date/DateFormatParser.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/DateFormatter.php

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