feat: add PropertyMetadata description (#365)

composer.json

@@ -3,7 +3,7 @@
     "description": "A complete Notion SDK for PHP developers.",
     "type": "library",
     "license": "MIT",
-    "homepage": "https:/mariosimao.github.io/notion-sdk-php",
+    "homepage": "https://mariosimao.github.io/notion-sdk-php",
     "autoload": {
         "psr-4": {
             "Notion\\": "src/"

src/Databases/Properties/Checkbox.php

@@ -8,6 +8,7 @@
  *      name: string,
  *      type: "checkbox",
  *      checkbox: array<empty, empty>,
+ *      description?: string,
  * }
  *
  * @psalm-immutable

src/Databases/Properties/CreatedBy.php

@@ -8,6 +8,7 @@
  *      name: string,
  *      type: "created_by",
  *      created_by: array<empty, empty>,
+ *      description?: string,
  * }
  *
  * @psalm-immutable

src/Databases/Properties/CreatedTime.php

@@ -8,6 +8,7 @@
  *      name: string,
  *      type: "created_time",
  *      created_time: array<empty, empty>,
+ *      description?: string,
  * }
  *
  * @psalm-immutable

src/Databases/Properties/Date.php

@@ -8,6 +8,7 @@
  *      name: string,
  *      type: "date",
  *      date: array<empty, empty>,
+ *      description?: string,
  * }
  *
  * @psalm-immutable

src/Databases/Properties/Email.php

@@ -8,6 +8,7 @@
  *      name: string,
  *      type: "email",
  *      email: array<empty, empty>,
+ *      description?: string,
  * }
  *
  * @psalm-immutable

src/Databases/Properties/Files.php

@@ -8,6 +8,7 @@
  *      name: string,
  *      type: "files",
  *      file: array<empty, empty>,
+ *      description?: string,
  * }
  *
  * @psalm-immutable

src/Databases/Properties/Formula.php

@@ -8,6 +8,7 @@
  *      name: string,
  *      type: "formula",
  *      formula: array{ expression: string },
+ *      description?: string,
  * }
  *
  * @psalm-immutable

src/Databases/Properties/LastEditedBy.php

@@ -8,6 +8,7 @@
  *      name: string,
  *      type: "last_edited_by",
  *      last_edited_by: array<empty, empty>,
+ *      description?: string,
  * }
  *
  * @psalm-immutable

src/Databases/Properties/LastEditedTime.php

@@ -8,6 +8,7 @@
  *      name: string,
  *      type: "last_edited_time",
  *      last_edited_time: array<empty, empty>,
+ *      description?: string,
  * }
  *
  * @psalm-immutable

src/Databases/Properties/MultiSelect.php

@@ -12,6 +12,7 @@
  *      multi_select: array{
  *          options: list<SelectOptionJson>
  *      },
+ *      description?: string,
  * }
  *
  * @psalm-immutable

src/Databases/Properties/Number.php

@@ -8,6 +8,7 @@
  *      name: string,
  *      type: "number",
  *      number: array{ format: string },
+ *      description?: string,
  * }
  *
  * @psalm-immutable

src/Databases/Properties/People.php

@@ -8,6 +8,7 @@
  *      name: string,
  *      type: "people",
  *      people: array<empty, empty>,
+ *      description?: string,
  * }
  *
  * @psalm-immutable

src/Databases/Properties/PhoneNumber.php

@@ -8,6 +8,7 @@
  *      name: string,
  *      type: "phone_number",
  *      phone_number: array<empty, empty>,
+ *      description?: string,
  * }
  *
  * @psalm-immutable

src/Databases/Properties/PropertyMetadata.php

@@ -3,7 +3,7 @@
 namespace Notion\Databases\Properties;
 
 /**
- * @psalm-type PropertyMetadataJson = array{ id: string, name: string, type: string, ... }
+ * @psalm-type PropertyMetadataJson = array{ id: string, name: string, type: string, description?: string, ... }
  *
  * @psalm-immutable
  */
@@ -14,12 +14,13 @@ private function __construct(
         public readonly string $name,
         public readonly PropertyType $type,
         private readonly string|null $unknownType = null,
+        public readonly string|null $description = null,
     ) {
     }
 
-    public static function create(string $id, string $name, PropertyType $type): self
+    public static function create(string $id, string $name, PropertyType $type, ?string $description = null): self
     {
-        return new self($id, $name, $type);
+        return new self($id, $name, $type, description: $description);
     }
 
     /**
@@ -36,6 +37,7 @@ public static function fromArray(array $array): self
             $array["name"],
             $type,
             $type === PropertyType::Unknown ? $array["type"] : null,
+            $array["description"] ?? null,
         );
     }
 
@@ -47,6 +49,9 @@ public function toArray(): array
             "id"   => $this->id,
             "name" => $this->name,
             "type" => $type,
+            ...($this->description !== null ? [
+                "description" => $this->description,
+            ] : []),
         ];
     }
 }

src/Databases/Properties/Relation.php

@@ -17,7 +17,8 @@
  *              synced_property_name: string,
  *              synced_property_id: string
  *          }
- *      }
+ *      },
+ *      description?: string,
  * }
  *
  * @psalm-immutable

src/Databases/Properties/RichTextProperty.php

@@ -8,6 +8,7 @@
  *      name: string,
  *      type: "rich_text",
  *      rich_text: array<empty, empty>,
+ *      description?: string,
  * }
  *
  * @psalm-immutable

src/Databases/Properties/Select.php

@@ -12,6 +12,7 @@
  *      select: array{
  *          options: list<SelectOptionJson>
  *      },
+ *      description?: string,
  * }
  *
  * @psalm-immutable

src/Databases/Properties/SelectOption.php

@@ -8,7 +8,8 @@
  * @psalm-type SelectOptionJson = array{
  *      id?: string,
  *      name?: string,
- *      color?: string
+ *      color?: string,
+ *      description?: string,
  * }
  *
  * @psalm-immutable

src/Databases/Properties/Status.php

@@ -14,6 +14,7 @@
  *          options: StatusOptionJson[],
  *          groups: StatusGroupJson[]
  *      },
+ *      description?: string,
  * }
  *
  * @psalm-immutable

src/Databases/Properties/StatusGroup.php

@@ -9,7 +9,8 @@
  *      id?: string,
  *      name?: string,
  *      color: string,
- *      option_ids: string[]
+ *      option_ids: string[],
+ *      description?: string,
  * }
  *
  * @psalm-immutable

src/Databases/Properties/StatusOption.php

@@ -8,7 +8,8 @@
  * @psalm-type StatusOptionJson = array{
  *      id?: string,
  *      name?: string,
- *      color?: string
+ *      color?: string,
+ *      description?: string,
  * }
  *
  * @psalm-immutable

src/Databases/Properties/Title.php

@@ -8,6 +8,7 @@
  *      name: string,
  *      type: "title",
  *      title: array<empty, empty>,
+ *      description?: string,
  * }
  *
  * @psalm-immutable

src/Databases/Properties/UniqueId.php

@@ -8,6 +8,7 @@
  *      name: string,
  *      type: "uniqueId",
  *      unique_id: \stdClass,
+ *      description?: string,
  * }
  *
  * @psalm-immutable

src/Databases/Properties/Unknown.php

@@ -6,7 +6,8 @@
  * @psalm-type PropertyJson = array{
  *      id: string,
  *      name: string,
- *      type: string
+ *      type: string,
+ *      description?: string,
  * }
  *
  * @psalm-immutable

src/Databases/Properties/Url.php

@@ -8,6 +8,7 @@
  *      name: string,
  *      type: "url",
  *      url: array<empty, empty>,
+ *      description?: string,
  * }
  *
  * @psalm-immutable

tests/Unit/Databases/Properties/CreatedByTest.php

@@ -24,6 +24,7 @@ public function test_array_conversion(): void
             "name"  => "dummy",
             "type"  => "created_by",
             "created_by" => new \stdClass(),
+            "description" => "foo bar",
         ];
         $createdBy = CreatedBy::fromArray($array);
         $fromFactory = PropertyFactory::fromArray($array);

tests/Unit/Databases/Properties/PropertyMetadataTest.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace Notion\Test\Unit\Databases\Properties;
+
+use Notion\Databases\Properties\PropertyMetadata;
+use Notion\Databases\Properties\PropertyType;
+use PHPUnit\Framework\TestCase;
+
+class PropertyMetadataTest extends TestCase
+{
+    public function test_create(): void
+    {
+        $metadata = PropertyMetadata::create("abc", "Dummy prop name", PropertyType::CreatedBy, "foo bar");
+
+        $this->assertEquals("abc", $metadata->id);
+        $this->assertEquals("Dummy prop name", $metadata->name);
+        $this->assertEquals(PropertyType::CreatedBy, $metadata->type);
+        $this->assertEquals("foo bar", $metadata->description);
+    }
+
+    public function test_from_array(): void
+    {
+        $array = [
+            "id"    => "abc",
+            "name"  => "dummy",
+            "type"  => "created_by",
+            "created_by" => new \stdClass(),
+            "description" => "foo bar",
+        ];
+        $metadata = PropertyMetadata::fromArray($array);
+
+        $this->assertEquals($array["id"], $metadata->id);
+        $this->assertEquals($array["name"], $metadata->name);
+        $this->assertEquals(PropertyType::CreatedBy, $metadata->type);
+        $this->assertEquals($array["description"], $metadata->description);
+
+        $toArray = $metadata->toArray();
+
+        $this->assertEqualsCanonicalizing(['id', 'name', 'type', 'description'], array_keys($toArray));
+    }
+
+    public function test_from_array_without_description(): void
+    {
+        $array = [
+            "id"    => "abc",
+            "name"  => "dummy",
+            "type"  => "created_by",
+            "created_by" => new \stdClass(),
+        ];
+
+        $metadata = PropertyMetadata::fromArray($array);
+
+        $this->assertEquals($array["id"], $metadata->id);
+        $this->assertEquals($array["name"], $metadata->name);
+        $this->assertEquals(PropertyType::CreatedBy, $metadata->type);
+        $this->assertNull($metadata->description);
+
+        $toArray = $metadata->toArray();
+
+        // When there is no description, its key won't show up
+        $this->assertEqualsCanonicalizing(['id', 'name', 'type'], array_keys($toArray));
+    }
+}