https://github.com/brd6/notion-sdk-php
PHP library for the official Notion API.
https://github.com/brd6/notion-sdk-php
notion notion-api notion-client notion-sdk php sdk
Last synced: 4 months ago
JSON representation
PHP library for the official Notion API.
- Host: GitHub
- URL: https://github.com/brd6/notion-sdk-php
- Owner: brd6
- License: mit
- Created: 2022-03-11T19:10:41.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2025-06-26T07:27:33.000Z (6 months ago)
- Last Synced: 2025-08-11T11:13:17.866Z (4 months ago)
- Topics: notion, notion-api, notion-client, notion-sdk, php, sdk
- Language: PHP
- Homepage:
- Size: 429 KB
- Stars: 59
- Watchers: 5
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
Notion SDK for PHP
PHP version of the official [NOTION API](https://developers.notion.com). It works the same way as the reference [JavaScript SDK](https://github.com/makenotion/notion-sdk-js) 🎉
## Installation
Install this package as a dependency using [Composer](https://getcomposer.org).
``` bash
composer require brd6/notion-sdk-php
```
This package `(brd6/notion-sdk-php)` is not tied to any specific library such as Guzzle or Buzz that sends HTTP messages. Instead, it uses the [PSR-18](https://www.php-fig.org/psr/psr-18/) client abstraction to let users choose whichever [PSR-7 implementation](https://packagist.org/providers/psr/http-message-implementation)
and [HTTP client](https://packagist.org/providers/psr/http-client-implementation) they want to use.
If you just want to get started quickly with symfony http client, run the following command:
```bash
composer require brd6/notion-sdk-php symfony/http-client nyholm/psr7
```
## Usage
> Use Notion's [Getting Started Guide](https://developers.notion.com/docs/getting-started) to get set up to use Notion's API.
Import and initialize a client using an **integration token** or an OAuth **access token**.
```php
use Brd6\NotionSdkPhp\Client;
use Brd6\NotionSdkPhp\ClientOptions;
$options = (new ClientOptions())
->setAuth(getenv('NOTION_TOKEN'));
$notion = new Client($options);
```
Make a request to any Notion API endpoint.
> See the complete list of endpoints in the [API reference](https://developers.notion.com/reference).
```php
$listUsersResponse = $notion->users()->list();
var_dump($listUsersResponse->toArray());
```
```php
array (size=4)
'has_more' => boolean false
'results' =>
array (size=2)
0 =>
array (size=6)
'object' => string 'user' (length=4)
'id' => string '7f03dda0-a132-49d7-b8b2-29c9ed1b1f0e' (length=36)
'type' => string 'person' (length=6)
'name' => string 'John Doe' (length=8)
'avatar_url' => string 'https://s3-us-west-2.amazonaws.com/public.notion-static.com/521dfe9c-f821-4de8-a0bb-e40ff71283e5/39989484_10217003981481443_4621803518267752448_n.jpg' (length=149)
'person' =>
array (size=1)
...
1 =>
array (size=5)
'object' => string 'user' (length=4)
'id' => string '8dee9e49-7369-4a6d-a11f-7db625b2448c' (length=36)
'type' => string 'bot' (length=3)
'name' => string 'MyBot' (length=5)
'bot' =>
array (size=1)
...
'object' => string 'list' (length=4)
'type' => string 'user' (length=4)
```
Endpoint parameters are grouped into a single object. You don't need to remember which parameters go in the path, query, or body.
```php
$databaseRequest = new DatabaseRequest();
$databaseRequest->setFilter([
'property' => 'Landmark',
'text' => [
'contains' => 'Bridge',
],
]);
$myPage = $notion->databases()->query('897e5a76-ae52-4b48-9fdf-e71f5945d1af', $databaseRequest)
```
### Handling errors
If the API returns an unsuccessful response, an `ApiResponseException` will be thrown.
The error contains properties from the response, and the most helpful is `code`. You can compare `code` to the values in the `NotionErrorCodeConstant` object to avoid misspelling error codes.
### Client options
The `Client` supports the following options on initialization. These options can be set on the `ClientOptions` instance.
| Option | Default value | Type | Description |
|--------------|----------------------------|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|
| `auth` | `''` | `string` | Bearer token for authentication. If left undefined, the `auth` parameter should be set on each request. |
| `timeout` | `60` | `number` | Number of seconds to wait before throw a `RequestTimeoutException` |
| `baseUrl` | `"https://api.notion.com"` | `string` | The root URL for sending API requests. This can be changed to test with a mock server. |
| `httpClient` | Default Http Client | `Psr\Http\Client\ClientInterface` | The Http Client used to make request on the Notion API. This can be change to customize the base Http Client or replace with a mocked Http Client. |
## Examples
The `examples/` directory contains a comprehensive set of usage examples that demonstrate how to use the SDK for various tasks, from basic API calls to complex integrations:
- **[01-intro-to-notion-api](examples/01-intro-to-notion-api/)** - Basic database queries and page creation
- **[02-parse-text-from-any-block](examples/02-parse-text-from-any-block/)** - Extract text content from all block types
- **[03-web-form](examples/03-web-form/)** - Web form to Notion page integration
- **[04-generate-random-data](examples/04-generate-random-data/)** - Populate databases with sample data
- **[05-notify-on-update](examples/05-notify-on-update/)** - Email notifications for database changes
- **[06-notion-github-sync](examples/06-notion-github-sync/)** - GitHub issues synchronization
- **[07-oauth-flow](examples/07-oauth-flow/)** - Complete OAuth 2.0 implementation
Each example is self-contained with its own dependencies, documentation, and setup instructions.
## Contributing
Contributions are welcome! To contribute, please familiarize yourself with
[CONTRIBUTING.md](CONTRIBUTING.md).
## License
The MIT License (MIT). Please see [LICENSE](LICENSE) for more information.