fix: support Notion icon object payload deserialization

src/Resource/File/Icon.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Brd6\NotionSdkPhp\Resource\File;
+
+use Brd6\NotionSdkPhp\Resource\Property\IconProperty;
+
+class Icon extends AbstractFile
+{
+    public const FILE_TYPE = 'icon';
+
+    protected ?IconProperty $icon = null;
+
+    public static function getFileType(): string
+    {
+        return self::FILE_TYPE;
+    }
+
+    protected function initialize(): void
+    {
+        $data = (array) $this->getRawData()[$this->getType()];
+        $this->icon = IconProperty::fromRawData($data);
+    }
+
+    public function getIcon(): ?IconProperty
+    {
+        return $this->icon;
+    }
+
+    public function setIcon(IconProperty $icon): self
+    {
+        $this->icon = $icon;
+
+        return $this;
+    }
+}

src/Resource/Property/IconProperty.php

@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Brd6\NotionSdkPhp\Resource\Property;
+
+use function rawurlencode;
+
+class IconProperty extends AbstractProperty
+{
+    private const NOTION_ICONS_BASE_URL = 'https://www.notion.so/icons';
+
+    protected string $name = '';
+    protected string $color = '';
+
+    public static function fromRawData(array $rawData): self
+    {
+        $property = new self();
+
+        $property->name = (string) ($rawData['name'] ?? '');
+        $property->color = (string) ($rawData['color'] ?? '');
+
+        return $property;
+    }
+
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
+    public function setName(string $name): self
+    {
+        $this->name = $name;
+
+        return $this;
+    }
+
+    public function getColor(): string
+    {
+        return $this->color;
+    }
+
+    public function setColor(string $color): self
+    {
+        $this->color = $color;
+
+        return $this;
+    }
+
+    public function getUrl(string $mode = 'light'): string
+    {
+        if ($this->name === '' || $this->color === '') {
+            return '';
+        }
+
+        $mode = $mode === 'dark' ? 'dark' : 'light';
+
+        return self::NOTION_ICONS_BASE_URL
+            . '/'
+            . rawurlencode($this->name)
+            . '_'
+            . rawurlencode($this->color)
+            . '.svg?mode='
+            . $mode;
+    }
+}

tests/Endpoint/DatabasesEndpointTest.php

@@ -21,7 +21,10 @@
 use Brd6\NotionSdkPhp\Resource\Database\PropertyObject\SelectPropertyObject;
 use Brd6\NotionSdkPhp\Resource\Database\PropertyObject\TitlePropertyObject;
 use Brd6\NotionSdkPhp\Resource\File\Emoji;
+use Brd6\NotionSdkPhp\Resource\File\Icon;
+use Brd6\NotionSdkPhp\Resource\Page;
 use Brd6\NotionSdkPhp\Resource\Page\Parent\PageIdParent;
+use Brd6\NotionSdkPhp\Resource\Pagination\PageOrDatabaseResults;
 use Brd6\NotionSdkPhp\Resource\Pagination\PageResults;
 use Brd6\NotionSdkPhp\Resource\Pagination\PaginationRequest;
 use Brd6\NotionSdkPhp\Resource\Property\SelectProperty;
@@ -81,6 +84,45 @@ public function testQueryDatabase(): void
         $this->assertNotEmpty($resultPage->getId());
     }
 
+    public function testQueryDatabaseWithIconObject(): void
+    {
+        $httpClient = new MockHttpClient(function (string $method, string $url, array $options) {
+            $this->assertEquals('POST', $method);
+            $this->assertStringContainsString('databases/21d89ea8-2c3c-8062-a6a2-f83f68500122/query', $url);
+
+            return new MockResponseFactory(
+                (string) file_get_contents('tests/Fixtures/client_databases_query_page_with_icon_object_200.json'),
+                [
+                    'http_code' => 200,
+                ],
+            );
+        });
+
+        $options = (new ClientOptions())
+            ->setAuth('secret_valid-auth')
+            ->setHttpClient($httpClient);
+
+        $client = new Client($options);
+
+        /** @var PageOrDatabaseResults $paginationResponse */
+        $paginationResponse = $client->databases()->query('21d89ea8-2c3c-8062-a6a2-f83f68500122');
+
+        $this->assertNotNull($paginationResponse);
+        $this->assertInstanceOf(PageOrDatabaseResults::class, $paginationResponse);
+        $this->assertGreaterThan(0, count($paginationResponse->getResults()));
+
+        /** @var Page $resultPage */
+        $resultPage = $paginationResponse->getResults()[0];
+        $icon = $resultPage->getIcon();
+
+        $this->assertNotNull($icon);
+        $this->assertInstanceOf(Icon::class, $icon);
+        $this->assertSame('icon', $icon->getType());
+        $this->assertNotNull($icon->getIcon());
+        $this->assertSame('book', $icon->getIcon()->getName());
+        $this->assertSame('gray', $icon->getIcon()->getColor());
+    }
+
     public function testQueryDatabaseWithPagination(): void
     {
         $httpClient = new MockHttpClient(function (string $method, string $url, array $options) {

tests/Fixtures/client_databases_query_page_with_icon_object_200.json

@@ -0,0 +1,38 @@
+{
+    "object": "list",
+    "results": [
+        {
+            "object": "page",
+            "id": "21d89ea8-2c3c-8024-850c-e90d903807c3",
+            "created_time": "2025-06-25T09:45:00.000Z",
+            "last_edited_time": "2025-06-25T09:45:00.000Z",
+            "created_by": {
+                "object": "user",
+                "id": "7f03dda0-a132-49d7-b8b2-29c9ed1b1f0e"
+            },
+            "last_edited_by": {
+                "object": "user",
+                "id": "7f03dda0-a132-49d7-b8b2-29c9ed1b1f0e"
+            },
+            "cover": null,
+            "icon": {
+                "type": "icon",
+                "icon": {
+                    "name": "book",
+                    "color": "gray"
+                }
+            },
+            "parent": {
+                "type": "database_id",
+                "database_id": "21d89ea8-2c3c-8062-a6a2-f83f68500122"
+            },
+            "archived": false,
+            "properties": {},
+            "url": "https://www.notion.so/Overcoming-Work-Obstacles-21d89ea82c3c8024850ce90d903807c3"
+        }
+    ],
+    "next_cursor": null,
+    "has_more": false,
+    "type": "page_or_database",
+    "page_or_database": {}
+}

tests/Resource/DataSourceTest.php

@@ -7,6 +7,7 @@
 use Brd6\NotionSdkPhp\Exception\InvalidResourceException;
 use Brd6\NotionSdkPhp\Resource\DataSource;
 use Brd6\NotionSdkPhp\Resource\Database\PropertyObject\RelationPropertyObject;
+use Brd6\NotionSdkPhp\Resource\File\Icon;
 use Brd6\NotionSdkPhp\Resource\Page\Parent\DatabaseIdParent;
 use Brd6\NotionSdkPhp\Resource\Page\Parent\PageIdParent;
 use PHPUnit\Framework\TestCase;
@@ -52,4 +53,32 @@ public function testDataSource(): void
         );
         $this->assertNotEmpty($dataSource->toArray());
     }
+
+    public function testDataSourceWithIconObject(): void
+    {
+        /** @var array $rawData */
+        $rawData = (array) json_decode(
+            (string) file_get_contents('tests/Fixtures/client_data_sources_retrieve_200.json'),
+            true,
+        );
+
+        $rawData['icon'] = [
+            'type' => 'icon',
+            'icon' => [
+                'name' => 'book',
+                'color' => 'gray',
+            ],
+        ];
+
+        /** @var DataSource $dataSource */
+        $dataSource = DataSource::fromRawData($rawData);
+
+        $icon = $dataSource->getIcon();
+        $this->assertNotNull($icon);
+        $this->assertInstanceOf(Icon::class, $icon);
+        $this->assertSame('icon', $icon->getType());
+        $this->assertNotNull($icon->getIcon());
+        $this->assertSame('book', $icon->getIcon()->getName());
+        $this->assertSame('gray', $icon->getIcon()->getColor());
+    }
 }

tests/Resource/DatabaseTest.php

@@ -9,6 +9,7 @@
 use Brd6\NotionSdkPhp\Resource\Database\PartialDataSource;
 use Brd6\NotionSdkPhp\Resource\File\Emoji;
 use Brd6\NotionSdkPhp\Resource\File\External;
+use Brd6\NotionSdkPhp\Resource\File\Icon;
 use PHPUnit\Framework\TestCase;
 
 use function array_filter;
@@ -119,4 +120,32 @@ public function testDatabaseWithDataSources(): void
         $this->assertNotEmpty($database->getDataSources()[0]->getId());
         $this->assertNotEmpty($database->getDataSources()[0]->getName());
     }
+
+    public function testDatabaseWithIconObject(): void
+    {
+        /** @var array $rawData */
+        $rawData = (array) json_decode(
+            (string) file_get_contents('tests/Fixtures/client_databases_retrieve_database_200.json'),
+            true,
+        );
+
+        $rawData['icon'] = [
+            'type' => 'icon',
+            'icon' => [
+                'name' => 'book',
+                'color' => 'gray',
+            ],
+        ];
+
+        /** @var Database $database */
+        $database = Database::fromRawData($rawData);
+
+        $icon = $database->getIcon();
+        $this->assertNotNull($icon);
+        $this->assertInstanceOf(Icon::class, $icon);
+        $this->assertSame('icon', $icon->getType());
+        $this->assertNotNull($icon->getIcon());
+        $this->assertSame('book', $icon->getIcon()->getName());
+        $this->assertSame('gray', $icon->getIcon()->getColor());
+    }
 }

tests/Resource/File/IconTest.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Brd6\Test\NotionSdkPhp\Resource\File;
+
+use Brd6\NotionSdkPhp\Resource\File\AbstractFile;
+use Brd6\NotionSdkPhp\Resource\File\Icon;
+use Brd6\Test\NotionSdkPhp\TestCase;
+
+class IconTest extends TestCase
+{
+    public function testFromRawData(): void
+    {
+        $file = AbstractFile::fromRawData([
+            'type' => 'icon',
+            'icon' => [
+                'name' => 'add',
+                'color' => 'blue',
+            ],
+        ]);
+
+        $this->assertInstanceOf(Icon::class, $file);
+        $this->assertSame('icon', $file->getType());
+        $this->assertNotNull($file->getIcon());
+        $this->assertSame('add', $file->getIcon()->getName());
+        $this->assertSame('blue', $file->getIcon()->getColor());
+    }
+
+    public function testToArrayRoundTrip(): void
+    {
+        $rawData = [
+            'type' => 'icon',
+            'icon' => [
+                'name' => 'book',
+                'color' => 'gray',
+            ],
+        ];
+
+        $file = AbstractFile::fromRawData($rawData);
+
+        $this->assertEquals($rawData, $file->toArray());
+    }
+}

tests/Resource/PageTest.php

@@ -7,6 +7,7 @@
 use Brd6\NotionSdkPhp\Exception\InvalidResourceException;
 use Brd6\NotionSdkPhp\Resource\File\Emoji;
 use Brd6\NotionSdkPhp\Resource\File\External;
+use Brd6\NotionSdkPhp\Resource\File\Icon;
 use Brd6\NotionSdkPhp\Resource\Page;
 use Brd6\NotionSdkPhp\Resource\Page\PropertyValue\NumberPropertyValue;
 use PHPUnit\Framework\TestCase;
@@ -70,6 +71,34 @@ public function testPageWithPageObject(): void
         $this->assertNotEmpty($external->getUrl());
     }
 
+    public function testPageWithIconObject(): void
+    {
+        /** @var array $rawData */
+        $rawData = (array) json_decode(
+            (string) file_get_contents('tests/Fixtures/client_request_retrieve_page_200.json'),
+            true,
+        );
+
+        $rawData['icon'] = [
+            'type' => 'icon',
+            'icon' => [
+                'name' => 'book',
+                'color' => 'gray',
+            ],
+        ];
+
+        /** @var Page $page */
+        $page = Page::fromRawData($rawData);
+
+        $icon = $page->getIcon();
+        $this->assertNotNull($icon);
+        $this->assertInstanceOf(Icon::class, $icon);
+        $this->assertSame('icon', $icon->getType());
+        $this->assertNotNull($icon->getIcon());
+        $this->assertSame('book', $icon->getIcon()->getName());
+        $this->assertSame('gray', $icon->getIcon()->getColor());
+    }
+
     public function testPageProperties(): void
     {
         /** @var Page $page */