### Raw Database Structure Example

Source: https://notionforlaravel.com/docs/v1.1.0/notion-databases/fetch-database-structure

Illustrates the raw JSON structure of a Notion database as returned by the API. This is useful for understanding the complete data model.

```json
{
  "object": "database",
  "id": "bc1211ca-e3f1-4939-ae34-5260b16f627c",
  "created_time": "2021-07-08T23:50:00.000Z",
  "last_edited_time": "2021-07-08T23:50:00.000Z",
  "icon": {
    "type": "emoji",
    "emoji": "🎉"
  },
  "cover": {
    "type": "external",
    "external": {
      "url": "https://website.domain/images/image.png"
    }
  },
  "url": "https://www.notion.so/bc1211cae3f14939ae34260b16f627c",
  "title": [
    {
      "type": "text",
      "text": {
        "content": "Grocery List",
        "link": null
      },
      "annotations": {
        "bold": false,
        "italic": false,
        "strikethrough": false,
        "underline": false,
        "code": false,
        "color": "default"
      },
      "plain_text": "Grocery List",
      "href": null
    }
  ],
  "description": [
    {
      "type": "text",
      "text": {
        "content": "Grocery list for just kale 🥬",
        "link": null
      },
      "annotations": {
        "bold": false,
        "italic": false,
        "strikethrough": false,
        "underline": false,
        "code": false,
        "color": "default"
      },
      "plain_text": "Grocery list for just kale 🥬",
      "href": null
    }
  ],
  "properties": {
    "Name": {
      "id": "title",
      "name": "Name",
      "type": "title",
      "title": {}
    }
  },
  "parent": {
    "type": "page_id",
    "page_id": "98ad959b-2b6a-4774-80ee-00246fb0ea9b"
  },
  "archived": false,
  "is_inline": false
}
```

--------------------------------

### Get Base Page Information

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/fetch-pages

Retrieve a page by its ID, get its title, icon, cover, and Notion URL. Ensure the page ID is valid.

```php
# Get Page
$page = Notion::pages()->find($pageId);

# Get Page Title
$page->getTitle();

# Get page icon and icon-type (emoji, file, external)
$database->getIcon();
$database->getIconType();

# Get page cover and cover-type (file, external)
$database->getCover();
$database->getCoverType();

# Get Notion URL of Page
$page->getUrl();

```

--------------------------------

### Query Database Entries (1-100)

Source: https://notionforlaravel.com/docs/v1.1.0/notion-databases/pagination

This is the initial query to retrieve the first 100 entries from a Notion database. It's the starting point for pagination.

```php
# query the database (1 - 100 entries)
$response = Notion::database($databaseId)->query();
```

--------------------------------

### Query Notion Database with Filters and Sorting

Source: https://notionforlaravel.com/docs/v1.1.0/notion-databases/filtering-and-sorting

Query a specific Notion database, applying filters and sorting to the results. This example shows how to build collections of sorts and filters, including using `rawFilter` for complex conditions.

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

# Queries a specific database and returns a collection of pages (= database entries)
$sortings = new Collection();
$filters = new Collection();

$sortings
    ->add(Sorting::propertySort("Birth year", "ascending"));
$sortings
    ->add(Sorting::timestampSort("created_time", "ascending"));

$filters
    ->add(
        Filter::textFilter("Name", Operators::EQUALS, "Ada Lovelace")
    );

# or
$filters
    ->add(
        Filter::rawFilter(
            "Known for",
            [
                "multi_select" =>
                    ["contains" => "COBOL"]
            ]
        )
    );

# the whole query
Notion::database("8284f3ff77e24d4a939d19459e4d6bdc")
        ->filterBy($filters) // filters are optional
        ->sortBy($sortings) // sorts are optional
        ->limit(5) // limit is optional
        ->query()
        ->asCollection();

// Returns Ada Lovelace and Grace Hopper from our Test Database: https://www.notion.so/8284f3ff77e24d4a939d19459e4d6bdc

```

--------------------------------

### GET /users

Source: https://notionforlaravel.com/docs/v1.1.0/basics/notion-users

Retrieve a list of all users within the connected Notion workspace.

```APIDOC
## GET /users

### Description
Retrieves all users from the connected workspace. A maximum of 100 users can be fetched.

### Method
GET

### Request Example
Notion::users()->all()->asCollection();
```

--------------------------------

### Get Database Properties

Source: https://notionforlaravel.com/docs/v1.1.0/notion-databases/fetch-database-structure

Retrieves structural information about all properties within a Notion database. This method returns a Collection of Property objects, not the content. Use `getPropertyKeys()` to get just the names.

```php
# `Collection` of objects inheriting `Property::class`
$collectionOfProperties = $database->getProperties();

# Get all keys of the properties (property names)
$arrayOfPropertyNames = $database->getPropertyKeys();
```

--------------------------------

### Fetch Database by ID

Source: https://notionforlaravel.com/docs/v1.1.0/notion-databases/fetch-database-structure

Retrieves a specific Notion database by its ID to get its structural information. Ensure the database ID is correctly formatted.

```php
$database = Notion::databases()->find($databaseId);
```

--------------------------------

### GET /databases/{databaseId}

Source: https://notionforlaravel.com/docs/v1.1.0/notion-databases/fetch-database-structure

Fetches a single Notion database by its unique identifier to retrieve structural information.

```APIDOC
## GET /databases/{databaseId}

### Description
Fetches one database and provides all structural information about it.

### Method
GET

### Endpoint
/databases/{databaseId}

### Parameters
#### Path Parameters
- **databaseId** (string) - Required - The unique identifier of the Notion database.

### Request Example
$database = Notion::databases()->find($databaseId);
```

--------------------------------

### Get Database Metadata

Source: https://notionforlaravel.com/docs/v1.1.0/notion-databases/fetch-database-structure

Extracts key metadata from a fetched Notion database object, such as title, description, icon, cover, and URL. Also checks if the database is inline.

```php
# Get database title and description
$database->getTitle();
$database->getDescription();

# Get database icon and icon-type (emoji, file, external)
$database->getIcon();
$database->getIconType();

# Get database cover and cover-type (file, external)
$database->getCover();
$database->getCoverType();

# Get database url (within Notion)
$database->getUrl();

# Check if database is inline
$database->isInline();
```

--------------------------------

### Notion user raw data structure

Source: https://notionforlaravel.com/docs/v1.1.0/basics/notion-users

Example of the raw JSON structure returned by the Notion API for a user object.

```json
{
  "object": "user",
  "id": "d40e767c-d7af-4b18-a86d-55c61f1e39a4",
  "type": "person",
  "person": {
    "email": "avo@example.org"
  },
  "name": "Avocado Lovelace",
  "avatar_url": "https://secure.notion-static.com/e6a352a8-8381-44d0-a1dc-9ed80e62b53d.jpg"
}
```

--------------------------------

### Raw Notion Comment Structure

Source: https://notionforlaravel.com/docs/v1.1.0/notion-comments/fetch-comments

An example of the complete JSON structure for a single Notion comment, including metadata and rich text content.

```json
{
  "object": "comment",
  "id": "94cc56ab-9f02-409d-9f99-1037e9fe502f",
  "parent": {
    "type": "page_id",
    "page_id": "5c6a2821-6bb1-4a7e-b6e1-c50111515c3d"
  },
  "discussion_id": "f1407351-36f5-4c49-a13c-49f8ba11776d",
  "created_time": "2022-07-15T16:52:00.000Z",
  "last_edited_time": "2022-07-15T19:16:00.000Z",
  "created_by": {
    "object": "user",
    "id": "9b15170a-9941-4297-8ee6-83fa7649a87a"
  },
  "rich_text": [
    {
      "type": "text",
      "text": {
        "content": "Single comment",
        "link": null
      },
      "annotations": {
        "bold": false,
        "italic": false,
        "strikethrough": false,
        "underline": false,
        "code": false,
        "color": "default"
      },
      "plain_text": "Single comment",
      "href": null
    }
  ]
}

```

--------------------------------

### Access Date Property

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/handle-properties

Retrieve start and end dates, and check if the property includes time information.

```php
$dateProp->getStart(); // returns `DateTime` (single or start-date)
$dateProp->getEnd(); // returns `DateTime` (end-date)
$dateProp->hasTime(); // returns `bool`
```

--------------------------------

### GET /users/{userId}

Source: https://notionforlaravel.com/docs/v1.1.0/basics/notion-users

Retrieve details for a specific Notion user by their unique identifier.

```APIDOC
## GET /users/{userId}

### Description
Finds and returns a specific user object based on the provided user ID.

### Method
GET

### Parameters
#### Path Parameters
- **userId** (string) - Required - The unique identifier of the Notion user.

### Request Example
$user = Notion::users()->find($userId);
```

--------------------------------

### Fetch Page Content

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/fetch-pages

To fetch the content of a Notion page, you need to retrieve its block children. The page ID can be used to get these children. Refer to the 'Fetch Blocks' documentation for more details.

```php
# Get Page Content
# A Notion Page itself is considered a block and the `Page ID` can be used for retrieving its children.
# More details can be found at  Fetch Blocks .

```

--------------------------------

### Get Raw Next Cursor UUID

Source: https://notionforlaravel.com/docs/v1.1.0/notion-databases/pagination

Access the raw string representation of the next cursor, which is the UUID of the next page.

```php
$nextPageUuid = $response->getRawNextCursor();
```

--------------------------------

### Get Next Cursor for Pagination

Source: https://notionforlaravel.com/docs/v1.1.0/notion-databases/pagination

Retrieve the cursor object needed to fetch the next page of results. This object contains the necessary information to continue the pagination.

```php
# get StartCursor::class object, which can be used to get next page of pagination
$startCursor = $response->getNextCursor();
```

--------------------------------

### Accessing Timestampable Entity Properties

Source: https://notionforlaravel.com/docs/v1.1.0/basics/handling-results

For entities that have creation and editing timestamps, use these methods to get the time instances and the user who performed the action.

```php
$entity->getCreatedTime();
$entity->getLastEditedTime();

$entity->getCreatedBy();
$entity->getLastEditedBy();

```

--------------------------------

### Get Search Results as JSON

Source: https://notionforlaravel.com/docs/v1.1.0/basics/search-notion-content

Retrieve search results directly as a JSON string, which can simplify frontend handling in JavaScript frameworks like Vue or React.

```php
Notion::search()
        ->query()
        ->asJson();

```

--------------------------------

### Create Property Instance

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/handle-properties

Use dedicated property classes to create new property values.

```php
use FiveamCode\LaravelNotionApi\Entities\Properties\Text;

# Creating a new Property
$textProperty = Text::value('This is a Text Property');
```

--------------------------------

### Create Notion Database with Configuration

Source: https://notionforlaravel.com/docs/v1.1.0/notion-databases/create-database

Creates a Notion database with custom configurations including inline status (currently not supported), title, external cover image, external icon, and description. The parent page ID is required.

```php
$databaseEntity = Notion::databases()
        ->build()
        ->inline() // Currently not supported due to Notion API versioning
        ->title('Created By Laravel')
        ->coverExternal('https://example.com/cover.jpg')
        ->iconExternal('https://example.com/cover.jpg')
        ->description('This Database has been created by Laravel')
        ->createInPage('0adbc2eb47e84569a700a60d537615be');
```

--------------------------------

### Entity Handling

Source: https://notionforlaravel.com/docs/v1.1.0/basics/handling-results

Explains how to work with individual Notion entities.

```APIDOC
## Entity Handling

An `Entity` is a single result from Notion. This can be a `Block`, `Database`, `User`, `Property`, `Page` etc.

### Base Methods

Every `Entity` has some base functions to access basic information.

```php
// This can be any of the entities
$entity = new Entity();

// Retrieve the ID of the Notion resources
$id = $entity->getId();

// Retrieve the type of the Notion resource
$objectType = $entity->getObjectType();

// Retrieve the raw result of the Notion API
$rawResponse = $entity->getRawResponse();

// Get the response structure as a JSON array
$entityAsJsonArray = $entity->toArray();
```

### Timestampable Entities

Some entities have properties like `created_time`, `last_edited_time`, `created_by` and `last_edited_by`. This is the case for `Block`, `Database`, `Page`, `User` and `Comment`.

While time properties are always `DateTime::class` instances, the `created_by` and `last_edited_by` properties are always `User::class` instances.

The following methods are available within timestampable entities:

```php
$entity->getCreatedTime();
$entity->getLastEditedTime();

$entity->getCreatedBy();
$entity->getLastEditedBy();
```

### Entities with a Parent

Some entities have a parent property, like `Block` `Database`, `Page` and `Comment`.

Both an id and the type of the parent are available as `string`. The type can be either a `page_id`, `workspace_id`, `database_id`.

The following methods are available within entities with a parent:

```php
$entity->getParentId();
$entity->getParentType();
```

### Archivable Entities

Some entities can be archived, like `Block` `Database`, and `Page`.

The following methods are available within archivable entities:

```php
$entity->isArchived();
```
```

--------------------------------

### Access Comment IDs

Source: https://notionforlaravel.com/docs/v1.1.0/notion-comments/fetch-comments

Get the unique identifier and discussion identifier for a comment using dedicated getter methods.

```php
$comment->getId();
$comment->getDiscussionId();

```

--------------------------------

### Create Basic Notion Database

Source: https://notionforlaravel.com/docs/v1.1.0/notion-databases/create-database

Creates a new Notion database with a default title property. The parent page ID is required.

```php
$databaseEntity = Notion::databases()
        ->build()
        ->createInPage('0adbc2eb47e84569a700a60d537615be');
```

--------------------------------

### Build and Create Notion Database

Source: https://notionforlaravel.com/docs/v1.1.0/notion-databases/create-database

Use `PropertyBuilder` to define initial properties for a new Notion database. The `title` property is required. The database is then created within a specified Notion page.

```php
use FiveamCode\LaravelNotionApi\Builder\PropertyBuilder;

$props = collect([
     PropertyBuilder::title('My Title'), // Title is required
     PropertyBuilder::richText('MyText'),  // Name of property is (mostly) optional
     PropertyBuilder::checkbox('...'),
    //PropertyBuilder::status(), // WARNING: Currently not supported
     PropertyBuilder::number(),
     PropertyBuilder::url(),
     PropertyBuilder::email(),
     PropertyBuilder::phoneNumber(),
     PropertyBuilder::people(),
     PropertyBuilder::files(),
     PropertyBuilder::createdBy(),
     PropertyBuilder::createdTime(),
     PropertyBuilder::lastEditedBy(),
     PropertyBuilder::lastEditedTime(),
     PropertyBuilder::formula('Testing', 'prop("MultiSelect")'),
     PropertyBuilder::select('Select', $selectOptions), // please refer 'Bulk Generation' 
     PropertyBuilder::multiSelect('MultiSelect', $multiSelectOptions), // please refer 'Bulk Generation'
]);

$databaseEntity = Notion::databases()
    ->build()
    ->title('Test DB 3')
    ->add($props) // add multiple properties (Collection)
    ->add(PropertyBuilder::date('My Date')) // add single property
    ->createInPage('1c682e7371ec4399be1cc015686c67c6');

```

--------------------------------

### Execute PEST tests

Source: https://notionforlaravel.com/docs/v1.1.0/development/testing

Run the test suite from the root directory of the package.

```bash
./vendor/bin/pest tests
```

--------------------------------

### Perform Basic Content Search

Source: https://notionforlaravel.com/docs/v1.1.0/basics/search-notion-content

Query all connected databases and pages in a Notion workspace based on a search string. The maximum amount of entries that can be queried is 100. If the search string is NULL, all entries are returned.

```php
$search = 'search term';

Notion::search($search) // if NULL, all entries are returned
        ->query()
        ->asCollection();

```

--------------------------------

### Fetch All Databases (Deprecated)

Source: https://notionforlaravel.com/docs/v1.1.0/notion-databases/fetch-database-structure

Retrieves all databases the workspace has granted access to. This endpoint is deprecated and may be removed; use 'Search Notion Content' instead.

```php
# Returns all databases of the workspace that were explicitly granted access.
Notion::databases()
        ->all()
        ->asCollection();
```

--------------------------------

### Query all Notion users

Source: https://notionforlaravel.com/docs/v1.1.0/basics/notion-users

Retrieves a list of up to 100 users from the connected workspace.

```php
Notion::users()
        ->all()
        ->asCollection(); // or `asJson()`
```

--------------------------------

### EntityCollection Handling

Source: https://notionforlaravel.com/docs/v1.1.0/basics/handling-results

Explains how to work with collections of Notion entities, often returned from search or database queries.

```APIDOC
## EntityCollection Handling

An `EntityCollection` is a collection of results from Notion. This can be a `DatabaseCollection`, `BlockCollection`, `PageCollection`, `UserCollection`etc. Mostly these are results of search queries, database queries or retrieving content of `Pages`.

### Base Methods

Every `EntityCollection` has functions to access basic information.

```php
// This can be any of the above mentioned EntityCollections
$entityCollection = new EntityCollection();

// Get all results as a `Illuminate\Support\Collection`
$collectionResult = $entityCollection->asCollection();

// Get all results as JSON string
$jsonResult = $entityCollection->asJson();

// Check if there are more results available within the query (pagination)
$hasMoreEntries = $entityCollection->hasMoreEntries();

// Get the next cursor for the next page of results (`FiveamCode\LaravelNotionApi\Query\StartCursor`)
$startCursor = $entityCollection->nextCursor();

// Get the raw result of the next cursor (as string)
$rawNextCursor = $entityCollection->nextCursorRaw();

// Retrieve the raw result of the Notion API
$entityCollection->getRawResponse();
```
```

--------------------------------

### Add Database Properties using Eloquent Way

Source: https://notionforlaravel.com/docs/v1.1.0/notion-databases/create-database

Creates a database schema using a closure, mimicking Eloquent migrations. Supports various property types, with 'Status' being unsupported. Requires 'select' and 'multiSelect' options to be defined separately.

```php
$databaseEntity = Notion::databases()
    ->build()
    ->title('Test Database')
    ->scheme(function ($table) {
        $table->title('MyTitle') // Title is required
        $table->richText('MyText')
        $table->checkbox('...') // Name of property is (mostly) optional
        // $table->status() // WARNING: Currently not supported
        $table->number()
        $table->date()
        $table->url()
        $table->email()
        $table->phoneNumber()
        $table->people()
        $table->files()
        $table->createdBy()
        $table->createdTime()
        $table->lastEditedBy()
        $table->lastEditedTime()
        $table->formula('Testing', 'prop("MultiSelect")')
        $table->select('Select', $selectOptions) // please refer 'Bulk Generation'
        $table->multiSelect('MultiSelect', $multiSelectOptions); // please refer 'Bulk Generation'
    })
    ->createInPage('1c682e7371ec4399be1cc015686c67c6');
```

--------------------------------

### Set Notion Page Properties

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/create-and-modify-pages

Demonstrates two ways to set properties for a Notion page before creation or update. The `::value` method is standard, while the alternative method provides a more direct setter.

```php
use FiveamCode\LaravelNotionApi\Entities\Properties\Title;

$page = new Page();

# Basic way of setting Properties
$page->set('title', Title::value('I was created from Laravel'));

# Alternative to ::value
$page->setTitle('title', 'I was by you');

Notion::pages()->createInDatabase($databaseId, $page);

```

--------------------------------

### Initialize filter bags

Source: https://notionforlaravel.com/docs/v1.1.0/notion-databases/filter

Create empty filter bags using the AND or OR operators.

```php
$andFilter = FilterBag::and();
$orFilter = FilterBag::or();
```

--------------------------------

### Create a Url Property

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/handle-properties

Creates a URL property from a string.

```php
$urlProperty = Url::value($url); // $url is a `string`
```

--------------------------------

### Fetch Pages

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/fetch-pages

This section details how to retrieve base information about Notion pages.

```APIDOC
## GET /pages/{pageId}

### Description
Fetches the base information of a specific Notion page using its ID.

### Method
GET

### Endpoint
`/pages/{pageId}`

### Parameters
#### Path Parameters
- **pageId** (string) - Required - The unique identifier of the Notion page.

### Request Example
```php
$page = Notion::pages()->find($pageId);
```

### Response
#### Success Response (200)
- **title** (string) - The title of the Notion page.
- **icon** (object) - The icon of the Notion page. Can be emoji, file, or external.
- **cover** (object) - The cover image of the Notion page. Can be file or external.
- **url** (string) - The Notion URL of the page.

#### Response Example
```json
{
  "title": "Example Page Title",
  "icon": {
    "type": "emoji",
    "emoji": "🚀"
  },
  "cover": {
    "type": "external",
    "external": {
      "url": "https://example.com/cover.jpg"
    }
  },
  "url": "https://www.notion.so/Example-Page-Title-a1b2c3d4e5f67890a1b2c3d4e5f67890"
}
```
```

```APIDOC
## GET /pages/{pageId}/content

### Description
Fetches the content of a Notion page by retrieving its block children.

### Method
GET

### Endpoint
`/pages/{pageId}/content`

### Parameters
#### Path Parameters
- **pageId** (string) - Required - The unique identifier of the Notion page.

### Request Example
```php
// To fetch page content, you need to retrieve the block children of the page.
// The Page ID can be used for this purpose.
$blocks = Notion::blocks()->children($pageId)->get();
```

### Response
#### Success Response (200)
- **blocks** (array) - A list of block objects representing the content of the page.

#### Response Example
```json
{
  "blocks": [
    {
      "object": "block",
      "id": "block-id-1",
      "type": "paragraph",
      "paragraph": {
        "rich_text": [
          {
            "type": "text",
            "text": {
              "content": "This is the first paragraph."
            }
          }
        ]
      }
    },
    {
      "object": "block",
      "id": "block-id-2",
      "type": "heading_2",
      "heading_2": {
        "rich_text": [
          {
            "type": "text",
            "text": {
              "content": "A Subheading"
            }
          }
        ]
      }
    }
  ]
}
```
```

--------------------------------

### Access Url Property

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/handle-properties

Retrieve the URL as a string.

```php
$urlProp->getUrl(); // returns `string`
```

--------------------------------

### Create a Select Property

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/handle-properties

Creates a single-select property. New items are automatically created in Notion if they do not exist.

```php
$item = 'Item 1';
$selectProperty = Select::value($item);
```

--------------------------------

### Create an Email Property

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/handle-properties

Creates an email property from a string.

```php
$emailProperty = Email::value($email);
```

--------------------------------

### Query Next Page with Offset

Source: https://notionforlaravel.com/docs/v1.1.0/notion-databases/pagination

Use the cursor obtained from `getNextCursor()` to query the subsequent set of entries (e.g., entries 101-200).

```php
# get next iteration of pagination, with $startCursor (entries 101-200)
$responseWithOffset = Notion::database($databaseId)
        ->offset($startCursor)
        ->query();
```

--------------------------------

### Database Pagination

Source: https://notionforlaravel.com/docs/v1.1.0/notion-databases/query-database

Handles pagination for database queries using cursors.

```APIDOC
## GET /database/{databaseId}/query (Paginated)

### Description
Retrieves subsequent pages of results using a cursor offset.

### Method
GET

### Parameters
#### Query Parameters
- **offset** (string) - Optional - The cursor string to fetch the next set of results.

### Request Example
```php
$response = Notion::database($databaseId)->query();
$startCursor = $response->getNextCursor();

$responseWithOffset = Notion::database($databaseId)
        ->offset($startCursor)
        ->query();
```
```

--------------------------------

### Resolving User Instances

Source: https://notionforlaravel.com/docs/v1.1.0/basics/resolving-entities

Fetches full User instances from database properties that only return user IDs.

```php
$page = Notion::pages()->find('8890c263-e97c-4533-9ef5-616d5e75360e');

$createdBy = $page->getProperty('Created by');
$lastEditedBy = $page->getProperty('Last edited by');
$person = $page->getProperty('Person');

$createdByUser = Notion::resolve()->user($createdBy->getUser());
$lastEditedByUser = Notion::resolve()->user($lastEditedBy->getUser());
$personUser = Notion::resolve()->user($person->getPeople()->first());
```

--------------------------------

### Create raw filters

Source: https://notionforlaravel.com/docs/v1.1.0/notion-databases/filter

Use rawFilter for property types that do not have dedicated helper methods.

```php
// Filter condition: ('Known for' CONTAINS 'COBOL')
$filter = Filter::rawFilter(
            "Known for",
            [
                "multi_select" =>
                    [Operators::CONTAINS => "COBOL"]
            ]
        );
```

--------------------------------

### Access Select Property

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/handle-properties

Retrieve the selected item, options, name, or color.

```php
$selectProp->getItem(); // returns `*\Entities\SelectItem`
$selectProp->getOptions(); // returns `Illuminate\Support\Collection` of `*\Entities\SelectItem`
$selectProp->getName(); // returns `string`
$selectProp->getColor(); // returns `string`
```

--------------------------------

### Instantiate a Comment Object

Source: https://notionforlaravel.com/docs/v1.1.0/notion-comments/create-comments

Create a new comment object using `Comment::fromText()`. This method accepts a string or a RichText object.

```php
use FiveamCode\LaravelNotionApi\Entities\Comment;

$comment = Comment::fromText('This is a comment');
$comment = Comment::fromText($richTextObject); // `RichText::class` instance
```

--------------------------------

### Access Files Property

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/handle-properties

Retrieve a collection of file URLs.

```php
$filesProp->getFiles(); // returns a `Illuminate\Support\Collection` of strings
```

--------------------------------

### Set a Notion Page Property

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/handle-properties

General method for applying a property object to a Notion page instance.

```php
$notionPage->setProperty('Text Property', $textProperty);
```

--------------------------------

### Create Notion Page Within a Page

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/create-and-modify-pages

Use this method to create a new Notion page as a child of an existing page. Custom properties cannot be set for pages created this way.

```php
use FiveamCode\LaravelNotionApi\Entities\Properties\Title;

# This has to be a valid uuid of the parent Notion Page
$parentPageId = 'f7a7c7f7-7f7f-7f7f-7f7f-7f7f7f7f7f7f';

# Create the page and set the title
$page = new Page();
$page->set('title', Title::value('I was created from Laravel'));

Notion::pages()->createInPage($parentPageId, $page);

```

--------------------------------

### Create a Title Property

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/handle-properties

Creates a title property from a string or RichText object.

```php
$titleProperty = Title::value($title); // $title is a `string` or `*\Entities\PropertyItems\RichText`
```

--------------------------------

### Retrieve Page Properties

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/handle-properties

Access individual properties by name or retrieve all properties as a collection from a page instance.

```php
$propertyName = 'Your Property Title';

# Get the desired property
# If unsupported:   `*\Entities\Properties\Property`
# If supported:     `*\Entities\Properties\{PropertyType}`
$property = $page->getProperty($propertyName);

# Retrieve all properties as `Illuminate\Support\Collection`
$collectionOfProperties = $page->getProperties();
```

--------------------------------

### Create Notion Page Within a Database

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/create-and-modify-pages

Create a new Notion page within a specific database. This allows for custom properties to be set, which must match the database structure. Unset properties default to empty.

```php
use FiveamCode\LaravelNotionApi\Entities\Properties\Title;

# This has to be a valid uuid of a Notion Page
$parentDatabaseId = 'f7a7c7f7-7f7f-7f7f-7f7f-7f7f7f7f7f7f';

# Create the Page and set the Title
$page = new Page();
$page->set('title', Title::value('I was created from Laravel'));

# [...] setting properties

Notion::pages()->createInDatabase($parentDatabaseId, $page);

```

--------------------------------

### Access Property Metadata

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/handle-properties

Use these methods on a property instance to retrieve its title, type, or raw content.

```php
# Get Property Title
$property->getTitle();

# Get Property Type
$property->getType();

# Get the base content of the property 
# raw content, if unsupported
$property->getContent();

# Get the raw content of the property
$property->getRawContent();

# Get string formatted content of the property (will be a JSON string, if unsupported)
$property->asText();
```

--------------------------------

### Create a Date Property

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/handle-properties

Creates date properties with or without time information using DateTime objects.

```php
# Both $startDate and $endDate are `DateTime`
# Any time information will be ignored
$dateProperty = Date::value($startDate, $endDate /* optional */);

# Both $startDate and $endDate are `DateTime`
# Your time information will be set within the Property in Notion
$dateProperty = Date::valueWithTime($startDate, $endDate /* optional */);
```

--------------------------------

### Query Notion Databases

Source: https://notionforlaravel.com/docs/v1.1.0/notion-databases/query-database

Retrieves a collection of pages from a specified Notion database.

```APIDOC
## GET /database/{databaseId}/query

### Description
Queries a Notion database and returns a PageCollection containing the pages.

### Method
GET

### Endpoint
Notion::database($databaseId)->query()

### Response
#### Success Response (200)
- **PageCollection** (object) - A collection of pages that can be accessed as a Laravel Collection or JSON string.

### Request Example
```php
$pageCollection = Notion::database($databaseId)->query();
$collectionOfPages = $pageCollection->asCollection();
$jsonOfPages = $pagesCollection->asJson();
```
```

--------------------------------

### Create a People Property

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/handle-properties

Creates a people property using an array of valid user UUIDs.

```php
$people = ['user-id-1', 'user-id-2', 'user-id-3'];
$peopleProperty = People::value($people);
```

--------------------------------

### Accessing a Page Parent

Source: https://notionforlaravel.com/docs/v1.1.0/basics/resolving-entities

Retrieves the parent object of a page as a NotionParent instance.

```php
$page = Notion::pages()->find('91f70932-ee63-47b5-9bc2-43e09b4cc9b0');
$notionParent = $page->getParent();
```

--------------------------------

### Access Text Property

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/handle-properties

Retrieve rich text objects or plain text content.

```php
$textProp->getRichText(); // returns `*\Entities\PropertyItems\RichText`
$textProp->getPlainText(); // returns `string`
```

--------------------------------

### Create a MultiSelect Property

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/handle-properties

Creates a multi-select property from an array of strings. New items are automatically created in Notion if they do not exist.

```php
$items = ['Item 1', 'Item 2', 'Item 3'];
$multiSelectProperty = MultiSelect::value($items);
```

--------------------------------

### Fetch Block Children Including Unsupported

Source: https://notionforlaravel.com/docs/v1.1.0/notion-blocks/fetch-blocks

Retrieve block children, forcing the inclusion of blocks that are not officially supported by the Notion API. This can be useful for handling all block types.

```php
# Fetches children from a specific block as JSON
Notion::block($blockId)
       ->children()
       ->withUnsupported()
       ->asCollection();
```

--------------------------------

### Create a Text Property

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/handle-properties

Creates a text property from a string or RichText object.

```php
$textProperty = Text::value($text); // $text is a `string` or `*\Entities\PropertyItems\RichText`
```

--------------------------------

### Create a Number Property

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/handle-properties

Creates a number property from a float value.

```php
$numberProperty = Number::value($number); // $number is a `float`
```

--------------------------------

### Access Email Property

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/handle-properties

Retrieve the email address as a string.

```php
$emailProp->getEmail(); // returns `string`
```

--------------------------------

### Create a PhoneNumber Property

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/handle-properties

Creates a phone number property from a string.

```php
$phoneNumberProperty = PhoneNumber::value($phoneNumber); // $phoneNumber is a `string`
```

--------------------------------

### Supported Notion Blocks

Source: https://notionforlaravel.com/docs/v1.1.0/notion-blocks/supported-blocks

Lists all implemented block classes within the FiveamCode\LaravelNotionApi\Entities\Blocks namespace. Unsupported blocks are returned as Block::class.

```APIDOC
## Supported Blocks

You can find all implemented block classes in the namespace: `FiveamCode\LaravelNotionApi\Entities\Blocks`.
All unsupported or unrecognized blocks will be returned as `Block::class`.

### List of Implemented Blocks

* BulletListItem
* ChildPage
* HeadingOne
* HeadingTwo
* HeadingThree
* NumberedListItem
* Paragraph
* TextBlock
* Quote
* ToDo
* Toggle
* Image
* Embed
* File
* Video
* Pdf
```

--------------------------------

### Use Previous Response as Offset

Source: https://notionforlaravel.com/docs/v1.1.0/notion-databases/pagination

An alternative to `getNextCursor()`, this method allows using the entire previous response object to query the next page of results.

```php
# query the database (entries 1-100)
$previousResponse = Notion::database($databaseId)->query();

# query the database further (entries 101-200)
$responseWithOffset = Notion::database($databaseId)
        ->offsetByResponse($previousResponse)
        ->query();
```

--------------------------------

### Notion Content Search

Source: https://notionforlaravel.com/docs/v1.1.0/basics/search-notion-content

Methods for searching and filtering Notion workspace content.

```APIDOC
## Notion::search()

### Description
Query all connected databases and pages of a Notion workspace based on a search string. The maximum number of entries that can be queried is 100.

### Methods
- **search(string $query)**: Initiates the search. If null, all entries are returned.
- **onlyPages()**: Constrains search results to Pages only.
- **onlyDatabases()**: Constrains search results to Databases only.
- **limit(int $count)**: Limits the number of search results.
- **sortByLastEditedTime(string $direction)**: Sorts results by 'ascending' or 'descending' order.
- **query()**: Executes the search query.
- **asCollection()**: Returns the results as a Laravel Collection.
- **asJson()**: Returns the results as a JSON string.

### Request Example
```php
// Basic search
Notion::search('search term')->query()->asCollection();

// Filtered and limited search
Notion::search()
    ->onlyPages()
    ->limit(10)
    ->sortByLastEditedTime('ascending')
    ->query()
    ->asJson();
```
```

--------------------------------

### Sort Database Entries by Property and Timestamp

Source: https://notionforlaravel.com/docs/v1.1.0/notion-databases/sorting

Use `Sorting::propertySort` for custom properties and `Sorting::timestampSort` for timestamps. Add sorting objects to a Collection and apply with `sortBy`.

```php
use Illuminate\Support\Collection;
use FiveamCode\LaravelNotionApi\Query\Sorting;

$sortings = new Collection();

# Sort the entries by birth year first, after that by creation timestamp
$sortings->add(Sorting::propertySort("Birth year", "ascending"));
$sortings->add(Sorting::timestampSort("created_time", "ascending"));

Notion::database("8284f3ff77e24d4a939d19459e4d6bdc")
    ->sortBy($sortings) // sorts are optional
    ->query()
    ->asCollection()
    ->each(function ($entry) {
        echo $entry->getTitle() . PHP_EOL;
    });


// Returns the entries sorted by birth year and created_time from our Test Database (https://www.notion.so/8284f3ff77e24d4a939d19459e4d6bdc) and prints their names (title property)
```

--------------------------------

### Access Title Property

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/handle-properties

Retrieve rich text objects or plain text content for the title property.

```php
$titleProp->getRichText(); // returns `*\Entities\PropertyItems\RichText`
$titleProp->getPlainText(); // returns `string`
```

--------------------------------

### Create a Relation Property

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/handle-properties

Creates a relation property using an array of valid page UUIDs.

```php
$relations = ['page-id-1', 'page-id-2', 'page-id-3'];
$relationProperty = Relation::value($relations);
```

--------------------------------

### Fetch Block Children as Content

Source: https://notionforlaravel.com/docs/v1.1.0/notion-blocks/fetch-blocks

Retrieves only the content of block children, formatted as a collection.

```APIDOC
## Fetch Block Children as Content

### Description
Retrieves only the content representation of all child blocks of a given parent block. The result is returned as a collection of the blocks' content.

### Method
GET (implied by retrieval)

### Endpoint
`/api/blocks/{blockId}/children/content` (conceptual, actual implementation uses a facade)

### Parameters
#### Path Parameters
- **blockId** (string) - Required - The UUID of the parent block whose children's content is to be fetched.

### Request Example
```php
// Fetches children from a specific block as a collection of their content
Notion::block($blockId)->children()->asTextCollection();
```

### Response
#### Success Response (200)
- **Content Collection** (array) - A collection containing the content of each child block.

#### Response Example
```php
[
  "Content of child block 1",
  "Content of child block 2",
  // ... more content strings
]
```
```

--------------------------------

### Access Formula Property

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/handle-properties

Retrieve the formula result and its type.

```php
$formulaProp->getContent(); // returns `mixed`
$formulaProp->getFormulaType(); // returns `string`
```

--------------------------------

### Access Number Property

Source: https://notionforlaravel.com/docs/v1.1.0/notion-pages/handle-properties

Retrieve the numeric value as a float.

```php
$numberProp->getNumber(); // returns `float`
```

--------------------------------

### Accessing Base EntityCollection Properties

Source: https://notionforlaravel.com/docs/v1.1.0/basics/handling-results

Methods for retrieving all results as a Laravel Collection or JSON string, checking for more results, and accessing pagination cursors.

```php
# This can be any of the above mentioned EntityCollections
$entityCollection = new EntityCollection();

# Get all results as a `Illuminate\Support\Collection`
$collectionResult = $entityCollection->asCollection();

# Get all results as JSON string
$jsonResult = $entityCollection->asJson();

# Check if there are more results available within the query (pagination)
$hasMoreEntries = $entityCollection->hasMoreEntries();

# Get the next cursor for the next page of results (`FiveamCode\LaravelNotionApi\Query\StartCursor`)
$startCursor = $entityCollection->nextCursor();

# Get the raw result of the next cursor (as string)
$rawNextCursor = $entityCollection->nextCursorRaw();

# Retrieve the raw result of the Notion API
$entityCollection->getRawResponse();

```

--------------------------------

### Filtering and Sorting Database Queries

Source: https://notionforlaravel.com/docs/v1.1.0/notion-databases/query-database

Applies optional filters, sorting, and result limits to a database query.

```php
Notion::database($databaseId)
        ->filterBy($filters) // filters are optional
        ->sortBy($sortings) // sorts are optional
        ->limit(5) // limit is optional
        ->query()
        ->asCollection();
```

--------------------------------

### Fetch Specific Blocks

Source: https://notionforlaravel.com/docs/v1.1.0/notion-blocks/fetch-blocks

Fetches a specific block using its UUID. Returns a Block instance or a specific class if supported.

```APIDOC
## Fetch Specific Blocks

### Description
Fetches a specific block by its UUID. If the block has a specific implementation in the package, an instance of that class is returned; otherwise, a generic `Block::class` instance is returned.

### Method
GET (implied by retrieval)

### Endpoint
`/api/blocks/{blockId}` (conceptual, actual implementation uses a facade)

### Parameters
#### Path Parameters
- **blockId** (string) - Required - The UUID of the block to fetch.

### Request Example
```php
Notion::block($blockId)->retrieve();
```

### Response
#### Success Response (200)
- **Block Object** (object) - The retrieved block data.

#### Response Example
```json
{
  "id": "...",
  "type": "paragraph",
  "paragraph": {
    "rich_text": [
      {
        "type": "text",
        "text": {
          "content": "Example block content"
        }
      }
    ]
  }
}
```
```

--------------------------------

### Add Comment to a Notion Page

Source: https://notionforlaravel.com/docs/v1.1.0/notion-comments/create-comments

Add a comment to a specific Notion page by providing the `page_id`. Ensure the `Comment` object is instantiated first.

```php
Notion::comments()
    ->onPage('cbf6b0af6eaa45ca97159fa147ef6b17')
    ->create(Comment::fromText('Hello world'));
```

--------------------------------

### Fetch Block Children

Source: https://notionforlaravel.com/docs/v1.1.0/notion-blocks/fetch-blocks

Fetches children of a block, with options to limit results, return as Collection or JSON, and include unsupported blocks.

```APIDOC
## Fetch Block Children

### Description
Fetches the children of a block (e.g., a page or list) using the parent's UUID. Results can be retrieved as a Collection or JSON, with optional limits and the ability to include unsupported blocks.

### Method
GET (implied by retrieval)

### Endpoint
`/api/blocks/{blockId}/children` (conceptual, actual implementation uses a facade)

### Parameters
#### Path Parameters
- **blockId** (string) - Required - The UUID of the parent block whose children are to be fetched.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of children to retrieve.

### Request Example
```php
// Fetches children as a Collection with a limit
Notion::block($blockId)->limit(5)->children()->asCollection();

// Fetches children as JSON
Notion::block($blockId)->children()->asJson();

// Fetches children including unsupported blocks as a Collection
Notion::block($blockId)->children()->withUnsupported()->asCollection();
```

### Response
#### Success Response (200)
- **Children Data** (array|object) - A Collection or JSON representation of the block's children.

#### Response Example (Collection)
```php
// Example of a Collection response structure
[
  {
    "id": "...",
    "type": "paragraph",
    "paragraph": {
      "rich_text": [
        {
          "type": "text",
          "text": {
            "content": "Child block 1 content"
          }
        }
      ]
    }
  },
  // ... more children
]
```

#### Response Example (JSON)
```json
[
  {
    "id": "...",
    "type": "paragraph",
    "paragraph": {
      "rich_text": [
        {
          "type": "text",
          "text": {
            "content": "Child block 1 content"
          }
        }
      ]
    }
  },
  // ... more children
]
```
```

--------------------------------

### Add Database Properties using Bulk Way

Source: https://notionforlaravel.com/docs/v1.1.0/notion-databases/create-database

Defines database properties using the PropertyBuilder::bulk method, similar to Laravel migrations. Includes various property types like title, richText, number, date, select, and multiSelect. The 'Status' property is currently not supported.

```php
use FiveamCode\LaravelNotionApi\Builder\PropertyBuilder;

$selectOptions = [
    [
        'name' => 'testing',
        'color' => 'blue',
    ],
];

$multiSelectOptions = [
    [
        'name' => 'testing2',
        'color' => 'yellow',
    ],
];

$scheme = PropertyBuilder::bulk()
        ->title('MyTitle') // Title is required
        ->richText('MyText')
        ->checkbox('...') // Name of property is (mostly) optional
        // ->status() // WARNING: currently not supported
        ->number()
        ->date()
        ->url()
        ->email()
        ->phoneNumber()
        ->people()
        ->files()
        ->createdBy()
        ->createdTime()
        ->lastEditedBy()
        ->lastEditedTime()
        ->formula('Testing', 'prop("MultiSelect")')
        ->select('Select', $selectOptions)
        ->multiSelect('MultiSelect', $multiSelectOptions);
```

```php
$databaseEntity = Notion::databases()
        ->build()
        ->inline()
        ->title('Test Database')
        ->add($scheme)
        ->createInPage('1c682e7371ec4399be1cc015686c67c6');
```

--------------------------------

### Fetch Block Children as Collection

Source: https://notionforlaravel.com/docs/v1.1.0/notion-blocks/fetch-blocks

Retrieve the children of a block (like a page or list) as a Laravel Collection. An optional limit can be applied to the number of children fetched.

```php
# Fetches children from a specific block as a Collection
Notion::block($blockId)
       ->limit(5) // limit is optional
       ->children()
       ->asCollection();
```