Handling Results

All responses from Notion are structured in a certain way, in order to ease the use of the API. Every result is either an EntityCollection or an Entity. Additionally, you can always look at the raw result from the Notion API.

Entity Handling

An Entity is a single result from Notion. This can be a Block, Database, User, Property, Page etc.

Base Methods

Every Entity has some base functions to access basic information.

# This can be any of the entities
$entity = new Entity();

# Retrieve the ID of the Notion resources
$id = $entity->getId();

# Retrieve the type of the Notion resource
$objectType = $entity->getObjectType();

# Retrieve the raw result of the Notion API
$rawResponse = $entity->getRawResponse();

# Get the response structure as a JSON array
$entityAsJsonArray = $entity->toArray();

Timestampable Entities

Some entities have properties like created_time, last_edited_time, created_by and last_edited_by.

This is the case for Block, Database, Page, User and Comment.

While time properties are always DateTime::class instances, the created_by and last_edited_by properties are always User::class instances.

The following methods are available within timestampable entities.

$entity->getCreatedTime();
$entity->getLastEditedTime();

$entity->getCreatedBy();
$entity->getLastEditedBy();

Entities with a Parent

Some entities have a parent property, like Block Database, Page and Comment.

Both an id and the type of the parent are available as string. The type can be either a page_id, workspace_id, database_id.

The following methods are available within entities with a parent.

$entity->getParentId();
$entity->getParentType();

Archivable Entities

Some entities can be archived, like Block Database, and Page.

The following methods are available within archivable entities.

$entity->isArchived();

EntityCollection Handling

An EntityCollection is a collection of results from Notion. This can be a DatabaseCollection, BlockCollection, PageCollection, UserCollectionetc. Mostly these are results of search queries, database queries or retrieving content of Pages.

Base Methods

Every EntityCollection has functions to access basic information.

# This can be any of the above mentioned EntityCollections
$entityCollection = new EntityCollection();

# Get all results as a `Illuminate\Support\Collection`
$collectionResult = $entityCollection->asCollection();

# Get all results as JSON string
$jsonResult = $entityCollection->asJson();

# Check if there are more results available within the query (pagination)
$hasMoreEntries = $entityCollection->hasMoreEntries();

# Get the next cursor for the next page of results (`FiveamCode\LaravelNotionApi\Query\StartCursor`)
$startCursor = $entityCollection->nextCursor();

# Get the raw result of the next cursor (as string)
$rawNextCursor = $entityCollection->nextCursorRaw();

# Retrieve the raw result of the Notion API
$entityCollection->getRawResponse();