### JSON fields search request example

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/00.prologue.md

Example POST request to search posts with filters, search, and sort on JSON fields using arrow notation.

```json
// (POST) https://myapp.com/api/posts/search
{
    "filters" : [
        {"field" : "options->visible", "operator" : ">=", "value" : true},
    ],
    "search" : {
        "value" : "Example post"
    },
    "sort" : [
        {"field" : "options->key", "direction" : "asc"},
    ]
}
```

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

### Create a resource

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/04.models.md

Use $query().store() with an object of attributes to create a new resource. The example creates a post with a title.

```typescript
const newPost = await Post.$query().store({
    title: 'New post'
});
```

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

### Install Orion using NPM

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/02.getting-started.md

Adds the @tailflow/laravel-orion package to your project using the npm package manager.

```bash
npm install @tailflow/laravel-orion --save
```

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

### Publish Orion Configuration

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/02.getting-started.md

Publishes the Orion configuration file using the orion-config tag. Run after installation.

```bash
php artisan vendor:publish --tag=orion-config
```

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

### ilike operator search request example

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/00.prologue.md

Example POST request using the ilike operator for case-insensitive search.

```json
// (POST) https://myapp.com/api/posts/search
{
    "filters" : [
        {"field" : "title", "operator" : "ilike", "value" : "example post"},
    ]
}
```

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

### Install Orion using Yarn

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/02.getting-started.md

Adds the @tailflow/laravel-orion package to your project using the Yarn package manager.

```bash
yarn add @tailflow/laravel-orion
```

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

### Hook method signature before 2.0

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/00.prologue.md

Example of hook method signature before 2.0, without parent entity.

```php
protected function afterSave(Request $request, Model $entity)
```

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

### Get and set primary key value

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/04.models.md

Use $setKey() and $getKey() to modify and retrieve the primary key value. The example sets the key to 4 and logs it along with the id attribute.

```typescript
const post = await Post.$query().find(5);

post.$setKey(4);

console.log(post.$getKey()); 
console.log(post.$attributes.id);
```

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

### Install Orion via Composer

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/02.getting-started.md

Adds the tailflow/laravel-orion package as a dependency. Composer v1 users may encounter an installation error; upgrade to Composer v2 or run 'composer require doctrine/dbal' first.

```bash
composer require tailflow/laravel-orion
```

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

### Refactor controller with buildFetchQuery, runFetchQuery, runIndexFetchQuery, and performStore

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/03.models.md

Refactored controller that overrides buildFetchQuery, runFetchQuery, runIndexFetchQuery, and performStore to fetch only published posts, select only specific columns, and conditionally fill attributes based on user role. This example shows how to customize query building, running, and storing for standard operations.

```php
<?php

namespace App\Http\Controllers\Api;

use App\Models\Post;
use Orion\Http\Controllers\Controller;

class PostsController extends Controller
{
    /**
     * Fully-qualified model class name
     */
    protected $model = Post::class; // or "App\Models\Post"

    /**
     * The list of attributes to select from db
     */
    protected $attributes = ['id', 'title', 'published_at'];

    /**
     * Builds Eloquent query for fetching entity(-ies).
     *
     * @param Request $request
     * @param array $requestedRelations
     * @return Builder
     */
    protected function buildFetchQuery(Request $request, array $requestedRelations): Builder
    {
        $query = parent::buildFetchQuery($request, $requestedRelations);

        $query->whereNotNull('published_at');

        return $query;
    }

    /**
     * Runs the given query for fetching entity.
     *
     * @param Request $request
     * @param Builder $query
     * @param int|string $key
     * @return Model
     */
    protected function runFetchQuery(Request $request, Builder $query, $key): Model
    {
        return $query->select($this->attributes)->findOrFail($key);
    }

    /**
     * Runs the given query for fetching entities in index method.
     *
     * @param Request $request
     * @param Builder $query
     * @param int $paginationLimit
     * @return LengthAwarePaginator
     */
    protected function runIndexFetchQuery(Request $request, Builder $query, int $paginationLimit): LengthAwarePaginator
    {
        return $query->paginate($paginationLimit, $this->attributes);
    }

    /**
     * Fills attributes on the given entity and stores it in database.
     *
     * @param Request $request
     * @param Model $post
     * @param array $attributes
     */
    protected function performStore(Request $request, Model $post, array $attributes): void
    {
        if ($this->resolveUser()->hasRole('admin')) {
            $post->forceFill($attributes);
        } else {
            $post->fill($attributes);
        }
        $post->save();
    }
}
```

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

### Search with scopes

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/04.models.md

Apply a scope by name and arguments using scope() before search(). The example uses the 'published' scope with the current timestamp.

```typescript
const posts = await Post.$query().scope('published', [Date.now()]).search(); 
```

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

### Apply filters to includes

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/06.search.md

JSON example showing how to specify filters for included relations. Supports nested filters with `nested` arrays and logical operators. Filters must be whitelisted in the `filterableBy` method.

```json
{
  "includes": [
    {
      "relation": "comments",
      "filters": [
        {"field" : "comments.created_at", "operator" : ">=", "value" : "2020-01-01"}
      ]
    },
    {
      "relation": "tags",
      "filters": [
        {"field" : "tags.created_at", "operator" : ">=", "value" : "2020-01-01"},
        {"nested": [
          {"field": "tags.id", "operator": "=", "value": 1},
          {"field": "tags.id", "operator": ">", "value": 20, "type": "or"}
        ]}
      ]
    }
  ]
}
```

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

### Register API routes (api.php)

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/index.md

Register model and relationship resources in your routes file using Orion's resource methods. This example registers a posts resource with soft deletes and a morphToMany relationship for tags.

```php
<?php

use Illuminate\Support\Facades\Route;
use Orion\Facades\Orion;
use App\Http\Controllers\PostsController;
use App\Http\Controllers\PostTagsController;

Route::group(['as' => 'api.'], function() {
    Orion::resource('posts', PostsController::class)->withSoftDeletes();
    Orion::morphToManyResource('posts', 'tags', PostTagsController::class);
});
```

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

### Hook method signature with parent entity

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/00.prologue.md

Example of a hook method signature that now receives a parent entity in relationship controllers.

```php
protected function afterSave(Request $request, Model $parentEntity, Model $entity)
```

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

### Example of using request class in store method

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/09.security.md

Shows how the request class is used in a store method signature, equivalent to how Orion uses it internally. This is a typical Laravel form request usage.

```php
public function store(CustomMessageRequest $request)
{
    ...
}
```

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

### Search request with sort descriptors

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/06.search.md

Example POST request to a search endpoint with a 'sort' property containing an array of sort descriptors. Each descriptor has 'field' and 'direction' properties, where 'direction' is either 'asc' or 'desc'.

```json
// (POST) https://myapp.com/api/posts/search
{
    "sort" : [
        {"field" : "name", "direction" : "asc"},
        {"field" : "options->key", "direction" : "asc"},
        {"field" : "meta.priority", "direction" : "desc"}
    ]
}
```

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

### Search with sorting

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/04.models.md

Sort results by attribute and direction using sortBy() before search(). The example sorts by 'published_at' in descending order.

```typescript
const posts = await Post.$query().sortBy('published_at', SortDirection.Desc).search(); 
```

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

### Customize primary key type

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/04.models.md

Override the fourth generic parameter to specify the primary key type. The example sets it to string and uses 'slug' as the key name.

```typescript
// post.ts

import {Model} from "@tailflow/laravel-orion/lib/model";

export class Post extends Model<{
    slug: string,
    title: string,
    body: string,
}, {}, {}, string>
{
    protected $keyName: string = 'slug';
}
```

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

### Search with filters

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/04.models.md

Filter results by attribute using filter() with an operator and value. The example filters by 'meta.source_id' equal to 'test-source'.

```typescript
const posts = await Post.$query().filter('meta.source_id', FilterOperator.Equal, 'test-source').search(); 
```

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

### Perform CRUD operations on a relation resource

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/05.relationships.md

Shows how to obtain a relation query builder by calling the relation method on a model instance, then perform CRUD operations like get() and store() on the relation resource.

```typescript
const post = Post.$query().find(5);

const comments = post.comments().get(); // retrieves a list of comments for post with id 5
const newComment = post.comments().store({body: 'Test comment'});
// etc.
```

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

### Request body with includes property

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/06.search.md

Example JSON request body for a search endpoint that includes the `includes` property. Each item specifies a relation and optionally a `limit` to cap the number of returned related entities.

```json
// (POST) https://myapp.com/api/posts/search
{
    "includes" : [
        {"relation" : "tags", "limit" : 10},
        {"relation" : "comments"}
    ]
}
```

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

### Request payload with aggregate filters

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/06.search.md

Example JSON payload showing how to apply filters to aggregates, including nested filters. Filters must be whitelisted in the `filterableBy` method on the controller.

```json
{
  "aggregates": [
    {
      "relation": "tags",
      "type": "count",
      "filters": [
        {"field" : "tags.created_at", "operator" : ">=", "value" : "2020-01-01"}
      ]
    },
    {
      "relation": "tags",
      "field": "stars",
      "type": "avg",
      "filters": [
        {"field" : "tags.created_at", "operator" : ">=", "value" : "2020-01-01"},
        {"nested": [
          {"field": "tags.id", "operator": "=", "value": 1},
          {"field": "tags.id", "operator": ">", "value": 10, "type": "or"}
        ]}
      ]
    }
  ]
}
```

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

### Define model attributes

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/04.models.md

Specify the attributes of a model by providing a generic type parameter to the Model class. The example defines a Post model with title and body attributes.

```typescript
// post.ts

import {Model} from "@tailflow/laravel-orion/lib/model";

export class Post extends Model<{
    title: string,
    body: string
}>
{
    
}
```

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

### Define allowed aggregates with relations and fields

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/06.search.md

Override the `aggregates` method in a controller to whitelist relations and fields that can be aggregated. This example allows aggregation on `user`, `user.team`, `user.profile`, and `meta`.

```php
<?php

namespace App\Http\Controllers\Api;

use Orion\Http\Controllers\Controller;

class PostsController extends Controller
{
    ...

    /**
    * The relations and fields that are allowed to be aggregated on a resource.
    *
    * @return array
    */
    public function aggregates() : array
    {
        return ['user', 'user.team', 'user.profile', 'meta'];
    }

    ...
}
```

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

### Define common and store validation rules

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/09.security.md

Extend Orion\Http\Requests\Request to define common rules for both store and update endpoints, and store-specific rules. Rules in storeRules overwrite commonRules for the same key. In this example, store requires both title and status, while update only requires title.

```php
<?php

namespace App\Http\Requests;

use Orion\Http\Requests\Request;

class PostRequest extends Request
{
    public function commonRules() : array
    {
        return [
            'title' => 'required'
        ];
    }

    public function storeRules() : array
    {
        return [
            'status' => 'required|in:draft,review'
        ];
    }
}
```

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

### Request payload with aggregates

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/06.search.md

Example JSON payload for a POST request to a search endpoint, including various aggregate types (count, exists, avg, sum, min, max) on the `tags` relation. Note that `count` and `exists` require only the `relation` field.

```json
// (POST) https://myapp.com/api/posts/search
{
    "aggregates" : [
        {"type" : "count", "relation" : "tags"},
        {"type" : "exists", "relation" : "tags"},
        {"type" : "avg", "relation" : "tags", "field": "stars"},
        {"type" : "sum", "relation" : "tags", "field": "stars"},
        {"type" : "min", "relation" : "tags", "field": "stars"},
        {"type" : "max", "relation" : "tags", "field": "stars"}
    ]
}
```

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

### Nested filters request JSON example

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/06.search.md

Shows the JSON body for a POST request to /api/posts/search using nested filters. The outer array contains a condition on 'created_at', then an 'or' group with a condition on 'options->visible' and an 'and' condition on 'meta.source_id'. The depth is limited to 1 by default; increase via 'search.max_nested_depth' in the config file.

```json
// (POST) https://myapp.com/api/posts/search
{
  "filters" : [
      {"field" : "created_at", "operator" : ">=", "value" : "2020-01-01"},
      {"type": "or", "nested" : [
        {"field" : "options->visible", "operator" : "=", "value" : true},
        {"type" : "and", "field" : "meta.source_id", "operator" : "in", "value" : [1,2,3]}
      ]}
  ]
}
```

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

### Customize policy classes for relation controller

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/09.security.md

Set the protected $policy and $parentPolicy variables on a relation controller to use specific policy classes for the relation entity and the parent entity. This example shows a relation controller for Team posts, using CustomPostPolicy for the relation and CustomTeamPolicy for the parent.

```php
<?php

namespace App\Http\Controllers\Api;

use App\Models\Team;
use App\Policies\CustomPostPolicy;
use App\Policies\CustomTeamPolicy;
use Orion\Http\Controllers\RelationController;

class TeamPostsController extends RelationController
{
     /**
     * @var string $model
     */
    protected $model = Team::class; // or "App\Models\Team"
    
    /**
     * Name of the relationship as it is defined on the Post model
     */
    protected $relation = 'posts';

    /**
     * @var string $parentPolicy
     */
    protected $parentPolicy = CustomTeamPolicy::class;

   /**
     * @var string $policy
     */
    protected $policy = CustomPostPolicy::class;
}
```

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

### Set API URL with Orion.init

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/03.configuration.md

Initializes the SDK with the API base URL. Use this before making any requests.

```typescript
Orion.init('https://your-api.test');
```

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

### Generate specs with custom path using --path option

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/11.specifications.md

Generates the specification file at a custom relative path. The path is relative to the storage/app directory.

```bash
php artisan orion:specs --path="specs/example.yaml"
```

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

### Define a typed model and perform CRUD operations

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/01.index.md

Initializes the SDK with an API URL and token, then defines a Post model with typed attributes. Shows how to retrieve, create, update, and delete posts using the $query() builder and model instance methods.

```typescript
import {Orion} from "@tailflow/laravel-orion/lib/orion";
import {Model} from "@tailflow/laravel-orion/lib/model";

Orion.init('https://your-api.test');
Orion.setToken('access-token-here');

export class Post extends Model<{
    title: string,
    body: string
}>
{
    public $resource(): string {
        return 'posts';
    }
}

// retrieve a list of posts
const posts = await Post.$query().get();

// search for posts
const posts = await Post.$query().lookFor('some value').search();

// create a post
const newPost = await Post.$query().store({
    title: 'New post' // <-- you get a nice autocompletion here, because the attributes are typed 
});
console.log(newPost.$attributes.title);  // <-- oh, and here as well

// retrieve a post
const post = await Post.$query().find(5);

// update a post
post.$attributes.title = 'Updated post';
await post.$save();
// or
await post.$save({title: 'Updated post'}); // <-- and here
// or
const updatedPost = await Post.$query().update(5, {
    title: 'Updated title' // <-- and, of course, here
});

// delete a post
const deletedPost = await Post.$query().delete(5);
// or
await post.$destroy();

// and more: search, relationship operations, etc.
```

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

### GET /api/users/{user}/posts

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/04.relationships.md

Retrieves a list of posts associated with the specified user.

```APIDOC
## GET /api/users/{user}/posts

### Description
Retrieves a list of posts associated with the specified user.

### Method
GET

### Endpoint
/api/users/{user}/posts

### Parameters
#### Path Parameters
- **user** (integer) - Required - The ID of the parent user.

### Response
#### Success Response (200)
- **data** (array) - List of post resources.

#### Response Example
{
  "data": []
}
```

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

### Search on deeply nested relations

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/00.prologue.md

Example of searchableBy method for deeply nested relation fields.

```php
public function searchableBy() : array
{
    return ['user.name', 'user.location.address.postalcode']; // postalcode field of the deeply nested user.location.address relation
}
```

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

### Search on one-level deep relation

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/00.prologue.md

Example of searchableBy method for a one-level deep relation field.

```php
public function searchableBy() : array
{
    return ['user.name']; // name field of the user relation
}
```

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

### Retrieve a list of resources

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/04.models.md

Use $query().get() to fetch all resources of the model.

```typescript
const posts = await Post.$query().get(); 
```

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

### GET /api/users/{user}/posts/{post}

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/04.relationships.md

Retrieves a specific post associated with the specified user.

```APIDOC
## GET /api/users/{user}/posts/{post}

### Description
Retrieves a specific post associated with the specified user.

### Method
GET

### Endpoint
/api/users/{user}/posts/{post}

### Parameters
#### Path Parameters
- **user** (integer) - Required - The ID of the parent user.
- **post** (integer) - Required - The ID of the post.

### Response
#### Success Response (200)
- **data** (object) - The post resource.

#### Response Example
{
  "data": {}
}
```

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

### Configure specs info and servers in orion.php

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/11.specifications.md

Configuration for the specs section in the orion.php config file. Populates the info and servers fields of the generated OpenAPI specification.

```php
'specs' => [
    'info' => [
        'title' => env('APP_NAME'),
        'description' => null,
        'terms_of_service' => null,
        'contact' => [
            'name' => null,
            'url' => null,
            'email' => null,
        ],
        'license' => [
            'name' => null,
            'url' => null,
        ],
            'version' => '1.0.0',
    ],
    'servers' => [
        ['url' => env('APP_URL').'/api', 'description' => 'Default Environment'],
    ],
],
```

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

### Set access token with Orion.init or setToken

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/03.configuration.md

Sets a static access token for authentication. Requires importing AuthDriver. Use the fourth argument of init or setToken.

```typescript
import {AuthDriver} from '@tailflow/laravel-orion/lib/drivers/default/enums/authDriver';

Orion.init('https://your-api.test', 'api', AuthDriver.Sanctum, 'test-access-token');
// or
Orion.setToken('test-access-token');
```

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

### Query the API with CRUD operations

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/02.getting-started.md

Shows the main query methods: $query().get() to list, lookFor().search() to search, store() to create, find() to retrieve, update() to modify, and delete() to delete. Also demonstrates saving attributes with $save(). Note: If using Sanctum, CSRF protection must be initialized first.

```typescript
// somewhere in your app

import {Post} from '../post.ts';

// retrieve a list of posts
const posts = await Post.$query().get();

// search for posts
const posts = await Post.$query().lookFor('some value').search();

// create a post
const newPost = await Post.$query().store({
    title: 'New post' // <-- you get a nice autocompletion here, because the attributes are typed 
});
console.log(newPost.$attributes.title);  // <-- oh, and here as well

// retrieve a post
const post = await Post.$query().find(5);

// update a post
post.$attributes.title = 'Updated post';
await post.$save();
// or
await post.$save({title: 'Updated post'}); // <-- and here
// or
const updatedPost = await Post.$query().update(5, {
    title: 'Updated title' // <-- and, of course, here
});

// delete a post
const deletedPost = await Post.$query().delete(5);
// or
await post.$destroy();
```

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

### Generate specs in YAML format using --format option

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/11.specifications.md

Generates the specification file in YAML format instead of the default JSON format.

```bash
php artisan orion:specs --format="yaml"
```

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

### POST /api/users/{user}/posts/batch

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/04.relationships.md

Creates multiple posts and associates them with the specified user.

```APIDOC
## POST /api/users/{user}/posts/batch

### Description
Creates multiple posts and associates them with the specified user.

### Method
POST

### Endpoint
/api/users/{user}/posts/batch

### Parameters
#### Path Parameters
- **user** (integer) - Required - The ID of the parent user.

#### Request Body
- **resources** (array) - Required - Array of post data to create.

### Request Example
{
  "resources": []
}

### Response
#### Success Response (201)
- **data** (array) - List of created post resources.

#### Response Example
{
  "data": []
}
```

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

### Return trashed resources with with_trashed

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/08.query-parameters.md

Returns all resources, including soft deleted ones, on index, search, and show endpoints of standard and relation resources.

```bash
(GET) https://myapp.com/api/posts?with_trashed=true
```

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

### Associate endpoint request payload

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/04.relationships.md

Example request payload for the associate endpoint. The only field is `related_key`, which is the ID of the post to associate with the user.

```json
// (POST) https://myapp.com/api/users/{user}/posts/associate
{
    "related_key" : 5
}
```

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

### Available endpoints for one-to-one relationship

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/04.relationships.md

Shows the generated API endpoints for a one-to-one relationship, including store, show, update, and destroy. The related resource key is optional in the URI.

```bash
+-----------+-------------------------------------------------+------------------------------------------+---------------------------------------------------------------------------+
| Method    | URI                                             | Name                                     | Action                                                                    |
+-----------+-------------------------------------------------+------------------------------------------+---------------------------------------------------------------------------+
| POST      | api/profiles/{profile}/image                    | api.profiles.relation.image.store        | App\Http\Controllers\Api\ProfileImageController@store                     |
| GET|HEAD  | api/profiles/{profile}/image/{image?}           | api.profiles.relation.image.show         | App\Http\Controllers\Api\ProfileImageController@show                      |
| PATCH|PUT | api/profiles/{profile}/image/{image?}           | api.profiles.relation.image.update       | App\Http\Controllers\Api\ProfileImageController@update                    |
| DELETE    | api/profiles/{profile}/image/{image?}           | api.profiles.relation.image.destroy      | App\Http\Controllers\Api\ProfileImageController@destroy                   |
+-----------+-------------------------------------------------+------------------------------------------+---------------------------------------------------------------------------+
```

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

### Configure Orion with API URL and access token

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/02.getting-started.md

Initializes the Orion SDK with your API endpoint and sets an access token for authentication. Must be called before making any API requests.

```typescript
import {Orion} from "@tailflow/laravel-orion/lib/orion";

Orion.init('https://your-api.test');
Orion.setToken('access-token-here');
```

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

### Access model attributes

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/04.models.md

After retrieving a model, access its attributes via the $attributes property. The example logs the title and body of a post with id 5.

```typescript
const post = await Post.$query().find(5);

console.log(post.$attributes.title);
console.log(post.$attributes.body);
```

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

### Nested filters pseudo expression

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/06.search.md

Represents the logical equivalent of the nested filters example in pseudo code. Not actual executable code, but illustrates how the conditions are combined with OR and AND.

```plaintext
(created_at >= "2020-01-01") OR (options->visible = true AND meta.source_id IN [1,2,3])
```

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

### Include relations with include

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/08.query-parameters.md

Requests related resources to be included in the response. Relations must be whitelisted first.

```bash
(GET) https://myapp.com/api/posts?include=user,meta
```

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

### POST /api/posts/batch

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/07.batch-operations.md

Creates multiple resources in a single request. The request body must contain a 'resources' array where each item is an object representing a resource to create.

```APIDOC
## POST /api/posts/batch

### Description
Creates multiple resources in a single request. The request body must contain a 'resources' array where each item is an object representing a resource to create.

### Method
POST

### Endpoint
/api/posts/batch

### Parameters
#### Request Body
- **resources** (array) - Required - An array of objects, each representing a resource to create.

### Request Example
{
    "resources" : [
        {
            "title" : "My Post 1",
            "body" : "Example body text"
        },
         {
            "title" : "My Post 2",
            "body" : "Example body text"
        }
    ]
}
```

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

### Create PostsController extending Orion Controller

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/02.getting-started.md

Initial controller skeleton that extends Orion\Http\Controllers\Controller. Required before adding the $model property.

```php
<?php

namespace App\Http\Controllers\Api;

use App\Models\Post;
use Orion\Http\Controllers\Controller;

class PostsController extends Controller
{

}
```

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

### Customize primary key attribute

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/04.models.md

Override the protected $keyName property to use a different attribute as the primary key. The example uses 'slug' instead of the default 'id'.

```typescript
// post.ts

import {Model} from "@tailflow/laravel-orion/lib/model";

export class Post extends Model<{
    slug: string,
    title: string,
    body: string,
}>
{
    protected $keyName: string = 'slug';
}
```

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

### Define a model controller (PostsController.php)

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/index.md

Create a controller extending Orion's base Controller and set the model property to the fully-qualified class name of your Eloquent model.

```php
<?php

namespace App\Http\Controllers\Api;

use App\Models\Post;
use Orion\Http\Controllers\Controller;

class PostsController extends Controller
{
    /**
    * Fully-qualified model class name
    */
    protected $model = Post::class; // or "App\Models\Post"
}
```

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

### Set API prefix with Orion.init or setPrefix

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/03.configuration.md

Changes the default API prefix (default is 'api'). Use the second argument of init or the setPrefix method.

```typescript
Orion.init('https://your-api.test', 'api/v1');
// or
Orion.setPrefix('api/v1');
```

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

### Define a relationship controller (PostTagsController.php)

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/index.md

Create a controller extending Orion's RelationController for a relationship. Set the model and the relation name as defined on the model.

```php
<?php

namespace App\Http\Controllers\Api;

use App\Models\Post;
use Orion\Http\Controllers\RelationController;

class PostTagsController extends RelationController
{
    /**
    * Fully-qualified model class name
    */
    protected $model = Post::class; // or "App\Models\Post"

    /**
    * Name of the relation as it is defined on the Post model
    */
    protected $relation = 'tags';
}
```

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

### Register resource with withSoftDeletes

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/03.models.md

Register a resource with soft delete support by calling withSoftDeletes() on the resource registration. This introduces restore and batchRestore endpoints.

```php
<?php

use Illuminate\Support\Facades\Route;
use Orion\Facades\Orion;

Route::group(['as' => 'api.'], function() {
    ...
    Orion::resource('posts', 'Api\PostsController')->withSoftDeletes();
    ...
});

```

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

### Route table generated by Orion::resource

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/03.models.md

Shows the routes created by Orion::resource for the posts resource, including standard CRUD endpoints, search, and batch operations. The table lists HTTP methods, URIs, route names, controller actions, and middleware.

```bash
+--------+-----------+-------------------------------------------------+----------------------------------------+---------------------------------------------------------------------------+-------------------------------------------------+
| Domain | Method    | URI                                             | Name                                   | Action                                                                    | Middleware                                      |
+--------+-----------+-------------------------------------------------+----------------------------------------+---------------------------------------------------------------------------+-------------------------------------------------+
...
|        | GET|HEAD  | api/posts                                       | api.posts.index                        | App\Http\Controllers\Api\PostsController@index                            | api                                             |
|        | POST      | api/posts/search                                | api.posts.search                       | App\Http\Controllers\Api\PostsController@index                            | api                                             |
|        | POST      | api/posts                                       | api.posts.store                        | App\Http\Controllers\Api\PostsController@store                            | api                                             |
|        | GET|HEAD  | api/posts/{post}                                | api.posts.show                         | App\Http\Controllers\Api\PostsController@show                             | api                                             |  
|        | PUT|PATCH | api/posts/{post}                                | api.posts.update                       | App\Http\Controllers\Api\PostsController@update                           | api                                             |
|        | DELETE    | api/posts/{post}                                | api.posts.destroy                      | App\Http\Controllers\Api\PostsController@destroy                          | api                                             |
|        | POST      | api/posts/batch                                 | api.posts.batchStore                   | App\Http\Controllers\Api\PostsController@batchStore                       | api                                             |
|        | PATCH     | api/posts/batch                                 | api.posts.batchUpdate                  | App\Http\Controllers\Api\PostsController@batchUpdate                      | api                                             |
|        | DELETE    | api/posts/batch                                 | api.posts.batchDestroy                 | App\Http\Controllers\Api\PostsController@batchDestroy                     | api                                             |
```

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

### PATCH pivot endpoint request payload

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/04.relationships.md

Example request payload for updating a pivot row. The payload contains a single `pivot` field whose properties correspond to pivot table columns to update.

```json
// (PATCH) https://myapp.com/api/users/{user}/roles/{role}/pivot
{
    "pivot" : { // properties correspond to the columns in pivot table
        "example_pivot_field" : "updated value",
        "another_pivot_field" : "new value"
        ...
    }
}
```

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

### Route list for restore endpoints

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/03.models.md

Route listing showing the restore and batchRestore endpoints added by withSoftDeletes. The restore endpoint is at api/posts/{post}/restore and the batch restore at api/posts/batch/restore.

```bash
+--------+-----------+-------------------------------------------------+----------------------------------------+---------------------------------------------------------------------------+-------------------------------------------------+
| Domain | Method    | URI                                             | Name                                   | Action                                                                    | Middleware                                      |
+--------+-----------+-------------------------------------------------+----------------------------------------+---------------------------------------------------------------------------+-------------------------------------------------+
...
|        | POST      | api/posts/{post}/restore                        | api.posts.restore                      | App\Http\Controllers\Api\PostsController@restore                          | api                                             |
|        | POST      | api/posts/batch/restore                         | api.posts.batchRestore                 | App\Http\Controllers\Api\PostsController@batchRestore                     | api                                             |

```

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

### Create a model controller extending Orion\Http\Controllers\Controller

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/03.models.md

Defines a controller for the Post model. The $model property must be set to the fully-qualified class name or its string equivalent. This controller is used to expose the model via API endpoints.

```php
<?php

namespace App\Http\Controllers\Api;

use App\Models\Post;
use Orion\Http\Controllers\Controller;

class PostsController extends Controller
{
    /**
     * Fully-qualified model class name
     */
    protected $model = Post::class; // or "App\Models\Post"
}
```

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

### Override resolveUser method for custom auth guard

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/09.security.md

Override the resolveUser method on a controller to change how the currently authenticated user is resolved. This example uses the 'sanctum' guard, but you can use any custom guard. By default, the 'api' guard is used.

```php
<?php

namespace App\Http\Controllers\Api;

use App\Models\Post;

class PostsController extends ApiController
{
    /**
     * @var string $model
     */
    protected $model = Post::class;

     /**
     * Retrieves currently authenticated user based on the guard.
     *
     * @return \Illuminate\Contracts\Auth\Authenticatable|null
     */
    public function resolveUser()
    {
        return Auth::guard('sanctum')->user();
    }
}
```

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

### Customize Axios instance with makeHttpClientUsing

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/03.configuration.md

Replaces the default HTTP client with a custom Axios instance. Allows adding interceptors or other customizations.

```typescript
import axios from 'axios';

Orion.makeHttpClientUsing(() => {
  const client = axios.create();

  client.interceptors.request.use(...);

  return client;
});
```

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

### POST api/posts/{post}/tags/batch

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/index.md

Create multiple tags and associate them with the specified post.

```APIDOC
## [POST] api/posts/{post}/tags/batch

### Description
Create multiple tags and associate them with the specified post.

### Method
POST

### Endpoint
api/posts/{post}/tags/batch

### Parameters
#### Path Parameters
- **post** (integer) - Required - The ID of the post.

#### Request Body
- **resources** (array) - Required - Array of tag objects.

### Request Example
{
  "resources": [
    {
      "name": "laravel"
    },
    {
      "name": "php"
    }
  ]
}

### Response
#### Success Response (201)
- **data** (array) - Array of created tag resources.

#### Response Example
{
  "data": [
    {
      "id": 1,
      "name": "laravel"
    },
    {
      "id": 2,
      "name": "php"
    }
  ]
}
```

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

### beforeSave hook to associate post with authenticated user

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/05.hooks.md

Use the `beforeSave` hook to associate the currently authenticated user with a model before it is saved, for example when a blog post is created. This avoids overriding the controller method. The method receives the `Request` and the model instance.

```php
<?php

namespace App\Http\Controllers\Api;

use App\Models\Post;
use Orion\Http\Requests\Request;
use Orion\Http\Controllers\Controller;

class PostsController extends Controller
{
    /**
     * @var string|null $model
     */
    protected $model = Post::class;

    /**
     * @param Request $request
     * @param Post $post
     */
    protected function beforeSave(Request $request, $post)
    {
        $post->user()->associate($request->user());
    }
}
```

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

### Authorize parent entities in relation policies

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/09.security.md

Relation operations pass the parent entity as an additional argument to policies. Use this to set up checks on whether a user is authorized to perform actions on a relation entity in the context of a given parent entity. The example shows PostPolicy and PostMetaPolicy, where the parent entity is passed as the third argument.

```php
class PostPolicy
{
    public function update($user, $post)
    {
        return $post->user_id === $user->id;
    }
}

class PostMetaPolicy
{
    public function update($user, $postMeta, $post) // <---- $post here is the parent entity
    {
        // please note that the check is performed against
        // the parent entity $post, not the relation entity $postMeta
        return Gate::forUser($user)->inspect('update', $post); 
    }
    
    public function create($user, $post)
    {
        return Gate::forUser($user)->inspect('update', $post);
    }
}
```

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

### Retrieve a single resource

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/04.models.md

Use $query().find() with the primary key value to fetch a specific resource.

```typescript
const post = await Post.$query().find(5);
```

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

### Define a basic Post model

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/02.getting-started.md

Creates a new model class extending the SDK's Model base class. The model can be left empty initially and attributes can be added later.

```typescript
// post.ts

import {Model} from "@tailflow/laravel-orion/lib/model";

export class Post extends Model {

}
```

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

### Aggregate relations and fields with with_count, with_exists, with_avg, with_sum, with_min, with_max

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/08.query-parameters.md

Requests aggregates for whitelisted relations and fields. Each query parameter returns a specific aggregate: count, exists, average, sum, min, or max.

```bash
(GET) https://myapp.com/api/posts?with_count=user,meta
(GET) https://myapp.com/api/posts?with_exists=user,meta
(GET) https://myapp.com/api/users?with_avg=posts.stars
(GET) https://myapp.com/api/users?with_sum=posts.stars
(GET) https://myapp.com/api/users?with_min=posts.stars
(GET) https://myapp.com/api/users?with_max=posts.stars
```

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

### POST /api/posts/search: JSON request payload with scopes, filters, search, sort, aggregates, and includes

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/06.search.md

Sends a POST request to the search endpoint with various query constraints. Use scopes, filters (including JSON and JSONB fields), search, sort, aggregates, and includes. The order of applying query constraints is fixed: scopes, filters, search, sort, includes, aggregates, regardless of property order in the payload.

```json
{
    "scopes" : [
        {"name" : "active"},
        {"name" : "whereCategory", "parameters" : ["my-category"]}
    ],
    "filters" : [
        {"field" : "created_at", "operator" : ">=", "value" : "2020-01-01"},
        {"field" : "options->visible", "operator" : ">=", "value" : true},
        {"type" : "or", "field" : "meta.source_id", "operator" : "in", "value" : [1,2,3]}
    ],
    "search" : {
        "value" : "Example post"
    },
    "sort" : [
        {"field" : "name", "direction" : "asc"},
        {"field" : "options->key", "direction" : "asc"},
        {"field" : "meta.priority", "direction" : "desc"}
    ],
    "aggregates": [
        {
          "relation": "tags",
          "type": "count",
          "filters": [
            {"field" : "tags.created_at", "operator" : ">=", "value" : "2020-01-01"}
          ]
        }
    ],
    "includes": [
        {
          "relation": "tags",
          "filters": [
            {"field" : "tags.created_at", "operator" : ">=", "value" : "2020-01-01"}
          ]
        }
    ]
}
```

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

### Include relations with with()

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/06.query-parameters.md

Use the with() method to include related resources in the response. Access them via $relations.

```typescript
const post = await Post.$query().with(['user', 'comments']).find(5); 

console.log(post.$relations.user);
console.log(post.$relations.comments);
```

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

### Merge existing specs with --path option

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/11.specifications.md

Merges existing custom OpenAPI specifications with the generated ones. The path is relative to the storage/app directory.

```bash
php artisan orion:specs --path="specs/existing-specs.json"
```

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

### Available endpoints for one-to-many relation resource

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/04.relationships.md

Lists the 11 endpoints generated for a one-to-many relation resource, including CRUD, search, associate, dissociate, and batch operations. The table shows the HTTP method, URI, route name, and controller action for each endpoint.

```bash
+-----------+-------------------------------------------------+----------------------------------------+---------------------------------------------------------------------------+
| Method    | URI                                             | Name                                   | Action                                                                    |
+-----------+-------------------------------------------------+----------------------------------------+---------------------------------------------------------------------------+
| GET|HEAD  | api/users/{user}/posts                          | api.users.relation.posts.index         | App\Http\Controllers\Api\UserPostsController@index                        |
| POST      | api/users/{user}/posts/search                   | api.users.relation.posts.search        | App\Http\Controllers\Api\UserPostsController@index                        |
| POST      | api/users/{user}/posts                          | api.users.relation.posts.store         | App\Http\Controllers\Api\UserPostsController@store                        |
| GET|HEAD  | api/users/{user}/posts/{post}                   | api.users.relation.posts.show          | App\Http\Controllers\Api\UserPostsController@show                         |
| PATCH     | api/users/{user}/posts/{post}                   | api.users.relation.posts.update        | App\Http\Controllers\Api\UserPostsController@update                       |
| PUT       | api/users/{user}/posts/{post}                   | api.users.relation.posts.update        | App\Http\Controllers\Api\UserPostsController@update                       |
| DELETE    | api/users/{user}/posts/{post}                   | api.users.relation.posts.destroy       | App\Http\Controllers\Api\UserPostsController@destroy                      |
| POST      | api/users/{user}/posts/associate                | api.users.relation.posts.associate     | App\Http\Controllers\Api\UserPostsController@associate                    |
| DELETE    | api/users/{user}/posts/{post}/dissociate        | api.users.relation.posts.dissociate    | App\Http\Controllers\Api\UserPostsController@dissociate                   |
| POST      | api/users/{user}/posts/batch                    | api.users.relation.posts.batchStore    | App\Http\Controllers\Api\UserPostsController@batchStore                   |
| PATCH     | api/users/{user}/posts/batch                    | api.users.relation.posts.batchUpdate   | App\Http\Controllers\Api\UserPostsController@batchUpdate                  |
| DELETE    | api/users/{user}/posts/batch                    | api.users.relation.posts.batchDestroy  | App\Http\Controllers\Api\UserPostsController@batchDestroy                 |
+-----------+-------------------------------------------------+----------------------------------------+---------------------------------------------------------------------------+
```

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

### Include trashed resources with withTrashed()

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/06.query-parameters.md

Use withTrashed() to include soft-deleted resources in the query results.

```typescript
const posts = await Post.$query().withTrashed().get();
```

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

### Set auth driver with AuthDriver.Sanctum

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/03.configuration.md

Configures the authentication driver. Requires importing AuthDriver from the SDK. Use the third argument of init or setAuthDriver.

```typescript
import {AuthDriver} from '@tailflow/laravel-orion/lib/drivers/default/enums/authDriver';

Orion.init('https://your-api.test', 'api', AuthDriver.Sanctum);
// or
Orion.setAuthDriver(AuthDriver.Sanctum);
```

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

### Initialize CSRF protection for Sanctum SPA

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/2.typescript-sdk/03.configuration.md

Initializes CSRF protection before making requests. Requires importing AuthDriver and calling Orion.csrf() before API calls.

```typescript
import {AuthDriver} from '@tailflow/laravel-orion/lib/drivers/default/enums/authDriver';

Orion.init('https://your-api.test');
Orion.setAuthDriver(AuthDriver.Sanctum);

try {
    await Orion.csrf();
    // now you can make requests to the API
    const posts = await Post.$query().get();
} catch (error) {
    console.error('Unable to retrieve CSRF cookie.');
}
```

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

### Set pagination limit via query parameter

Source: https://github.com/tailflow/laravel-orion-docs/blob/main/content/en/1.guide/08.query-parameters.md

Requests a specific number of entities per page. The limit query parameter always overwrites the controller's limit method but cannot exceed the maxLimit value.

```bash
(GET) https://myapp.com/api/posts?limit=30
```