Client

The class is the main entry point for all interactions with the Notion API. It provides a clean, organized interface to access different API endpoints and handles the underlying HTTP communication, authentication, and error handling.

Basic usage

Simple initialization

The simplest way to create a client is by passing a object with your authentication token:

<?php

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

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

Default initialization

You can also create a client without any options, and configure it later:

<?php

use Brd6\NotionSdkPhp\Client;

// Create client with default options
$notion = new Client();

However, you'll need to provide authentication before making any requests.

ClientOptions configuration

The class allows you to configure various aspects of the client's behavior. All options have sensible defaults, but you can customize them as needed.

Available options

Configuring multiple options

The class uses fluent setter methods, allowing you to chain multiple configuration calls:

<?php

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

$options = (new ClientOptions())
    ->setAuth('your_notion_token')
    ->setTimeout(30)
    ->setNotionVersion('2022-02-22')
    ->setBaseUrl('https://api.notion.com/v1/');

$notion = new Client($options);

Custom HTTP client

If you need to use a specific HTTP client or configure it with custom options, you can provide your own PSR-18 compliant client:

<?php

use Brd6\NotionSdkPhp\Client;
use Brd6\NotionSdkPhp\ClientOptions;
use Symfony\Component\HttpClient\HttpClient;
use Symfony\Component\HttpClient\HttplugClient;

// Create a custom Symfony HTTP client with specific options
$httpClient = new HttplugClient(HttpClient::create([
    'timeout' => 120,
    'max_redirects' => 3,
]));

$options = (new ClientOptions())
    ->setAuth('your_notion_token')
    ->setHttpClient($httpClient);

$notion = new Client($options);

HTTP client auto-detection

When you don't provide a custom HTTP client, the SDK automatically detects and configures an appropriate HTTP client based on what's available in your project. The detection order is:

1. Symfony HTTP Client () - Preferred choice

2. Guzzle HTTP Client () - Popular alternative

3. cURL HTTP Client () - Lightweight option

4. PSR-18 Discovery - Falls back to any PSR-18 client found

The auto-detected client will be configured with your specified timeout and other relevant options.

Accessing API endpoints

Once you have a configured client, you can access different API endpoints through dedicated methods:

<?php

// Access different endpoints
$users = $notion->users();          // UsersEndpoint
$pages = $notion->pages();          // PagesEndpoint
$databases = $notion->databases();  // DatabasesEndpoint
$blocks = $notion->blocks();        // BlocksEndpoint
$comments = $notion->comments();    // CommentsEndpoint

// Make requests
$userList = $notion->users()->list();
$page = $notion->pages()->retrieve('page_id');
$searchResults = $notion->search();

Error handling

The client automatically handles HTTP errors and transforms them into appropriate exceptions. All requests can throw:

• - For Notion API errors (invalid requests, permissions, etc.)

• - For HTTP-related errors (network issues, server errors)

• - When requests exceed the configured timeout

<?php

use Brd6\NotionSdkPhp\Exception\ApiResponseException;
use Brd6\NotionSdkPhp\Exception\HttpResponseException;
use Brd6\NotionSdkPhp\Exception\RequestTimeoutException;

try {
    $page = $notion->pages()->retrieve('invalid_page_id');
} catch (ApiResponseException $e) {
    // Handle Notion API errors
    echo "API Error: " . $e->getMessage();
} catch (HttpResponseException $e) {
    // Handle HTTP errors
    echo "HTTP Error: " . $e->getMessage();
} catch (RequestTimeoutException $e) {
    // Handle timeout errors
    echo "Request timed out";
}