Changelog

v0.2.0 → v0.3.0

We're still in an early development phase of the Laravel Notion API, so we still have some breaking changes in order to achieve a good structure for a great developer experience 🥰.

Nevertheless we want to make sure you can implement the breaking changes in no time. Just have a look at the guide below!

🔥 What's new

Easy access to content of page properties

Property classes provide simple access to their content.

# For example:
$page = \Notion::pages()->find($pageId);

# Property Select
$selectProperty = $page->getProperty($propertyKeyOfSelectProperty); // returns Select::class
$selectProperty->getName(); // returns name of select
$selectProperty->getColor(); // returns color of select

▶ More code-examples.

Search pages and databases

You can search all databases and pages which are included in your workspace.

# For example:
# Returns all databases and pages of the workspace filtered by the searchText you provide
\Notion::search($yourSearchText)
        ->query()
        ->asCollection();

▶ More code-examples.

Improved structure for server/client communication

By implementing JsonSerializable within the Entity::class and improving the structure of all entity-classes, it's easier to access the datastructure within JavaScript/TypeScript.

Especially helpful if you're working with inertiajs.

Breaking Changes

❗️ Constructor and handling of Notion::class changed

We now have a Notion Facade thanks to @marcelpociot!

You can still use the instance constructor, but watch out: The parameter order has changed - $notion_api_token comes first.

/*
 * Before
 */

# Usage with token stored in .env
use FiveamCode\LaravelNotionApi\Notion;
$notion = new Notion();
$notion->v1();
$notion->pages()->find($pageId);

# Usage with token in constructor:
use FiveamCode\LaravelNotionApi\Notion;
$notion = new Notion($version, $notion_api_token);

/*
 * As of v0.3.0:
 */

# Usage with token stored in .env
\Notion::pages()->find($pageId);

# Usage with token in constructor:
use FiveamCode\LaravelNotionApi\Notion;
$notion = new Notion($notion_api_token, $version);

❗️ Exceptions changed

In v0.2.0 WrapperException was thrown for different errors.

As of version 0.3.0, for every problem occurring from the Notion API (no response, failing response etc.) a NotionException is thrown.

For anything else (object not found, not implemented, wrong parameters, wrong json-structure etc.) a HandlingException is thrown.

❗️ Handling of Collections/Lists changed

All calls to endpoints which expected some kind of list returned a Illuminate\Support\Collection in v0.2.0.

/*
 * Before
 */

# Fetches a list of databases:
$notion->databases()
            ->all(); # returns collection

# Fetches all users from the current workspace
$notion->users()
            ->all(); # returns Collection

To make the endpoints more flexible, we decided to return an EntityCollection, respectively an inherited implementation of this class, for example PageCollection, from now on.

Now it's easy to get different types of results:

/*
 * As of v0.3.0:
 */

# Fetches a list of databases:
\Notion::databases()
            ->all()
            ->asCollection(); # returns collection

\Notion::databases()
            ->all()
            ->asJson(); # returns array, ready to be transferred to client-side (JavaScript/Typescript)

\Notion::databases()
            ->all()
            ->getRawResponse(); # returns untouched representation of the Notion API response

❗️ getPropertyNames() → getPropertyKeys() in Page

The method getPropertyNames(), which returns all keys of the properties of a page, was renamed to getPropertyKeys(). We think the label 'key' is more generic and fits better in this case.

/*
 * Before
 */
$propertyNames = $notion->pages()->find($pageId)->getPropertyNames();

/*
 * As of v0.3.0:
 */
$propertyNames = \Notion::pages()->find($pageId)->getPropertyKeys();

❗️ getRaw() → getRawResponse() in Entity

Notice: This change affects all endpoints (Database, Page, Property, User).

/*
 * Before
 */
$notionApiRawPageResponse = $notion->pages()->find($pageId)->getRaw();
$notionApiRawDbResponse = $notion->databases()->find($pageId)->getRaw();

/*
 * As of v0.3.0:
 */
$notionApiRawPageResponse = \Notion::pages()->find($pageId)->getRawResponse();
$notionApiRawDbResponse = \Notion::databases()->find($pageId)->getRawResponse();