feat(stories): Add published_at_gt and other date related query parameters (#65)

Co-authored-by: Silas Joisten <[email protected]>

Author: frastel

README.md

@@ -309,6 +309,38 @@ new OrFilter(
 );
 ```
 
+#### Filtering by native date fields
+
+The Storyblok API allows filtering by published or updated dates.
+Those fields could not be filtered by `gt_date` or `lt_date` operations and have dedicated parameters in the request.
+
+Supported date parameters are:
+ * `published_at_gt`
+ * `published_at_lt`
+ * `first_published_at_gt`
+ * `first_published_at_lt`
+ * `updated_at_gt`
+ * `updated_at_lt`
+
+Ensure that the dates used have to be in UTC timezone.
+
+```php
+use Storyblok\Api\StoriesApi;
+use Storyblok\Api\StoryblokClient;
+use Storyblok\Api\Domain\Value\QueryParameter\PublishedAtGt;
+use Storyblok\Api\Request\StoriesRequest;
+
+$dateTime = new \DateTimeImmutable('1969-12-28 12:12:12.425', new \DateTimeZone('UTC'));
+
+$client = new StoryblokClient(/* ... */);
+
+$storiesApi = new StoriesApi($client);
+$response = $storiesApi->all(new StoriesRequest(
+    language: 'de',
+    publishedAtGt: new PublishedAtGt($dateTime)
+));
+```
+
 ### Get all available stories by Content Type (`string`)
 
 ```php

src/Domain/Value/QueryParameter/FirstPublishedAtGt.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of storyblok/php-content-api-client.
+ *
+ * (c) Storyblok GmbH <[email protected]>
+ * in cooperation with SensioLabs Deutschland <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Storyblok\Api\Domain\Value\QueryParameter;
+
+/**
+ * @author Frank Stelzer <[email protected]>
+ */
+final readonly class FirstPublishedAtGt
+{
+    public function __construct(
+        private \DateTimeInterface $dateTime
+    ) {
+    }
+
+    public function toString(): string
+    {
+        return $this->dateTime->format('Y-m-d\TH:i:s.v\Z');
+    }
+}

src/Domain/Value/QueryParameter/FirstPublishedAtLt.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of storyblok/php-content-api-client.
+ *
+ * (c) Storyblok GmbH <[email protected]>
+ * in cooperation with SensioLabs Deutschland <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Storyblok\Api\Domain\Value\QueryParameter;
+
+/**
+ * @author Frank Stelzer <[email protected]>
+ */
+final readonly class FirstPublishedAtLt
+{
+    public function __construct(
+        private \DateTimeInterface $dateTime
+    ) {
+    }
+
+    public function toString(): string
+    {
+        return $this->dateTime->format('Y-m-d\TH:i:s.v\Z');
+    }
+}

src/Domain/Value/QueryParameter/PublishedAtGt.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of storyblok/php-content-api-client.
+ *
+ * (c) Storyblok GmbH <[email protected]>
+ * in cooperation with SensioLabs Deutschland <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Storyblok\Api\Domain\Value\QueryParameter;
+
+/**
+ * @author Frank Stelzer <[email protected]>
+ */
+final readonly class PublishedAtGt
+{
+    public function __construct(
+        private \DateTimeInterface $dateTime
+    ) {
+    {
+    }
+
+    public function toString(): string
+    {
+        return $this->dateTime->format('Y-m-d\TH:i:s.v\Z');
+    }
+}

src/Domain/Value/QueryParameter/PublishedAtLt.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of storyblok/php-content-api-client.
+ *
+ * (c) Storyblok GmbH <[email protected]>
+ * in cooperation with SensioLabs Deutschland <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Storyblok\Api\Domain\Value\QueryParameter;
+
+/**
+ * @author Frank Stelzer <[email protected]>
+ */
+final readonly class PublishedAtLt
+{
+    public function __construct(
+        private \DateTimeInterface $dateTime
+    ) {
+    }
+
+    public function toString(): string
+    {
+        return $this->dateTime->format('Y-m-d\TH:i:s.v\Z');
+    }
+}

src/Domain/Value/QueryParameter/UpdatedAtGt.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of storyblok/php-content-api-client.
+ *
+ * (c) Storyblok GmbH <[email protected]>
+ * in cooperation with SensioLabs Deutschland <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Storyblok\Api\Domain\Value\QueryParameter;
+
+/**
+ * @author Frank Stelzer <[email protected]>
+ */
+final readonly class UpdatedAtGt
+{
+    public function __construct(
+        private \DateTimeInterface $dateTime
+    ) {
+    }
+
+    public function toString(): string
+    {
+        return $this->dateTime->format('Y-m-d\TH:i:s.v\Z');
+    }
+}

src/Domain/Value/QueryParameter/UpdatedAtLt.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of storyblok/php-content-api-client.
+ *
+ * (c) Storyblok GmbH <[email protected]>
+ * in cooperation with SensioLabs Deutschland <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Storyblok\Api\Domain\Value\QueryParameter;
+
+/**
+ * @author Frank Stelzer <[email protected]>
+ */
+final readonly class UpdatedAtLt
+{
+    public function __construct(
+        private \DateTimeInterface $dateTime
+    ) {
+    }
+
+    public function toString(): string
+    {
+        return $this->dateTime->format('Y-m-d\TH:i:s.v\Z');
+    }
+}

src/Request/StoriesRequest.php

@@ -20,6 +20,12 @@
 use Storyblok\Api\Domain\Value\Field\FieldCollection;
 use Storyblok\Api\Domain\Value\Filter\FilterCollection;
 use Storyblok\Api\Domain\Value\IdCollection;
+use Storyblok\Api\Domain\Value\QueryParameter\FirstPublishedAtGt;
+use Storyblok\Api\Domain\Value\QueryParameter\FirstPublishedAtLt;
+use Storyblok\Api\Domain\Value\QueryParameter\PublishedAtGt;
+use Storyblok\Api\Domain\Value\QueryParameter\PublishedAtLt;
+use Storyblok\Api\Domain\Value\QueryParameter\UpdatedAtGt;
+use Storyblok\Api\Domain\Value\QueryParameter\UpdatedAtLt;
 use Storyblok\Api\Domain\Value\Resolver\RelationCollection;
 use Storyblok\Api\Domain\Value\Resolver\ResolveLinks;
 use Storyblok\Api\Domain\Value\Slug\Slug;
@@ -49,6 +55,12 @@ public function __construct(
         public ResolveLinks $resolveLinks = new ResolveLinks(),
         public SlugCollection $excludeSlugs = new SlugCollection(),
         public ?Slug $startsWith = null,
+        public ?PublishedAtGt $publishedAtGt = null,
+        public ?PublishedAtLt $publishedAtLt = null,
+        public ?FirstPublishedAtGt $firstPublishedAtGt = null,
+        public ?FirstPublishedAtLt $firstPublishedAtLt = null,
+        public ?UpdatedAtGt $updatedAtGt = null,
+        public ?UpdatedAtLt $updatedAtLt = null,
     ) {
         Assert::stringNotEmpty($language);
         Assert::lessThanEq($this->pagination->perPage, self::MAX_PER_PAGE);
@@ -71,6 +83,12 @@ public function __construct(
      *     version?: string,
      *     excluding_slugs?: string,
      *     starts_with?: string,
+     *     published_at_gt?: string,
+     *     published_at_lt?: string,
+     *     first_published_at_gt?: string,
+     *     first_published_at_lt?: string,
+     *     updated_at_gt?: string,
+     *     updated_at_lt?: string,
      * }
      */
     public function toArray(): array
@@ -126,6 +144,30 @@ public function toArray(): array
             $array['starts_with'] = $this->startsWith->value;
         }
 
+        if (null !== $this->publishedAtGt) {
+            $array['published_at_gt'] = $this->publishedAtGt->toString();
+        }
+
+        if (null !== $this->publishedAtLt) {
+            $array['published_at_lt'] = $this->publishedAtLt->toString();
+        }
+
+        if (null !== $this->firstPublishedAtGt) {
+            $array['first_published_at_gt'] = $this->firstPublishedAtGt->toString();
+        }
+
+        if (null !== $this->firstPublishedAtLt) {
+            $array['first_published_at_lt'] = $this->firstPublishedAtLt->toString();
+        }
+
+        if (null !== $this->updatedAtGt) {
+            $array['updated_at_gt'] = $this->updatedAtGt->toString();
+        }
+
+        if (null !== $this->updatedAtLt) {
+            $array['updated_at_lt'] = $this->updatedAtLt->toString();
+        }
+
         return $array;
     }
 }

tests/Unit/Domain/Type/AssetTest.php

@@ -285,17 +285,6 @@ public function orientation(Orientation $expected, int $width, int $height): voi
         self::assertTrue($expected->equals((new Asset($response))->orientation));
     }
 
-    #[Test]
-    public function orientationWithNoImage(): void
-    {
-        $faker = self::faker();
-        $response = $faker->storyAssetResponse([
-            'filename' => $faker->url(),
-        ]);
-
-        self::assertTrue(Orientation::Unknown->equals((new Asset($response))->orientation));
-    }
-
     /**
      * @return iterable<string, array{0: Orientation, 1: int, 2: int}>
      */
@@ -309,6 +298,17 @@ public static function orientationProvider(): iterable
         yield 'portrait' => [Orientation::Portrait, 1080, 1920];
     }
 
+    #[Test]
+    public function orientationWithNoImage(): void
+    {
+        $faker = self::faker();
+        $response = $faker->storyAssetResponse([
+            'filename' => $faker->url(),
+        ]);
+
+        self::assertTrue(Orientation::Unknown->equals((new Asset($response))->orientation));
+    }
+
     #[Test]
     public function isExternalUrl(): void
     {

tests/Unit/Domain/Value/QueryParameter/FirstPublishedAtGtTest.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of storyblok/php-content-api-client.
+ *
+ * (c) Storyblok GmbH <[email protected]>
+ * in cooperation with SensioLabs Deutschland <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Storyblok\Api\Tests\Unit\Domain\Value\QueryParameter;
+
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use Storyblok\Api\Domain\Value\QueryParameter\FirstPublishedAtGt;
+use Storyblok\Api\Tests\Util\FakerTrait;
+
+/**
+ * @author Frank Stelzer <[email protected]>
+ */
+class FirstPublishedAtGtTest extends TestCase
+{
+    use FakerTrait;
+
+    #[Test]
+    public function valueToString(): void
+    {
+        $value = self::faker()->dateTime();
+        $expectedValue = $value->format('Y-m-d\TH:i:s.v\Z');
+
+        $valueObject = new FirstPublishedAtGt($value);
+        self::assertSame($expectedValue, $valueObject->toString());
+    }
+}