Resources

Resources are PHP objects that represent Notion API entities like pages, databases, blocks, and users. Instead of working with raw JSON arrays, the SDK transforms API responses into strongly-typed PHP objects that provide a clean, object-oriented interface for accessing data.

Benefits of resources

Working with resource objects provides several advantages over raw JSON arrays:

• Type safety: Get IDE autocompletion and type hints

• Consistent interface: All resources follow the same patterns

• Nested data access: Easy access to deeply nested properties

• Validation: Automatic validation when creating resources from API data

• Extensibility: Easy to extend with custom methods

Before and after: Raw JSON vs Resources

Raw JSON response

Here's what a typical page response looks like from the Notion API:

{
  "object": "page",
  "id": "4a808e6e-8845-4d49-a447-fb2a4c460f6f",
  "created_time": "2022-03-08T22:56:00.000Z",
  "last_edited_time": "2022-03-24T15:24:00.000Z",
  "created_by": {
    "object": "user",
    "id": "7f03dda0-a132-49d7-b8b2-29c9ed1b1f0e"
  },
  "last_edited_by": {
    "object": "user",
    "id": "8dee9e49-7369-4a6d-a11f-7db625b2448c"
  },
  "cover": {
    "type": "external",
    "external": {
      "url": "https://example.com/cover.jpg"
    }
  },
  "icon": null,
  "parent": {
    "type": "workspace",
    "workspace": true
  },
  "archived": false,
  "properties": {
    "title": {
      "id": "title",
      "type": "title",
      "title": [
        {
          "type": "text",
          "text": {
            "content": "Getting Started",
            "link": null
          },
          "plain_text": "Getting Started"
        }
      ]
    }
  },
  "url": "https://www.notion.so/Getting-Started-4a808e6e88454d49a447fb2a4c460f6f"
}

Using Resource Objects (With SDK)

<?php

use Brd6\NotionSdkPhp\Client;
use Brd6\NotionSdkPhp\ClientOptions;

$options = (new ClientOptions())->setAuth('your_token');
$notion = new Client($options);

// The SDK automatically converts JSON to a Page resource
$page = $notion->pages()->retrieve('4a808e6e-8845-4d49-a447-fb2a4c460f6f');

// Clean, type-safe access to data
$pageId = $page->getId();
$createdTime = $page->getCreatedTime(); // Returns DateTimeImmutable
$createdBy = $page->getCreatedBy();     // Returns AbstractUser object

// Easy access to nested properties
if ($page->getCover() !== null) {
    $coverUrl = $page->getCover()->getExternal()->getUrl();
}

// Properties are also resource objects
$properties = $page->getProperties();
$titleProperty = $properties['title']; // Returns TitlePropertyValue object

Common resource types

The SDK includes resource classes for all major Notion API objects:

Core resources

• Page - Represents a Notion page

• Database - Represents a Notion database

• Block - Represents content blocks (paragraphs, headings, etc.)

• User - Represents workspace users and bots

• Comment - Represents page and block comments

Property resources

• Property Values - Page property values (TitlePropertyValue, TextPropertyValue, etc.)

• Property Configurations - Database property configurations (TitlePropertyConfiguration, etc.)

• Property Objects - Database property objects for queries and filters

Supporting resources

• File - Represents files, images, and external links

• RichText - Represents formatted text with annotations

• Pagination - Handles paginated API responses

Resource architecture

All resources extend from a common base class that provides shared functionality:

<?php

// All resources extend AbstractResource
abstract class AbstractResource extends AbstractJsonSerializable
{
    // Common properties
    protected string $object = ''; // The object type (e.g., "page", "database")
    protected string $id = '';     // The unique identifier

    // Common methods
    public function getId(): string;
    public function getObject(): string;
    public function getRawData(): array; // Access to original JSON data

    // Factory method - creates resource from API response
    public static function fromRawData(array $rawData): self;
}

Accessing nested data

Resources make it easy to access deeply nested data through chained method calls:

<?php

$coverUrl = $page->getCover()->getExternal()->getUrl();
$creatorName = $page->getCreatedBy()->getName();
$statusName = $page->getProperties()['Status']->getSelect()->getName();

Type safety and IDE support

Resources provide full type hints and IDE autocompletion:

<?php

/** @var Page $page */
$page = $notion->pages()->retrieve('page_id');

// IDE knows this returns DateTimeImmutable
$createdTime = $page->getCreatedTime();

// IDE knows this returns AbstractUser
$creator = $page->getCreatedBy();

// IDE can autocomplete available methods
$creatorId = $creator->getId();
$creatorName = $creator->getName();

Raw data access

If you need access to the original JSON data, every resource provides it:

<?php

$page = $notion->pages()->retrieve('page_id');

// Get the original JSON data as an array
$rawData = $page->getRawData();

// Useful for debugging or accessing properties not yet supported
$customField = $rawData['custom_field'] ?? null;