mariosimao / notion-sdk-php Goto Github PK

https://developers.notion.com/reference/delete-a-block

Leftover?

Originally posted by @Ocramius in #6 (comment)

self::LANG_* in here would make things much more explicit

Originally posted by @Ocramius in #6 (comment)

Hello, tell me what is the correct way to change the value of a property in a row from a database table? And yet, you can show an example of how to add new rows to a table with a data base.

There are no examples at all of how to change property values in pages. Or I didn't find it.

Thanks a lot. I hope you have some time to answer this question.

And thanks a lot for this SDK.

Add support to Link Preview

Instead of using Type[] syntax, consider being explicit about the shape of the input.

For example:

• RichText[] means array<array-key, RichText>
• array<int, RichText> could be [0 => new RichText(), 4 => new RichText()]
• list<RichText> is like array<int, RichText>, but prevents gaps in array keys (safer, when considering that a lot of this stuff will be json_encode()d

Originally posted by @Ocramius in #6 (comment)

I suggest using psr/http-message-implementation and psr/http-factory-implementation, then leave the picked implementation out of the hard requirements here

Originally posted in #6 (comment)

Somewhere in this documentation, it is worth explaining that either vimeo/psalm or phpstan/phpstan should be used in combination with this library, to avoid silly/simple mistakes

Originally posted by @Ocramius in #6 (comment)

Will this work also for third-parties trying your integration test suite?

Originally posted by @Ocramius in #6 (comment)

Support database actions:

• Create a database
• Update a database
• Retrieve a database

Where possible, use @psalm-immutable:

• @psalm-immutable for objects designed to not change state internally
• @psalm-pure on static methods that do not cause side-effects (usually factories for those objects)

Originally posted by @Ocramius in #6 (comment)

https://developers.notion.com/reference/update-a-block

https://developers.notion.com/reference/block#template-blocks

Currently, only Guzzle and SymfonyClient are supported, without any type of test.

Maybe a more concrete solution like PHP-HTTP Discovery would be better.

Possibly not applicable, but it is worth documenting title: non-empty-string or similar, when some constraints are also enforced by notion.com on some of this stuff: prevents a lot of runtime waste of time and validation :)

Originally posted by @Ocramius in #6 (comment)

https://developers.notion.com/changelog/link-previews-block-and-rich_text-supported-in-response

You really should run psalm only with locked dependencies - from experience, it is just too unstable to use lowest or highest with it

Originally posted in #6 (comment)

You might want to use azjezz/psl for improved type inference, in future: I've used beberlei/assert and webmozart/assert extensively over the years, but @azjezz's work is just so much better, long-term

Originally posted in #6 (comment)

/** @psalm-return BlockJson */ should probably be used here - in general, more precise type declarations save you some testing later on

Originally posted by @Ocramius in #6 (comment)

Internal cover images are now supported by Notion API, as read-only fields. I think we should be able to retrieve pages with internal covers instead of throwing an exception.

https://developers.notion.com/reference/retrieve-a-block

You should also cover your tests

Originally posted by @Ocramius in #6 (comment)

One thing you may want to start doing instead of coverage, is mutation testing, with either of:

• infection/infection
• roave/infection-static-analysis-plugin

Both should give you a good idea of which areas in the code are not tested well enough, but a mutation test score of >80% is generally really good :)

Code coverage itself is mostly a vanity metric these days: admirable, but not a clear indicator of tested/untested paths.

Originally posted by @Ocramius in #6 (comment)

https://developers.notion.com/reference/block#link-to-page-blocks

Probably worth enabling turning deprecations into errors here - PHPUnit disabled it because of Symfony's and PHP 8.1 broken design constraints, but it's good to prevent deprecations from randomly propagating to your consumers

Originally posted in #6 (comment)

PHP 8.1 Enum seem the right choice for many constants such as block type, code language, etc.

Hello, thanks for the great SDK 😁

It doesn't currently appear possible to create a RichText object with a link to a URL that's correctly formatted as a clickable link.

As an example, I currently have this code:

BulletedListItem::create()->withText([
    RichText::createText("My link: "),
    RichText::createText("https://example.com/my-link"),
]));

It's not possible to use a Text object directly as BulletedListItem only accepts RichText. https://example.com/my-link isn't clickable in Notion, I guess because the underlying text object isn't a link object (https://developers.notion.com/reference/rich-text#link-objects).

It would be great to be able to do something like the following to make the link clickable:

BulletedListItem::create()->withText([
    RichText::createText("My link: "),
    RichText::createText("https://example.com/my-link")
        ->withUrl("https://example.com/my-link"),
]));

• https://developers.notion.com/changelog/simple-table-support
• https://developers.notion.com/reference/block#table-blocks

Change Notion version header to 2022-02-22

Setting findUnusedCode to true on Psalm configuration would make it easier to find non-tested methods.

I like the way you designed all this with DI in mind :)

Only complain I have is that Client itself does not have an interface, so it is hard to mock/stub.

Another detail is that Client seems to be more like an entry-point: perhaps this class could be called Notion:

$notion = Notion::create(...)->users()->...

In fact, users() gives you a client, while Notion could be expanded with further utilities later on

Originally posted by @Ocramius in #6 (comment)

https://developers.notion.com/reference/patch-block-children

Does this API allow for the ability to return a set of pages from a given database? I can't seem to find any documentation or tests that handle this use-case. Perhaps I'm missing something?

https://developers.notion.com/reference/block#synced-block-blocks

• https://developers.notion.com/changelog/caption-property-is-now-supported-in-code-block-type

I have files property (Files & Media type)

when I'm fetching my page

$page = $notion->pages()->find('f3b4ab7c34fa4b71acb0c7fa011374d9');
dd($page);

I see error

Fatal error: Uncaught Exception: Invalid property type: 'files' in /Applications/MAMP/htdocs/projects/flextype/flextype/project/plugins/notion/vendor/mariosimao/notion-sdk-php/src/Pages/Properties/Factory.php:34 Stack trace: #0 /Applications/MAMP/htdocs/projects/flextype/flextype/project/plugins/notion/vendor/mariosimao/notion-sdk-php/src/Pages/Page.php(108): Notion\Pages\Properties\Factory::fromArray(Array) #1 /Applications/MAMP/htdocs/projects/flextype/flextype/project/plugins/notion/vendor/mariosimao/notion-sdk-php/src/Pages/Client.php(57): Notion\Pages\Page::fromArray(Array) #2 /Applications/MAMP/htdocs/projects/flextype/flextype/project/plugins/notion/plugin.php(58): Notion\Pages\Client->find('f3b4ab7c34fa4b7...') #3 /Applications/MAMP/htdocs/projects/flextype/flextype/src/flextype/core/Plugins.php(423): require_once('/Applications/M...') #4 /Applications/MAMP/htdocs/projects/flextype/flextype/src/flextype/core/Plugins.php(191): Flextype\Plugins->includeEnabledPlugins() #5 /Applications/MAMP/htdocs/projects/flextype/flextype/src/flextype/core/Plugins.php(51): Flextype\Plugins->init() #6 /Applications/MAMP/htdocs/projects/flextype/flextype/src/flextype/flextype.php(350): Flextype\Plugins->__construct() #7 /Applications/MAMP/htdocs/projects/flextype/flextype/index.php(46): require_once('/Applications/M...') #8 {main} thrown in /Applications/MAMP/htdocs/projects/flextype/flextype/project/plugins/notion/vendor/mariosimao/notion-sdk-php/src/Pages/Properties/Factory.php on line 34

s/psaml/psalm

Originally posted by @Ocramius in #6 (comment)

Add support to database properties with one class for each property.

• title
• rich_text
• number
• select
• multi_select
• date
• people
• files
• checkbox
• url
• email
• phone_number
• formula
• created_time
• created_by
• last_edited_time
• last_edited_by

Probably not relevant for an API client anyway

Originally posted by @Ocramius in #6 (comment)

See https://developers.notion.com/reference/post-database-query

Consider being more precise around string values that are constrained within a certain range. For example, this could be Block::TYPE_*

Originally posted by @Ocramius in #6 (comment)

With the new never return type, the method BlockInterface::changeChildren() could optionally be marked as a never returning method, due to blocks that do no accept children.

public function changeChildren(array $children): self|never

https://developers.notion.com/reference/post-search