Merge branch 'sync'

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\DateFormatter;
 use Lkrms\Support\ProviderContext;
 use Lkrms\Utility\Env;
 
@@ -20,7 +20,7 @@ abstract class Provider implements IProvider
 
     protected Env $Env;
 
-    private DateFormatter $DateFormatter;
+    private IDateFormatter $DateFormatter;
 
     /**
      * Creates a new provider object
@@ -32,13 +32,13 @@ public function __construct(IContainer $app, Env $env)
     }
 
     /**
-     * Get a DateFormatter to work with the backend's date format and/or
-     * timezone
+     * Get a date formatter to work with the backend's date and time format
+     * and/or timezone
      *
-     * The {@see DateFormatter} returned will be cached for the lifetime of the
+     * The {@see IDateFormatter} returned will be cached for the lifetime of the
      * {@see Provider} instance.
      */
-    abstract protected function getDateFormatter(): DateFormatter;
+    abstract protected function getDateFormatter(): IDateFormatter;
 
     /**
      * @inheritDoc
@@ -99,7 +99,7 @@ final public function env(): Env
     /**
      * @inheritDoc
      */
-    final public function dateFormatter(): DateFormatter
+    final public function dateFormatter(): IDateFormatter
     {
         return $this->DateFormatter
             ?? ($this->DateFormatter = $this->getDateFormatter());

src/Contract/IProvider.php

@@ -3,7 +3,6 @@
 namespace Lkrms\Contract;
 
 use Lkrms\Exception\MethodNotImplementedException;
-use Lkrms\Support\DateFormatter;
 
 /**
  * Services objects on behalf of a backend
@@ -52,9 +51,10 @@ public function getContext(?IContainer $container = null): IProviderContext;
     public function getBackendIdentifier(): array;
 
     /**
-     * Get a DateFormatter to work with the backend's date format and timezone
+     * Get a date formatter to work with the backend's date and time format
+     * and/or timezone
      */
-    public function dateFormatter(): DateFormatter;
+    public function dateFormatter(): IDateFormatter;
 
     /**
      * Throw an exception if the backend isn't reachable

src/Curler/Curler.php

@@ -6,6 +6,7 @@
 use Lkrms\Concern\HasMutator;
 use Lkrms\Concern\TReadable;
 use Lkrms\Concern\TWritable;
+use Lkrms\Contract\IDateFormatter;
 use Lkrms\Contract\IReadable;
 use Lkrms\Contract\IWritable;
 use Lkrms\Contract\ProvidesBuilder;
@@ -67,7 +68,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 DateFormatter|null $DateFormatter Specify the date format and timezone used upstream
+ * @property IDateFormatter|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?
@@ -349,7 +350,7 @@ final class Curler implements IReadable, IWritable, ProvidesBuilder
     /**
      * Specify the date format and timezone used upstream
      *
-     * @var DateFormatter|null
+     * @var IDateFormatter|null
      */
     protected $DateFormatter;
 
@@ -428,7 +429,7 @@ public function __construct(
         bool $expectJson = true,
         bool $postJson = true,
         bool $preserveKeys = false,
-        ?DateFormatter $dateFormatter = null,
+        ?IDateFormatter $dateFormatter = null,
         ?string $userAgent = null,
         bool $alwaysPaginate = false,
         bool $objectAsArray = true
@@ -799,11 +800,14 @@ private function prepareData($data)
                 !($value instanceof CurlerFile ||
                     $value instanceof DateTimeInterface)
         );
-        $leafIterator = new RecursiveIteratorIterator($iterator);
+        $leaves = new RecursiveIteratorIterator($iterator);
+        $iterator = new RecursiveIteratorIterator(
+            $iterator, RecursiveIteratorIterator::SELF_FIRST
+        );
 
         // Does `$data` contain a `CurlerFile`?
         $file = false;
-        foreach ($leafIterator as $value) {
+        foreach ($leaves as $value) {
             if ($value instanceof CurlerFile) {
                 $file = true;
                 break;
@@ -812,21 +816,32 @@ private function prepareData($data)
 
         // With that answered, start over, replacing `CurlerFile` and
         // `DateTimeInterface` instances
-        /** @var RecursiveObjectOrArrayIterator $iterator */
         foreach ($iterator as $value) {
+            $replace = null;
+
             if ($value instanceof CurlerFile) {
-                $value = $value->getCurlFile();
+                $replace = $value->getCurlFile();
             } elseif ($value instanceof DateTimeInterface) {
-                $value = $this->getDateFormatter()->format($value);
-            } elseif ($file) {
-                // And if uploading a file, replace every object that isn't a
-                // CURLFile with an array cURL can encode
-                $iterator->maybeReplaceCurrentWithArray();
+                $replace = $this->getDateFormatter()->format($value);
+            } elseif (!$file) {
                 continue;
-            } else {
+            }
+
+            /** @var RecursiveHasChildrenCallbackIterator<array-key,mixed> */
+            $inner = $iterator->getInnerIterator();
+            /** @var RecursiveObjectOrArrayIterator */
+            $inner = $inner->getInnerIterator();
+
+            if ($replace !== null) {
+                $inner->replace($replace);
                 continue;
             }
-            $iterator->replace($value);
+
+            // If uploading a file, replace every object that isn't a CURLFile
+            // with an array cURL can encode
+            if ($file) {
+                $inner->maybeConvertToArray();
+            }
         }
 
         if ($file) {
@@ -855,7 +870,7 @@ private function getCookieKey(): ?string
             : null;
     }
 
-    private function getDateFormatter(): DateFormatter
+    private function getDateFormatter(): IDateFormatter
     {
         return $this->DateFormatter
             ?: ($this->DateFormatter = new DateFormatter());

src/Curler/CurlerBuilder.php

@@ -3,10 +3,10 @@
 namespace Lkrms\Curler;
 
 use Lkrms\Concept\Builder;
+use Lkrms\Contract\IDateFormatter;
 use Lkrms\Curler\Catalog\CurlerProperty;
 use Lkrms\Curler\Contract\ICurlerHeaders;
 use Lkrms\Curler\Contract\ICurlerPager;
-use Lkrms\Support\DateFormatter;
 
 /**
  * Creates Curler objects via a fluent interface
@@ -32,7 +32,7 @@
  * @method $this expectJson(bool $value = true) Request JSON from upstream? (default: true)
  * @method $this postJson(bool $value = true) Use JSON to serialize POST/PUT/PATCH/DELETE data? (default: true)
  * @method $this preserveKeys(bool $value = true) Suppress removal of numeric indices from serialized lists? (default: false)
- * @method $this dateFormatter(?DateFormatter $value) Specify the date format and timezone used upstream
+ * @method $this dateFormatter(?IDateFormatter $value) Specify the date format and timezone used upstream
  * @method $this userAgent(?string $value) Override the default User-Agent header (see {@see Curler::$UserAgent})
  * @method $this alwaysPaginate(bool $value = true) Pass every response to the pager? (default: false)
  * @method $this objectAsArray(bool $value = true) Return deserialized objects as associative arrays? (default: true)

src/Support/Iterator/ObjectOrArrayIterator.php

@@ -3,17 +3,15 @@
 namespace Lkrms\Support\Iterator;
 
 use Lkrms\Support\Iterator\Contract\MutableIterator;
-use Iterator;
+use LogicException;
 use ReturnTypeWillChange;
-use RuntimeException;
 
 /**
  * Iterates over an object's properties or an array's elements
  *
- * @implements Iterator<array-key,mixed>
  * @implements MutableIterator<array-key,mixed>
  */
-class ObjectOrArrayIterator implements Iterator, MutableIterator
+class ObjectOrArrayIterator implements MutableIterator
 {
     /**
      * @var object|mixed[]
@@ -64,17 +62,15 @@ public function current()
     public function replace($value)
     {
         if (($key = current($this->Keys)) === false) {
-            throw new RuntimeException('Current position is not valid');
+            throw new LogicException('Current position is not valid');
         }
 
         if ($this->IsObject) {
             $this->ObjectOrArray->{$key} = $value;
-
             return $this;
         }
 
         $this->ObjectOrArray[$key] = $value;
-
         return $this;
     }
 
@@ -87,7 +83,6 @@ public function key()
         if (($key = current($this->Keys)) === false) {
             return null;
         }
-
         return $key;
     }
 

src/Support/Iterator/RecursiveHasChildrenCallbackIterator.php

@@ -48,17 +48,24 @@ public function hasChildren(): bool
             return false;
         }
 
-        $key = $this->Iterator->key();
-        $current = $this->Iterator->current();
-
-        return ($this->Callback)($current, $key, $this->Iterator);
+        return ($this->Callback)(
+            $this->Iterator->current(),
+            $this->Iterator->key(),
+            $this->Iterator,
+        );
     }
 
     /**
-     * @return RecursiveIterator<TKey,TValue>|null
+     * @return self<TKey,TValue>|null
      */
-    public function getChildren(): ?RecursiveIterator
+    public function getChildren(): ?self
     {
-        return $this->Iterator->getChildren();
+        /** @var RecursiveIterator<TKey,TValue>|null */
+        $children = $this->Iterator->getChildren();
+
+        return
+            $children === null
+                ? null
+                : new self($children, $this->Callback);
     }
 }

src/Support/Iterator/RecursiveObjectOrArrayIterator.php

@@ -43,13 +43,12 @@ public function getChildren(): ?self
      * If the current element is an object with children, replace it with an
      * array of its properties
      *
-     * @return mixed|false `false` if the current position is invalid, otherwise
-     * the current value.
+     * @return $this
      */
-    public function maybeReplaceCurrentWithArray()
+    public function maybeConvertToArray()
     {
         if (($current = $this->current()) === false) {
-            return false;
+            return $this;
         }
 
         if (is_object($current) && $this->hasChildren()) {
@@ -61,6 +60,6 @@ public function maybeReplaceCurrentWithArray()
             return $this->replace($array);
         }
 
-        return $current;
+        return $this;
     }
 }

src/Sync/Concept/HttpSyncProvider.php

@@ -2,6 +2,7 @@
 
 namespace Lkrms\Sync\Concept;
 
+use Lkrms\Contract\IDateFormatter;
 use Lkrms\Contract\IProvider;
 use Lkrms\Curler\Contract\ICurlerHeaders;
 use Lkrms\Curler\Contract\ICurlerPager;
@@ -35,20 +36,19 @@ final public function getCurler(
         string $path,
         ?int $expiry = -1,
         ?ICurlerHeaders $headers = null,
-        ?ICurlerPager $pager = null
+        ?ICurlerPager $pager = null,
+        ?IDateFormatter $dateFormatter = null
     ): Curler {
         $curlerB = $this->buildCurler(
             CurlerBuilder::build()
                 ->baseUrl($this->getEndpointUrl($path))
         );
 
-        if (!is_null($expiry) && $expiry < 0) {
+        if ($expiry !== null && $expiry < 0) {
             $expiry = $this->getExpiry($path);
         }
-        if (!is_null($expiry)) {
-            $curlerB = $curlerB
-                ->cacheResponse()
-                ->expiry($expiry);
+        if ($expiry !== null) {
+            $curlerB = $curlerB->cacheResponse()->expiry($expiry);
         } else {
             $curlerB = $curlerB->cacheResponse(false);
         }
@@ -65,6 +65,12 @@ final public function getCurler(
             $curlerB = $curlerB->pager($this->getPager($path));
         }
 
+        if ($dateFormatter) {
+            $curlerB = $curlerB->dateFormatter($dateFormatter);
+        } elseif (!$curlerB->issetB('dateFormatter')) {
+            $curlerB = $curlerB->dateFormatter($this->getDateFormatter($path));
+        }
+
         return $curlerB->go();
     }
 
@@ -192,4 +198,9 @@ protected function getExpiry(?string $path): ?int
     {
         return null;
     }
+
+    /**
+     * @inheritDoc
+     */
+    abstract protected function getDateFormatter(?string $path = null): IDateFormatter;
 }