README

Documentation

For a extensive documentation, more context and usage examples, head over to the official documentation at notionforlaravel.com.

Quick Start Guide

All examples refer to our test database, which you can find here.

Installation

The package is compatible with Laravel 8, 9 and 10. The minimum PHP requirement is 8.0.

1. Install the package via composer:

   composer require fiveam-code/laravel-notion-api

2. Get your Notion API access token like explained in their documentation. It's also important to grant access to the integration within your Notion pages, which is described in the developer documentation at Notion as well.

3. Add a new line to your applications .env file:

   NOTION_API_TOKEN="$YOUR_ACCESS_TOKEN"

4. You're ready to go! You can now access Notion endpoints through the Notion facade:

   use \Notion;
   
   Notion::databases()->find("8284f3ff77e24d4a939d19459e4d6bdc");

   That's it.

For detailed usage information and a list of available endpoints see (the docs).

Examples

Fetch a Notion Database

The databases()->find() method returns a FiveamCode\LaravelNotionApi\Entities\Database object, which contains all the information about the database, including its properties and the possible values for each property.

use \Notion;

Notion::databases()
        ->find("8284f3ff77e24d4a939d19459e4d6bdc");

Fetch a Notion Page

The pages()->find() method returns a FiveamCode\LaravelNotionApi\Entities\Page object, which contains all the information about the page, including its properties and the possible values for each property.

Notion::pages()
        ->find("e7e5e47d-23ca-463b-9750-eb07ca7115e4");

Search

The search() endpoint returns a collection of pages that match the search query. The scope of the search is limited to the workspace that the integration is installed in and the pages that are shared with the integration.

Notion::search("Search term")
        ->query()
        ->asCollection();

Query Database

The database() endpoint allows you to query a specific database and returns a collection of pages (= database entries). You can filter and sort the results and limit the number of returned entries. For detailed information about the available filters and sorts, please refer to the documentation.

use FiveamCode\LaravelNotionApi\Query\Filters\Filter;
use FiveamCode\LaravelNotionApi\Query\Filters\Operators;

$nameFilter = Filter::textFilter('Name', Operators::EQUALS, 'Ada Lovelace');

\Notion::database("8284f3ff77e24d4a939d19459e4d6bdc")
    ->filterBy($nameFilter)
    ->limit(5)
    ->query()
    ->asCollection();

Compound filters for AND or OR queries are also available:

use Illuminate\Support\Collection;
use FiveamCode\LaravelNotionApi\Query\Filters\Filter;
use FiveamCode\LaravelNotionApi\Query\Filters\FilterBag;
use FiveamCode\LaravelNotionApi\Query\Filters\Operators;
use FiveamCode\LaravelNotionApi\Query\Sorting;

# Give me all entries that are
# (KnownFor == UNIVAC || KnownFor == ENIAC)
# and sort them by name ascending

$filterBag = new FilterBag(Operators::AND);

$filterBag->addFilter(
    Filter::rawFilter("Known for", [
        "multi_select" => [Operators::CONTAINS => "UNIVAC"],
    ])
);

$filterBag->addFilter(
    Filter::rawFilter("Known for", [
        "multi_select" => [Operators::CONTAINS => "ENIAC"],
    ])
);

\Notion::database("8284f3ff77e24d4a939d19459e4d6bdc")
    ->filterBy($filterBag)
    ->sortBy(Sorting::propertySort('Name', 'ascending'))
    ->limit(5)
    ->query()
    ->asCollection();

Tests

You can find even more usage examples by checking out the package tests in the /tests directory. We are using Pest for out tests and are currently in the process of switching all existing PHPUnit tests to Pest.

If you want to run the tests in your CLI:

vendor/bin/pest tests

Support

Supported by Tinkerwell

The development of this package is supported by Tinkerwell.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email hello@dianaweb.dev instead of using the issue tracker.

Credits

• Diana Scharf
• Johannes Güntner

License

The MIT License (MIT). Please see License File for more information.