Merge pull request #73 from mariosimao/release-0.4.0

Release 0.4.0

CHANGELOG.md

@@ -3,9 +3,21 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
 ## [Unreleased]
 
+## [0.4.0] - 2022-03-24
+
 ### Added
+- How to documentation for pages
+- Find block (!58)
+- Update block (!59)
+- Append blocks (!60)
+- Delete block (!61)
+
+## Changed
+- Notion version to `2022-02-22` (!69)
+
 ## [0.3.0] - 2021-12-04
 
 ### Added
@@ -109,4 +121,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [Unreleased]: https://github.com/mariosimao/notion-sdk-php/compare/v0.1.0...HEAD
 [0.1.0]: https://github.com/mariosimao/notion-sdk-php/releases/tag/v0.1.0
 [0.2.0]: https://github.com/mariosimao/notion-sdk-php/releases/tag/v0.2.0
-[0.3.0]: https://github.com/mariosimao/notion-sdk-php/releases/tag/v0.3.0
+[0.3.0]: https://github.com/mariosimao/notion-sdk-php/releases/tag/v0.3.0
+[0.4.0]: https://github.com/mariosimao/notion-sdk-php/releases/tag/v0.4.0

README.md

@@ -1,6 +1,6 @@
 [![Codecov](https://img.shields.io/codecov/c/github/mariosimao/notion-sdk)](https://app.codecov.io/gh/mariosimao/notion-sdk)
 [![Type coverage](https://shepherd.dev/github/mariosimao/notion-sdk/coverage.svg)](https://shepherd.dev/github/mariosimao/notion-sdk)
-[![Notion API version](https://img.shields.io/badge/API%20Version-2021--08--16-blue)](https://developers.notion.com/reference/versioning)
+[![Notion API version](https://img.shields.io/badge/API%20Version-2022--02--22-blue)](https://developers.notion.com/reference/versioning)
 
 # notion-sdk-php
 
@@ -22,19 +22,22 @@ A simple example on how to create a page with some content:
 <?php
 
 use Notion\Notion;
+use Notion\Common\Emoji;
 use Notion\Blocks\Paragraph;
 use Notion\Pages\Page;
 use Notion\Pages\PageParent;
 
-$token = getenv("NOTION_TOKEN");
+$token = $_ENV["NOTION_TOKEN"];
 $notion = Notion::create($token);
 
 $parent = PageParent::page("c986d7b0-7051-4f18-b165-cc0b9503ffc2");
 $page = Page::create($parent)
             ->withTitle("Sample page")
-            ->withIcon("⭐");
+            ->withIcon(Emoji::create("⭐"));
 
-$content = Paragraph::fromString("This is a simple paragraph.");
+$content = [
+    Paragraph::fromString("This is a simple paragraph."),
+];
 
 $notion->pages()->create($page, $content);
 ```

docs/README.md

@@ -1,5 +1,11 @@
 # Documentation
 
+## How to
+- [Create a page](./how-to/create-a-page.md)
+- [Find a page](./how-to/find-a-page.md)
+- [Update a page](./how-to/update-a-page.md)
+- [Delete a page](./how-to/delete-a-page.md)
+
 ## Blocks
 
 - [Bookmark](./blocks/Bookmark.md)

docs/how-to/add-content-to-page.md

@@ -0,0 +1,21 @@
+# Add content to page
+
+```php
+<?php
+
+use Notion\Blocks\Paragraph;
+use Notion\Notion;
+
+$token = $_ENV["NOTION_SECRET"];
+
+$notion = Notion::create($token);
+
+$pageId = "c986d7b0-7051-4f18-b165-cc0b9503ffc2";
+
+$content = [
+    Paragraph::fromString("This paragraph will be appended."),
+    Paragraph::fromString("This other paragraph too!"),
+];
+
+$notion->blocks()->append($pageId, $content);
+```

docs/how-to/create-a-page.md

@@ -0,0 +1,57 @@
+# Create a page
+
+## Empty page
+
+```php
+<?php
+
+use Notion\Notion;
+use Notion\Common\Emoji;
+use Notion\Pages\Page;
+use Notion\Pages\PageParent;
+
+$token = $_ENV["NOTION_SECRET"];
+
+$notion = Notion::create($token);
+
+$parent = PageParent::page("c986d7b0-7051-4f18-b165-cc0b9503ffc2");
+$page = Page::create($parent)
+            ->withTitle("Empty page")
+            ->withIcon(Emoji::create("⭐"));
+
+$page = $notion->pages()->create($page);
+```
+
+## Page with content
+
+```php
+<?php
+
+use Notion\Blocks\Heading1;
+use Notion\Notion;
+use Notion\Blocks\ToDo;
+use Notion\Common\Emoji;
+use Notion\Pages\Page;
+use Notion\Pages\PageParent;
+
+$token = $_ENV["NOTION_SECRET"];
+
+$notion = Notion::create($token);
+
+$parent = PageParent::page("c986d7b0-7051-4f18-b165-cc0b9503ffc2");
+$page = Page::create($parent)
+            ->withTitle("Shopping list")
+            ->withIcon(Emoji::create("🛒"));
+
+$content = [
+    Heading1::fromString("Supermarket"),
+    ToDo::fromString("Tomato"),
+    ToDo::fromString("Sugar"),
+    ToDo::fromString("Apple"),
+    ToDo::fromString("Milk"),
+    Heading1::fromString("Mall"),
+    ToDo::fromString("Black T-shirt"),
+];
+
+$page = $notion->pages()->create($page, $content);
+```

docs/how-to/delete-a-page.md

@@ -0,0 +1,19 @@
+# Delete a page
+
+Deleted pages are archived. It is possible to recover archived pages.
+
+```php
+<?php
+
+use Notion\Notion;
+
+$token = $_ENV["NOTION_SECRET"];
+
+$notion = Notion::create($token);
+
+$pageId = "c986d7b0-7051-4f18-b165-cc0b9503ffc2";
+$page = $notion->pages()->find($pageId);
+$page = $notion->pages()->delete($page);
+
+$page->archived(); // true
+```

docs/how-to/find-a-page.md

@@ -0,0 +1,18 @@
+# Find a page
+
+It is possible to retrieve a page by knowing its ID.
+
+```php
+<?php
+
+use Notion\Notion;
+
+$token = $_ENV["NOTION_SECRET"];
+
+$notion = Notion::create($token);
+
+$pageId = "c986d7b0-7051-4f18-b165-cc0b9503ffc2";
+$page = $notion->pages()->find($pageId);
+
+echo $page->title()->toString();
+```

docs/how-to/update-a-page.md

@@ -0,0 +1,19 @@
+# Update a page
+
+```php
+<?php
+
+use Notion\Notion;
+use Notion\Common\Emoji;
+
+$token = $_ENV["NOTION_SECRET"];
+
+$notion = Notion::create($token);
+
+$pageId = "c986d7b0-7051-4f18-b165-cc0b9503ffc2";
+$page = $notion->pages()->find($pageId);
+$page = $page->withTitle("New title")
+             ->withIcon(Emoji::create(🚲));
+
+$notion->pages()->update($page);
+```

src/Blocks/Block.php

@@ -111,6 +111,18 @@ public function toArray(): array
         return $array;
     }
 
+    public function archive(): self
+    {
+        return new self(
+            $this->id,
+            $this->createdTime,
+            $this->lastEditedTime,
+            true,
+            $this->hasChildren,
+            $this->type,
+        );
+    }
+
     public function withHasChildren(bool $hasChildren): self
     {
         return new self(

src/Blocks/BlockInterface.php

@@ -7,8 +7,10 @@ interface BlockInterface
 {
     public static function fromArray(array $array): self;
     public function toArray(): array;
+    public function toUpdateArray(): array;
 
     public function block(): Block;
     /** @param list<BlockInterface> $children */
     public function changeChildren(array $children): self;
+    public function archive(): self;
 }

src/Blocks/Bookmark.php

@@ -81,6 +81,18 @@ public function toArray(): array
         return $array;
     }
 
+    /** @internal */
+    public function toUpdateArray(): array
+    {
+        return [
+            self::TYPE => [
+                "url" => $this->url,
+                "caption" => array_map(fn(RichText $t) => $t->toArray(), $this->caption),
+            ],
+            "archived" => $this->block()->archived(),
+        ];
+    }
+
     /** Get block common object */
     public function block(): Block
     {
@@ -128,4 +140,13 @@ public function changeChildren(array $children): self
             "no_children_support",
         );
     }
+
+    public function archive(): BlockInterface
+    {
+        return new self(
+            $this->block->archive(),
+            $this->url,
+            $this->caption,
+        );
+    }
 }

src/Blocks/Breadcrumb.php

@@ -53,6 +53,15 @@ public function toArray(): array
         return $array;
     }
 
+    /** @internal */
+    public function toUpdateArray(): array
+    {
+        return [
+            self::TYPE => [],
+            "archived" => $this->block()->archived(),
+        ];
+    }
+
     public function block(): Block
     {
         return $this->block;
@@ -65,4 +74,9 @@ public function changeChildren(array $children): self
             "no_children_support",
         );
     }
+
+    public function archive(): BlockInterface
+    {
+        return new self($this->block->archive());
+    }
 }

src/Blocks/BulletedListItem.php

@@ -13,7 +13,7 @@
  *
  * @psalm-type BulletedListItemJson = array{
  *      bulleted_list_item: array{
- *          text: list<RichTextJson>,
+ *          rich_text: list<RichTextJson>,
  *          children?: list<BlockJson>,
  *      },
  * }
@@ -27,7 +27,6 @@ class BulletedListItem implements BlockInterface
     private Block $block;
 
     /** @var list<RichText> */
-
     private array $text;
 
     /** @var list<\Notion\Blocks\BlockInterface> */
@@ -81,7 +80,7 @@ public static function fromArray(array $array): self
         /** @psalm-var BulletedListItemJson $array */
         $item = $array[self::TYPE];
 
-        $text = array_map(fn($t) => RichText::fromArray($t), $item["text"]);
+        $text = array_map(fn($t) => RichText::fromArray($t), $item["rich_text"]);
 
         $children = array_map(fn($b) => BlockFactory::fromArray($b), $item["children"] ?? []);
 
@@ -94,13 +93,24 @@ public function toArray(): array
         $array = $this->block->toArray();
 
         $array[self::TYPE] = [
-            "text"     => array_map(fn(RichText $t) => $t->toArray(), $this->text),
+            "rich_text"     => array_map(fn(RichText $t) => $t->toArray(), $this->text),
             "children" => array_map(fn(BlockInterface $b) => $b->toArray(), $this->children),
         ];
 
         return $array;
     }
 
+    /** @internal */
+    public function toUpdateArray(): array
+    {
+        return [
+            self::TYPE => [
+                "rich_text"     => array_map(fn(RichText $t) => $t->toArray(), $this->text),
+            ],
+            "archived" => $this->block()->archived(),
+        ];
+    }
+
     /** Get item content as string */
     public function toString(): string
     {
@@ -181,4 +191,13 @@ public function appendChild(BlockInterface $child): self
             $children,
         );
     }
+
+    public function archive(): BlockInterface
+    {
+        return new self(
+            $this->block->archive(),
+            $this->text,
+            $this->children,
+        );
+    }
 }