### Install Orion SDK using NPM

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

Installs the Orion TypeScript SDK into your project using the Node Package Manager (NPM). This is the first step to start using the SDK.

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

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

### Create PostsController

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/1.guide/2.getting-started.md

Demonstrates the initial setup of a controller by extending Orion's base controller class.

```php
<?php

namespace App\Http\Controllers\Api;

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

class PostsController extends Controller
{

}
```

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

### Install Orion Package

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

Installs the Orion package into your Laravel project using Composer. This command adds the necessary dependency to your project's composer.json file.

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

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

### Install Laravel Orion via Composer

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/1.guide/2.getting-started.md

Installs the Laravel Orion package using Composer. Ensure your project meets the PHP and Laravel version requirements before running this command.

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

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

### Install Orion SDK using Yarn

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

Installs the Orion TypeScript SDK into your project using Yarn. This is an alternative to NPM for package management.

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

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

### Install Orion TypeScript SDK

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

Install the Orion SDK into your project using either NPM or Yarn package managers. This is the first step to integrate the SDK with your application.

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

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

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

### Initialize Orion SDK

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

Configure the Orion SDK by initializing it with your API's base URL and setting an authentication token. This setup is crucial before making any API calls.

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

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

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

### Define Orion Controller

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

Create a controller that extends Orion's base `Controller` class. This sets up the foundation for managing API resources.

```php
<?php

namespace App\Http\Controllers\Api;

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

class PostsController extends Controller
{

}
```

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

### List Artisan Routes

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

Use the `php artisan route:list` command to view all registered routes in your Laravel application, including those generated by Orion.

```bash
php artisan route:list
```

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

### Publish Orion Configuration

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

Publishes Orion's configuration files to your Laravel project. This allows you to customize the package's behavior by modifying the generated configuration files.

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

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

### Query API: Get List

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

Retrieves a list of resources from the API. This method fetches all records for the defined model's resource.

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

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

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

### Register Orion Resource Route

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/1.guide/2.getting-started.md

Registers a RESTful resource route for the 'posts' endpoint using Orion::resource in the API routes file.

```php
<?php

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

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

```

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

### Register Orion Resource Route

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

Register a resource route for your controller in the `api.php` file using `Orion::resource`. This automatically generates standard RESTful endpoints.

```php
<?php

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

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

```

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

### Orion Generated API Routes

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/1.guide/2.getting-started.md

Lists the standard RESTful API endpoints generated by Orion for managing a resource, including index, store, show, update, destroy, and batch operations.

```APIDOC
Resource: posts
Controller: App\Http\Controllers\Api\PostsController
Base URL: /api/posts

Methods:

GET api/posts
  Name: api.posts.index
  Description: Retrieves a list of posts, supports searching.
  Action: App\Http\Controllers\Api\PostsController@index
  Middleware: api

POST api/posts
  Name: api.posts.store
  Description: Creates a new post.
  Action: App\Http\Controllers\Api\PostsController@store
  Middleware: api

GET api/posts/{post}
  Name: api.posts.show
  Description: Retrieves a specific post by its ID.
  Action: App\Http\Controllers\Api\PostsController@show
  Middleware: api

PUT|PATCH api/posts/{post}
  Name: api.posts.update
  Description: Updates a specific post by its ID.
  Action: App\Http\Controllers\Api\PostsController@update
  Middleware: api

DELETE api/posts/{post}
  Name: api.posts.destroy
  Description: Deletes a specific post by its ID.
  Action: App\Http\Controllers\Api\PostsController@destroy
  Middleware: api

POST api/posts/batch
  Name: api.posts.batchStore
  Description: Creates multiple posts in a single request.
  Action: App\Http\Controllers\Api\PostsController@batchStore
  Middleware: api

PATCH api/posts/batch
  Name: api.posts.batchUpdate
  Description: Updates multiple posts in a single request.
  Action: App\Http\Controllers\Api\PostsController@batchUpdate
  Middleware: api

```

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

### Initialize Orion SDK

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

Configures the Orion SDK by providing the base URL of your API and setting an authentication token. This must be done before making any API calls.

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

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

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

### Query API: Find Resource

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

Retrieves a single resource by its ID from the API. This is used to fetch a specific record.

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

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

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

### Define Model Property in Controller

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/1.guide/2.getting-started.md

Specifies the fully-qualified Eloquent model class name that the controller will manage.

```php
<?php

namespace App\Http\Controllers\Api;

use Orion\Http\Controllers\Controller;

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

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

### Query API: Create Resource

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

Stores a new resource by sending data to the API. The SDK provides autocompletion for attributes based on the model definition.

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

// 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
```

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

### Orion Resource API Endpoints

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

Orion automatically generates a set of standard RESTful API endpoints for a registered resource. These endpoints allow for common CRUD operations and batch processing.

```APIDOC
Resource: posts
Controller: App\Http\Controllers\Api\PostsController
Model: App\Models\Post

Endpoints:

GET api/posts
  Name: api.posts.index
  Action: App\Http\Controllers\Api\PostsController@index
  Description: Retrieves a list of posts, supports filtering, sorting, and pagination.
  Middleware: api

POST api/posts/search
  Name: api.posts.search
  Action: App\Http\Controllers\Api\PostsController@index
  Description: Searches for posts based on provided criteria. Often uses the index method with search parameters.
  Middleware: api

POST api/posts
  Name: api.posts.store
  Action: App\Http\Controllers\Api\PostsController@store
  Description: Creates a new post.
  Middleware: api

GET|HEAD api/posts/{post}
  Name: api.posts.show
  Action: App\Http\Controllers\Api\PostsController@show
  Description: Retrieves a specific post by its ID.
  Middleware: api

PUT|PATCH api/posts/{post}
  Name: api.posts.update
  Action: App\Http\Controllers\Api\PostsController@update
  Description: Updates a specific post by its ID.
  Middleware: api

DELETE api/posts/{post}
  Name: api.posts.destroy
  Action: App\Http\Controllers\Api\PostsController@destroy
  Description: Deletes a specific post by its ID.
  Middleware: api

POST api/posts/batch
  Name: api.posts.batchStore
  Action: App\Http\Controllers\Api\PostsController@batchStore
  Description: Creates multiple posts in a single request.
  Middleware: api

PATCH api/posts/batch
  Name: api.posts.batchUpdate
  Action: App\Http\Controllers\Api\PostsController@batchUpdate
  Description: Updates multiple posts in a single request.
  Middleware: api

```

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

### Define a Model

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

Sets up a model class by extending the base `Model` provided by the SDK. This class represents a resource from your API and allows for type-safe attribute definition.

```typescript
// post.ts

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

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

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

### Query API: Search

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

Searches for resources in the API using a specified query term. This method allows for text-based searching across resource fields.

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

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

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

### Query API with Orion SDK

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

Perform various CRUD operations and searches on your API using the Orion TypeScript SDK. The SDK provides a fluent interface for common actions like fetching lists, finding specific records, creating, updating, and deleting data.

```typescript
// 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();
```

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

### Define a Model

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

Create a TypeScript class that extends the SDK's `Model` and defines its resource name and attributes. This allows the SDK to map API responses to typed objects.

```typescript
// post.ts

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

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

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

### Set Model Property in Controller

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

Specify the fully-qualified class name of the Eloquent model that the controller will manage by setting the `protected $model` property.

```php
<?php

namespace App\Http\Controllers\Api;

use Orion\Http\Controllers\Controller;

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

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

### DELETE api/posts/batch - Batch Destroy Posts API

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

This API endpoint facilitates the batch deletion of multiple posts. It is designed to handle bulk operations efficiently by accepting a collection of post identifiers, likely within the request body. The endpoint is mapped to the `batchDestroy` method of the `PostsController`.

```APIDOC
Endpoint: DELETE api/posts/batch

Route Name: api.posts.batchDestroy

Controller Action: App\Http\Controllers\Api\PostsController@batchDestroy

Middleware Group: api

Description:
  Allows for the deletion of multiple posts in a single request.

Parameters:
  (Implicitly via request body, e.g., JSON array of IDs)
  - ids: An array of post identifiers to be deleted.

Returns:
  (Typically a success status or count of deleted items)
  - 204 No Content on successful deletion.
  - 400 Bad Request if input is invalid.
  - 404 Not Found if one or more posts do not exist.

Example Usage:
  DELETE /api/posts/batch
  Request Body:
  {
    "ids": [1, 5, 10]
  }

Related Endpoints:
  - DELETE /api/posts/{post} - Delete a single post.
```

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

### API Controller Setup with Orion

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

Demonstrates creating an API controller by extending `Orion\Http\Controllers\Controller` and defining the `$model` property to specify the Eloquent model. This is the foundational step for exposing models via API.

```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"
}
```

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

### Query API: Delete Resource

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

Deletes a resource from the API either by using its ID or by calling a destroy method on the resource instance.

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

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

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

### Query API: Update Resource

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

Updates an existing resource either by modifying its attributes and saving, or by directly calling an update method with the resource ID and new data.

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

// update a post
const post = await Post.$query().find(5);
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 api/posts/batch - Batch Destroy Posts API

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/1.guide/2.getting-started.md

This API endpoint facilitates the batch deletion of multiple posts. It is designed to handle bulk operations efficiently by accepting a collection of post identifiers, likely within the request body. The endpoint is mapped to the `batchDestroy` method of the `PostsController`.

```APIDOC
Endpoint: DELETE api/posts/batch

Route Name: api.posts.batchDestroy

Controller Action: App\Http\Controllers\Api\PostsController@batchDestroy

Middleware Group: api

Description:
  Allows for the deletion of multiple posts in a single request.

Parameters:
  (Implicitly via request body, e.g., JSON array of IDs)
  - ids: An array of post identifiers to be deleted.

Returns:
  (Typically a success status or count of deleted items)
  - 204 No Content on successful deletion.
  - 400 Bad Request if input is invalid.
  - 404 Not Found if one or more posts do not exist.

Example Usage:
  DELETE /api/posts/batch
  Request Body:
  {
    "ids": [1, 5, 10]
  }

Related Endpoints:
  - DELETE /api/posts/{post} - Delete a single post.
```

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

### TypeScript SDK: Model Definition and API Operations

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/2.typescript-sdk/1.index.md

Demonstrates how to initialize the Orion SDK, define a typed model, and perform common API operations. It covers initializing the SDK with an API URL and token, defining models with typed attributes, and executing operations like retrieving lists, searching, creating, finding, updating, and deleting resources. The example highlights the benefits of typed attributes for autocompletion.

```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, relantionship operations, etc.
```

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

### Laravel Orion Controller Example

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/1.guide/3.models.md

This PHP code demonstrates a custom controller extending Orion's base controller to manage 'Post' resources. It shows how to define the model, specify attributes to select, and override methods like `buildFetchQuery` to add custom query logic (e.g., filtering by `published_at`) and `runFetchQuery` for specific fetching behavior.

```php
<?php

namespace App\Http\Controllers\Api;

use App\Models\Post;
use Orion\Http\Controllers\Controller;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Http\Request;
use Illuminate\Pagination\LengthAwarePaginator;

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();
    }
}

```

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

### Laravel Orion API Controller Example

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

Demonstrates a custom Laravel API controller using the Orion package. It shows how to define the model, specify attributes to select, and override methods like `buildFetchQuery` to apply custom logic, such as filtering by `published_at` and selecting specific columns.

```php
<?php

namespace App\Http\Controllers\Api;

use App\Models\Post;
use Orion\Http\Controllers\Controller;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Http\Request;
use Illuminate\Pagination\LengthAwarePaginator;

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();
    }
}

```

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

### PHP Example: Associating User in beforeSave Hook

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

Demonstrates using the `beforeSave` hook in an Orion API controller to associate the currently authenticated user with a newly created post.

```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());
    }
}
```

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

### Customize Index Fetch Query (Run)

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/1.guide/3.models.md

Demonstrates how to customize the execution of an Eloquent query for the `index` endpoint by overriding the `runIndexFetchQuery` method. This example selects specific columns and applies pagination.

```php
<?php

namespace App\Http\Controllers\Api;

use App\Models\Post;
use Orion\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Pagination\LengthAwarePaginator;

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

    ...

    /**
     * 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, ['id', 'title', 'published_at']);
    }
}

```

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

### Register One-to-One Relationship Route

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/1.guide/4.relationships.md

Example of registering a one-to-one relationship route for 'profiles' and 'image' using Orion's `hasOneResource` method in PHP. This sets up the controller to handle operations for the related resource.

```PHP
Orion::hasOneResource('profiles', 'image' , ProfileImageController::class);
```

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

### PHP: Example beforeSave Hook for User Association

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/1.guide/5.hooks.md

Demonstrates how to use the `beforeSave` hook in an Orion controller to associate the currently authenticated user with a model instance before it is saved to the database. This is a common pattern for tracking data ownership.

```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());
    }
}
```

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

### Register HasOne Resource Route

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

Example of registering a route for a one-to-one 'hasOne' relationship using Orion's resource registration method. This sets up the necessary routing for managing the related resource.

```php
Orion::hasOneResource('profiles', 'image' , ProfileImageController::class);
```

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

### Configure OpenAPI Info and Servers

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

The `info` and `servers` fields in the OpenAPI specification are populated from the `orion.php` configuration file. You can customize details like title, description, contact information, license, and server URLs.

```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 API URL

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/2.typescript-sdk/3.configuration.md

Initializes the Orion SDK with the base API endpoint URL. This is the first step in configuring the library.

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

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

### Register Many to Many Relationship

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/1.guide/4.relationships.md

Example of registering a many-to-many relationship between 'users' and 'roles' using Orion's belongsToMany method.

```php
Orion::belongsToManyResource('users', 'roles' , UserRolesController::class);
```

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

### TypeScript SDK: Model Definition and API Operations

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

Demonstrates how to initialize the Orion SDK, define a model with typed attributes, and perform various API operations including querying, searching, creating, finding, updating, and deleting resources. It showcases the SDK's autocompletion and type safety features.

```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, relantionship operations, etc.
```

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

### Retrieve a Resource

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/2.typescript-sdk/4.models.md

Fetch a single resource by its primary key using the `find()` method. This sends a GET request to the API for a specific resource.

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

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

### Set API URL

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

Initializes the Orion SDK with the base API endpoint URL. This is the first step in configuring the library.

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

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

### Retrieve a Resource

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

Fetch a single resource by its primary key using the `find()` method. This sends a GET request to the API for a specific resource.

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

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

### Publish Orion Configuration

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

Command to publish the Orion configuration file to your application. This allows customization of default settings, including auth guards and API specification details.

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

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

### Customize Index Fetch Query (Build)

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/1.guide/3.models.md

Illustrates how to customize the Eloquent query building process for the `index` endpoint by overriding the `buildIndexFetchQuery` method. This example filters posts to include only those that are published.

```php
<?php

namespace App\Http\Controllers\Api;

use App\Models\Post;
use Orion\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Illuminate\Database\Eloquent\Builder;

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

    /**
     * Builds Eloquent query for fetching entities in index method.
     *
     * @param Request $request
     * @param array $requestedRelations
     * @return Builder
     */
    protected function buildIndexFetchQuery(Request $request, array $requestedRelations): Builder
    {
        $query = parent::buildIndexFetchQuery($request, $requestedRelations);

        $query->whereNotNull('published_at');

        return $query;
    }
}

```

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

### Register Many-to-Many Relationship

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

Example of registering a many-to-many relationship resource in Laravel Orion using the `belongsToMany` method. This sets up the necessary routes for managing the relationship.

```PHP
Orion::belongsToManyResource('users', 'roles' , UserRolesController::class);
```

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

### Orion Resource Routes

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

Lists the standard API routes generated by `Orion::resource` for a resource controller. It covers common HTTP methods for index, store, show, update, destroy, and batch operations.

```APIDOC
+--------+-----------+-------------------------------------------------+----------------------------------------+---------------------------------------------------------------------------+-------------------------------------------------+
| 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                                             |
+--------+-----------+-------------------------------------------------+----------------------------------------+---------------------------------------------------------------------------+-------------------------------------------------+
```

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

### Get and Set Primary Key

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/2.typescript-sdk/4.models.md

Demonstrates how to retrieve the current primary key value of a model instance using `$getKey()` and how to set it using `$setKey()`. The primary key is typically an identifier for the resource.

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

post.$setKey(4);

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

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

### Get and Set Primary Key

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

Demonstrates how to retrieve the current primary key value of a model instance using `$getKey()` and how to set it using `$setKey()`. The primary key is typically an identifier for the resource.

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

post.$setKey(4);

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

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

### Returning Trashed Resources (Bash)

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/1.guide/8.query-parameters.md

Shows how to retrieve soft-deleted resources using query parameters. 'with_trashed=true' returns all resources including trashed ones, while 'only_trashed=true' returns only trashed resources.

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

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

### Generated API Resource Routes Table

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/1.guide/3.models.md

Lists the standard API routes generated by `Orion::resource` for a model, including index, search, store, show, update, destroy, and batch operations.

```bash
+--------+-----------+-------------------------------------------------+----------------------------------------+---------------------------------------------------------------------------+-------------------------------------------------+
| Domain | Method    | URI                                             | Name                                   | Action                                                                    | Middleware                                      |
+--------+-----------+-------------------------------------------------+----------------------------------------+---------------------------------------------------------------------------+-------------------------------------------------+
...
```

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

### Generate OpenAPI Specs

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

This command generates OpenAPI specifications for your project. It creates a `specs.json` file in the `storage/app/specs` directory by default. No code changes are required to use this feature.

```bash
php artisan orion:specs
```

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

### Customize Resource Key Name

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/1.guide/3.models.md

Shows how to override the default primary key (e.g., `id`) used for retrieving resources by implementing the `keyName` method in the controller. This example uses a `slug` field.

```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 name of the field used to fetch a resource from the database.
     *
     * @return string
     */
    protected function keyName(): string
    {
        return 'slug';
    }
}

```

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

### Generate OpenAPI Specifications

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

Automatically generate OpenAPI specifications for all Orion-powered endpoints by running the provided Artisan command. This feature simplifies API documentation and integration.

```bash
php artisan orion:specs
```

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

### API Search Payload - Filters Example

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/1.guide/6.search.md

This JSON payload demonstrates how to apply filters to API search requests. It shows the structure for specifying fields, operators (e.g., `>=`, `in`), values, and logical types (`and`, `or`) for granular data filtering.

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

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

### Create API Controller for Model

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/1.guide/3.models.md

Demonstrates creating a basic API controller that extends Orion's Controller and sets the `$model` property to a fully-qualified model class name.

```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"
}
```

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

### Laravel Orion Standard API Operations

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

Reference for standard operations methods used in Laravel Orion API controllers. This outlines the mapping between common API actions (index, store, show, update, destroy, restore) and the underlying `build`, `run`, and `perform` methods that handle query construction and data manipulation.

```APIDOC
Standard Operations Methods:

This section details the standard methods used by Orion controllers for common API operations. Each operation typically involves a `build` method for query construction, a `run` method for executing the query, and a `perform` method for data manipulation (like saving or updating).

- **index**:
  - `buildIndexFetchQuery`: Builds the Eloquent query for listing resources.
  - `runIndexFetchQuery`: Executes the query to fetch a paginated list of resources.
  - `perform`: Not typically used for index operations.

- **store**:
  - `buildStoreFetchQuery`: Builds the Eloquent query for fetching the resource to be updated or created.
  - `runStoreFetchQuery`: Executes the query to fetch the resource.
  - `performStore`: Fills attributes on a model and saves it to the database.

- **show**:
  - `buildShowFetchQuery`: Builds the Eloquent query for fetching a single resource by its key.
  - `runShowFetchQuery`: Executes the query to fetch a single resource.
  - `perform`: Not typically used for show operations.

- **update**:
  - `buildUpdateFetchQuery`: Builds the Eloquent query for fetching the resource to be updated.
  - `runUpdateFetchQuery`: Executes the query to fetch the resource.
  - `performUpdate`: Fills attributes on an existing model and saves it to the database.

- **destroy**:
  - `buildDestroyFetchQuery`: Builds the Eloquent query for fetching the resource to be deleted.
  - `runDestroyFetchQuery`: Executes the query to fetch the resource.
  - `performDestroy`: Deletes the specified resource.

- **restore**:
  - `buildRestoreFetchQuery`: Builds the Eloquent query for fetching the resource to be restored.
  - `runRestoreFetchQuery`: Executes the query to fetch the resource.
  - `performRestore`: Restores a soft-deleted resource.

Example Mapping:

| Method             | Build                  | Run                    | Perform        |
|--------------------|------------------------|------------------------|----------------|
| index              | buildIndexFetchQuery   | runIndexFetchQuery     | -              |
| store              | buildStoreFetchQuery   | runStoreFetchQuery     | performStore   |
| show               | buildShowFetchQuery    | runShowFetchQuery      | -              |
| update             | buildUpdateFetchQuery  | runUpdateFetchQuery    | performUpdate  |
| destroy            | buildDestroyFetchQuery | runDestroyFetchQuery   | performDestroy |
| restore            | buildRestoreFetchQuery | runRestoreFetchQuery   | performRestore |

```

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

### Configure API Prefix

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/2.typescript-sdk/3.configuration.md

Sets or changes the API prefix, which defaults to 'api'. This is useful for APIs with versioning or custom routing.

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

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

### Soft Deletes API Endpoints Example

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/1.guide/4.relationships.md

Illustrates the API endpoints generated for restoring soft-deleted resources when the `withSoftDeletes()` method is applied to an Orion relationship resource. This includes specific URIs and controller actions for single and batch restoration.

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

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

### Configure Authentication Driver

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/2.typescript-sdk/3.configuration.md

Sets the authentication driver for API requests. Supports drivers like Sanctum for token-based authentication.

```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);
```

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

### Disable Batch Operations (PHP)

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/1.guide/7.batch-operations.md

Provides PHP code examples for disabling specific batch operations or all batch operations for a resource using the Orion Laravel package. This is done via fluent methods on the resource definition.

```php
Orion::resource('posts', PostsController::class)->except(['batchStore', 'batchUpdate']);
```

```php
Orion::resource('posts', PostsController::class)->withoutBatch();
```

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

### Sanctum Integration for SPAs

Source: https://github.com/tailflow/laravel-orion-docs-new/blob/main/content/v1.x/2.typescript-sdk/3.configuration.md

Demonstrates how to integrate with Laravel Sanctum for Single Page Applications, including CSRF protection and making authenticated requests.

```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.');
}
```