8000 git · 5am-code/laravel-notion-api@4244807 · GitHub
[go: up one dir, main page]
Skip to content

Commit 4244807

Browse files
johguentnerjohguentner
committed
git
2 parents 27620d3 + d16d87b commit 4244807

15 files changed

+348
-68
lines changed

‎.gitignore

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,5 @@
22
vendor
33
.phpunit.result.cache
44
coverage/
5-
.phpunit.cache/
5+
.phpunit.cache/
6+
.env*

‎CONTRIBUTING.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -42,14 +42,14 @@ If the project maintainer has any additional requirements, you will find them li
4242

4343
- **[PSR-2 Coding Standard](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md)** - The easiest way to apply the conventions is to install [PHP Code Sniffer](https://pear.php.net/package/PHP_CodeSniffer).
4444

45-
- **Add tests!** - Your patch won't be accepted if it doesn't have tests.
45+
- **Add tests!** - Your pull request won't be accepted if it doesn't have tests. When implementing new tests, please use the Pest PHP framework. You can find examples and detailed documentation at [pestphp.com](https://pestphp.com/).
4646

47-
- **Document any change in behaviour** - Make sure the `README.md` and any other relevant documentation are kept up-to-date.
47+
- **Document any change in behaviour** - Make sure the `README.md` is kept up-to-date. If you implement a new feature or propose significant changes to an existing feature, you will have to provide the documentation for these as well. The maintainers of the project will inform you about the process if necessary.
4848

4949
- **Consider our release cycle** - We try to follow [SemVer v2.0.0](https://semver.org/). Randomly breaking public APIs is not an option.
5050

5151
- **One pull request per feature** - If you want to do more than one thing, send multiple pull requests.
5252

5353
- **Send coherent history** - Make sure each individual commit in your pull request is meaningful. If you had to make multiple intermediate commits while developing, please [squash them](https://www.git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages) before submitting.
5454

55-
**Happy coding**!
55+
**Happy coding!** 🚀!

‎README.md

Lines changed: 124 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,121 +1,191 @@
11
<h1 align="center"> Notion for Laravel</h1>
22

3-
<img src="https://banners.beyondco.de/Notion%20for%20Laravel.png?theme=light&packageManager=composer+require&packageName=fiveam-code%2Flaravel-notion-api&pattern=architect&style=style_1&description=Effortless+Notion+integrations+with+Laravel&md=1&showWatermark=1&fontSize=100px&images=https%3A%2F%2Flaravel.com%2Fimg%2Flogomark.min.svg">
3+
<div align="center">
4+
<img src="https://notionforlaravel.com/images/open-graph.png" alt="Notion For Laravel" width="500">
45

6+
[![Run tests](https://github.com/5am-code/laravel-notion-api/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/5am-code/laravel-notion-api/actions/workflows/main.yml)
57
[![Latest Version on Packagist](https://img.shields.io/packagist/v/fiveam-code/laravel-notion-api.svg?style=flat-square)](https://packagist.org/packages/fiveam-code/laravel-notion-api)
68
[![Total Downloads](https://img.shields.io/packagist/dt/fiveam-code/laravel-notion-api.svg?style=flat-square)](https://packagist.org/packages/fiveam-code/laravel-notion-api)
79

810
[comment]: <> (![GitHub Actions]&#40;https://github.com/fiveam-code/laravel-notion-api/actions/workflows/main.yml/badge.svg&#41;)
9-
11+
</div>
1012
This package provides a simple and crisp way to access the Notion API endpoints, query data and update existing entries.
1113

14+
# Documentation
15+
16+
For a extensive documentation, more context and usage examples, head over to the official documentation at [notionforlaravel.com](https://notionforlaravel.com).
17+
18+
19+
# Quick Start Guide
20+
21+
All examples refer to our test database, which you can
22+
find [here](https://dianawebdev.notion.site/8284f3ff77e24d4a939d19459e4d6bdc?v=bc3a9ce8cdb84d3faefc9ae490136ac2).
1223

1324
## Installation
1425

15-
1. You can install the package via composer:
26+
The package is compatible with Laravel 8, 9 and 10. The minimum PHP requirement is 8.0.
1627

17-
```bash
18-
composer require fiveam-code/laravel-notion-api
19-
```
28+
1. Install the package via composer:
2029

30+
```bash
31+
composer require fiveam-code/laravel-notion-api
32+
```
2133

2234
2. Get your Notion API access token like explained in [their documentation](https://developers.notion.com/). It's also
23-
important to grant access to the integration within your Notion pages, which is described in the developer documentation at Notion as well.
35+
important to grant access to the integration within your Notion pages, which is described in the developer
36+
documentation at Notion as well.
37+
38+
3. Add a new line to your applications `.env` file:
39+
40+
```bash
41+
NOTION_API_TOKEN="$YOUR_ACCESS_TOKEN"
42+
```
2443

25-
3. For internal Integrations, please add a new entry to your `.env` like the following:
44+
4. You're ready to go! You can now access Notion endpoints through the `Notion` facade:
2645

27-
```bash
28-
NOTION_API_TOKEN="$YOUR_ACCESS_TOKEN"
29-
```
30-
4. Now you can easily access Notion:
31-
```php
32-
use \Notion;
33-
34-
Notion::databases()->find($databaseId);
35-
```
46+
```php
47+
use \Notion;
3648

37-
That's it.
49+
Notion::databases()->find("8284f3ff77e24d4a939d19459e4d6bdc");
50+
```
3851

52+
That's it.
3953

40-
## Usage
54+
For detailed usage information and a list of available endpoints see (the docs).
4155

42-
Head over to the [Documentation](https://notionforlaravel.com) of this package.
56+
## Examples
4357

44-
### 🔥 Code Examples to jumpstart your next Notion API Project
4558

46-
#### Fetch a Notion Database (through a Facade)
59+
### Fetch a Notion Database
60+
61+
The `databases()->find()` method returns a `FiveamCode\LaravelNotionApi\Entities\Database` object,
62+
which contains all the information about the database, including its properties and the possible values for each
63+
property.
64+
4765
```php
48-
use \Notion;
66+
use \Notion;
4967

5068
Notion::databases()
51-
->find("a7e5e47d-23ca-463b-9750-eb07ca7115e4");
69+
->find("8284f3ff77e24d4a939d19459e4d6bdc");
5270
```
5371

54-
#### Fetch a Notion Page
72+
### Fetch a Notion Page
73+
74+
The `pages()->find()` method returns a `FiveamCode\LaravelNotionApi\Entities\Page` object,
75+
which contains all the information about the page, including its properties and the possible values for each property.
76+
5577
```php
5678
Notion::pages()
5779
->find("e7e5e47d-23ca-463b-9750-eb07ca7115e4");
5880
```
5981

60-
#### Search
82+
### Search
83+
84+
The `search()` endpoint returns a collection of pages that match the search query. The scope of the search is limited to
85+
the workspace that the integration is installed in
86+
and the pages that are shared with the integration.
87+
6188
```php
62-
// Returns a collection pages and databases of your workspace (included in your integration-token)
63-
Notion::search("My Notion Search")
89+
Notion::search("Search term")
6490
->query()
6591
->asCollection();
6692
```
6793

68-
#### Query Database
94+
### Query Database
95+
96+
The `database()` endpoint allows you to query a specific database and returns a collection of pages (= database
97+
entries).
98+
You can filter and sort the results and limit the number of returned entries. For detailed information about the
99+
available
100+
filters and sorts, please refer to the [documentation](https://developers.notion.com/reference/post-database-query).
101+
102+
```php
103+
use FiveamCode\LaravelNotionApi\Query\Filters\Filter;
104+
use FiveamCode\LaravelNotionApi\Query\Filters\Operators;
105+
106+
$nameFilter = Filter::textFilter('Name', Operators::EQUALS, 'Ada Lovelace');
107+
108+
\Notion::database("8284f3ff77e24d4a939d19459e4d6bdc")
109+
->filterBy($nameFilter)
110+
->limit(5)
111+
->query()
112+
->asCollection();
113+
```
114+
115+
Compound filters for AND or OR queries are also available:
69116

70117
```php
71-
// Queries a specific database and returns a collection of pages (= database entries)
72-
$sortings = new Collection();
73-
$filters = new Collection();
74-
75-
$sortings->add(Sorting::propertySort('Ordered', 'ascending'));
76-
$sortings->add(Sorting::timestampSort('created_time', 'ascending'));
77-
78-
$filters->add(Filter::textFilter('title', ['contains' => 'new']));
79-
// or
80-
$filters->add(Filter::rawFilter('Tags', ['multi_select' => ['contains' => 'great']]));
81-
82-
Notion::database("a7e5e47d-23ca-463b-9750-eb07ca7115e4")
83-
->filterBy($filters) // filters are optional
84-
->sortBy($sortings) // sorts are optional
85-
->limit(5) // limit is optional
86-
->query()
87-
->asCollection();
118+
use Illuminate\Support\Collection;
119+
use FiveamCode\LaravelNotionApi\Query\Filters\Filter;
120+
use FiveamCode\LaravelNotionApi\Query\Filters\FilterBag;
121+
use FiveamCode\LaravelNotionApi\Query\Filters\Operators;
122+
use FiveamCode\LaravelNotionApi\Query\Sorting;
123+
124+
# Give me all entries that are
125+
# (KnownFor == UNIVAC || KnownFor == ENIAC)
126+
# and sort them by name ascending
127+
128+
$filterBag = new FilterBag(Operators::AND);
129+
130+
$filterBag->addFilter(
131+
Filter::rawFilter("Known for", [
132+
"multi_select" => [Operators::CONTAINS => "UNIVAC"],
133+
])
134+
);
135+
136+
$filterBag->addFilter(
137+
Filter::rawFilter("Known for", [
138+
"multi_select" => [Operators::CONTAINS => "ENIAC"],
139+
])
140+
);
141+
142+
\Notion::database("8284f3ff77e24d4a939d19459e4d6bdc")
143+
->filterBy($filterBag)
144+
->sortBy(Sorting::propertySort('Name', 'ascending'))
145+
->limit(5)
146+
->query()
147+
->asCollection();
88148
```
89149

150+
### Tests
151+
152+
You can find even more usage examples by checking out the package tests in the `/tests` directory.
153+
We are using [Pest](https://pestphp.com/) for out tests and are currently in the process of switching all existing PHPUnit tests to Pest.
90154

91-
### Testing (pestphp)
155+
If you want to run the tests in your CLI:
92156

93157
```bash
94158
vendor/bin/pest tests
95159
```
96160

97-
## Support
161+
# Support
162+
163+
## Supported by Tinkerwell
98164

99-
If you use this package in one of your projects or just want to support our development, consider becoming a [Patreon](https://www.patreon.com/bePatron?u=56662485)!
165+
<a href="https://tinkerwell.app/">
166+
<img src="https://tinkerwell.app/images/tinkerwell_logo.png" width="64" height="64" alt="Tinkerwell"> <br/>
167+
</a>
100168

101-
## Contributing
169+
The development of this package is supported by [Tinkerwell](https://tinkerwell.app/).
170+
171+
172+
# Contributing
102173

103174
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
104175

105-
## Security
176+
# Security
106177

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

109-
## Credits
180+
# Credits
110181

111182
- [Diana Scharf](https://github.com/mechelon)
112183
- [Johannes Güntner](https://github.com/johguentner)
113184

114-
115185
<p align="center">
116186
<img src="https://5amco.de/images/5am.png" width="200" height="200">
117187
</p>
118188

119-
## License
189+
# License
120190

121191
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

‎src/Exceptions/NotionException.php

Lines changed: 3 additions & 2 deletions
47
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
namespace FiveamCode\LaravelNotionApi\Exceptions;
44

55
use Illuminate\Http\Client\Response;
6+
use Illuminate\Support\Arr;
67

78
/**
89
* Class NotionException.
@@ -44,11 +45,11 @@ public static function fromResponse(Response $response): NotionException
4445
$responseBody = json_decode($response->getBody()->getContents(), true);
4546

4647
$errorCode = $errorMessage = '';
-
if (array_key_exists('code', $responseBody)) {
48+
if (Arr::exists($responseBody ?? [], 'code')) {
4849
$errorCode = "({$responseBody['code']})";
4950
}
5051

51-
if (array_key_exists('code', $responseBody)) {
52+
if (Arr::exists($responseBody ?? [], 'code')) {
5253
$errorMessage = "({$responseBody['message']})";
5354
}
5455

‎src/LaravelNotionApiServiceProvider.php

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
namespace FiveamCode\LaravelNotionApi;
44

55
use FiveamCode\LaravelNotionApi\Console\Commands\MakeNotionModel;
6+
use FiveamCode\LaravelNotionApi\Macros\PestHttpRecorder;
67
use Illuminate\Support\ServiceProvider;
78

89
/**
@@ -37,5 +38,9 @@ public function register()
3738
$this->app->singleton(Notion::class, function () {
3839
return new Notion(config('laravel-notion-api.notion-api-token'), config('laravel-notion-api.version'));
3940
});
41+
42+
if ($this->app->runningInConsole()) {
43+
PestHttpRecorder::register();
44+
}
4045
}
4146
}

0 commit comments

Comments
 (0)
0