Updated README & contribution guide

Author: mechelon

CONTRIBUTING.md

@@ -42,14 +42,14 @@ If the project maintainer has any additional requirements, you will find them li
 
 - **[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).
 
-- **Add tests!** - Your patch won't be accepted if it doesn't have tests.
+- **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/).
 
-- **Document any change in behaviour** - Make sure the `README.md` and any other relevant documentation are kept up-to-date.
+- **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.
 
 - **Consider our release cycle** - We try to follow [SemVer v2.0.0](https://semver.org/). Randomly breaking public APIs is not an option.
 
 - **One pull request per feature** - If you want to do more than one thing, send multiple pull requests.
 
 - **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.
 
-**Happy coding**!
+**Happy coding!** 🚀!

README.md

@@ -1,6 +1,6 @@
 <h1 align="center"> Notion for Laravel</h1>
 
-<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">
+<img src="open-graph.png">
 
 [![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)
 [![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)
@@ -9,94 +9,158 @@
 
 This package provides a simple and crisp way to access the Notion API endpoints, query data and update existing entries.
 
-
 ## Installation
 
-1. You can install the package via composer:
+The package is compatible with Laravel 8, 9 and 10 with their respective PHP versions.
 
-    ```bash
-    composer require fiveam-code/laravel-notion-api
-    ```
+1. Install the package via composer:
 
+   ```bash
+   composer require fiveam-code/laravel-notion-api
+   ```
 
 2. Get your Notion API access token like explained in [their documentation](https://developers.notion.com/). 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.
+   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:
+
+   ```bash
+   NOTION_API_TOKEN="$YOUR_ACCESS_TOKEN"
+   ```
 
-3. For internal Integrations, please add a new entry to your `.env` like the following:
+4. You're ready to go! You can now access Notion endpoints through the `Notion` facade:
 
-    ```bash
-    NOTION_API_TOKEN="$YOUR_ACCESS_TOKEN"
-    ```
-4. Now you can easily access Notion:
-    ```php
-    use \Notion;
-    
-    Notion::databases()->find($databaseId);
-    ```
+   ```php
+   use \Notion;
 
-    That's it.
+   Notion::databases()->find("8284f3ff77e24d4a939d19459e4d6bdc");
+   ```
 
+   That's it.
 
-## Usage
+For detailed usage information and a list of available endpoints see (the docs).
 
-Head over to the [Documentation](https://notionforlaravel.com) of this package.
+## Examples
 
-### 🔥 Code Examples to jumpstart your next Notion API Project
+All examples refer to our test database, which you can
+find [here](https://dianawebdev.notion.site/8284f3ff77e24d4a939d19459e4d6bdc?v=bc3a9ce8cdb84d3faefc9ae490136ac2).
+
+### 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.
 
-#### Fetch a Notion Database (through a Facade)
 ```php
-use \Notion; 
+use \Notion;
 
 Notion::databases()
-        ->find("a7e5e47d-23ca-463b-9750-eb07ca7115e4");
+        ->find("8284f3ff77e24d4a939d19459e4d6bdc");
 ```
 
-#### Fetch a Notion Page
+### 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.
+
 ```php
 Notion::pages()
         ->find("e7e5e47d-23ca-463b-9750-eb07ca7115e4");
 ```
 
-#### Search
+### 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.
+
 ```php
-// Returns a collection pages and databases of your workspace (included in your integration-token)
-Notion::search("My Notion Search")
+Notion::search("Search term")
         ->query()
         ->asCollection();
 ```
 
-#### Query Database
+### 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](https://developers.notion.com/reference/post-database-query).
 
 ```php
-// Queries a specific database and returns a collection of pages (= database entries)
-$sortings = new Collection();
-$filters = new Collection();
-
-$sortings->add(Sorting::propertySort('Ordered', 'ascending'));
-$sortings->add(Sorting::timestampSort('created_time', 'ascending'));
-
-$filters->add(Filter::textFilter('title', ['contains' => 'new']));
-// or
-$filters->add(Filter::rawFilter('Tags', ['multi_select' => ['contains' => 'great']]));
-  
-Notion::database("a7e5e47d-23ca-463b-9750-eb07ca7115e4")
-      ->filterBy($filters) // filters are optional
-      ->sortBy($sortings) // sorts are optional
-      ->limit(5) // limit is optional
-      ->query()
-      ->asCollection();
+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:
+
+```php
+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();
+```
 
 ### Testing (pestphp)
 
+You can find even more usage examples by checking out the package tests in the `/tests` directory.
+The tests are making use of Pest PHP and we are working on switching from PHPUNIT to it (todo sentence).
+
+If you want to run the tests in your CLI:
+
 ```bash
 vendor/bin/pest tests
 ```
 
 ## Support
 
-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)!
+If you use this package in one of your projects or want to support our development, consider becoming
+a [Patreon Supporter](https://www.patreon.com/bePatron?u=56662485)!
+
+### Supported by Tinkerwell
+
+<a href="https://tinkerwell.app/">
+<img src="https://tinkerwell.app/images/tinkerwell_logo.png" width="64" height="64" alt="Tinkerwell"> <br/>
+</a>
+
+The development of this package is supported by [Tinkerwell](https://tinkerwell.app/).
+
 
 ## Contributing
 
@@ -111,7 +175,6 @@ If you discover any security related issues, please email hello@dianaweb.dev ins
 - [Diana Scharf](https://github.com/mechelon)
 - [Johannes Güntner](https://github.com/johguentner)
 
-
 <p align="center">
 <img src="https://5amco.de/images/5am.png" width="200" height="200">
 </p>