### Passport Installation Output

Source: https://github.com/apiato/documentation/blob/master/docs/security/authentication.mdx

Example output showing the generated Client IDs and secrets after running the installation command.

```text
Personal access client created successfully.
Client ID: 1
Client secret: Mo45lC2zhZWcMfDGmCbsw1OfasdCrc3wqQAeeYAO
Password grant client created successfully.
Client ID: 2
Client secret: nu8B2npfoR4hP6sWHaf90EvWUFe2EDYyJXGnCrso
```

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

### Install Dependencies

Source: https://github.com/apiato/documentation/blob/master/README.md

Run this command to install all project dependencies.

```bash
$ yarn
```

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

### Start Development Server

Source: https://github.com/apiato/documentation/blob/master/README.md

Initiates a local development server with live reloading enabled.

```bash
$ yarn start
```

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

### Install Passport Keys

Source: https://github.com/apiato/documentation/blob/master/docs/getting-started/installation.mdx

Generates encryption keys and clients required for secure access token generation.

```bash
php artisan passport:install
```

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

### Example user resource JSON structure

Source: https://github.com/apiato/documentation/blob/master/docs/the-basics/response.mdx

A sample JSON response structure for a user resource.

```json
{
  "data": {
    "type": "User",
    "id": "0one37vjk49rp5ym",
    "email": "gandalf@the.grey",
    "products": {
      "data": [
        {
          "type": "Product",
          "id": "bmo7y84xpgeza06k",
          "status": "pending"
        },
        {
          "type": "Product",
          "id": "o0wzxbg0q4k7jp9d",
          "status": "fulfilled"
        }
      ]
    },
    "store": {
      "data": {
        "type": "Store",
        "id": "r6lbekg8rv5ozyad"
      }
    },
    "recipients": {
      "data": [
        {
          "type": "Recipient",
          "id": "r6lbekg8rv5ozyad",
          "contact": {
            "data": {
              "type": "Contact",
              "address": "123 Main St",
              "city": "Gotham"
            }
          }
        }
      ]
    }
  }
}
```

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

### Registration Response Example

Source: https://github.com/apiato/documentation/blob/master/docs/security/registration.mdx

The expected JSON response structure after a successful user registration.

```json
{
  "data": {
    "type": "User",
    "id": "XbPW7awNkzl83LD6",
    "name": null,
    "email": "john@doe.com",
    "email_verified_at": null,
    "gender": null,
    "birth": null
  },
  "meta": {
    "include": [
        "roles",
        "permissions"
    ],
    "custom": []
  }
}
```

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

### Install ApiDocJs dependencies

Source: https://github.com/apiato/documentation/blob/master/docs/getting-started/installation.mdx

Install the necessary dependencies for documentation generation using NPM.

```bash
npm install
```

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

### Install Documentation Generator Container

Source: https://github.com/apiato/documentation/blob/master/docs/pacakges/documentation.mdx

Install the Apiato documentation generator package via Composer.

```shell
composer require apiato/documentation-generator-container
```

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

### Search Query Parameters

Source: https://github.com/apiato/documentation/blob/master/docs/components/optional-components/repository/repositories.mdx

Examples of using the search parameter in GET requests.

```text
?search=John
?search=name:John
?search=name:John%20Doe
```

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

### Install ApiDocJs dependency

Source: https://github.com/apiato/documentation/blob/master/docs/pacakges/documentation.mdx

Install the required ApiDocJs tool in the project directory.

```shell
npm install apidoc
```

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

### DataArraySerializer response examples

Source: https://github.com/apiato/documentation/blob/master/docs/components/main-components/transformers.mdx

Examples of JSON output using the default DataArraySerializer.

```json
{
  "data": {
    "type": "User",
    "id": "XbPW7awNkzl83LD6",
    "name": "Mohammad Alavi"
  }
}
```

```json
{
  "data": [ ... ],
  "meta": {
    "include": [
      "xxx",
      "yyy"
    ],
    "custom": [],
    "pagination": {
      "total": 999,
      "count": 999,
      "per_page": 999,
      "current_page": 999,
      "total_pages": 999,
      "links": {
        "next": "http://api.apiato.test/v1/accounts?page=999"
      }
    }
  }
}
```

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

### Example request with field filtering

Source: https://github.com/apiato/documentation/blob/master/docs/the-basics/response.mdx

A URL query string demonstrating how to filter specific fields in the response.

```text
api.apiato.test/v1/users?fields[User]=type,email,products,recipients&fields[Product]=status&fields[Recipient]=id,contact&fields[Contact]=address,city
```

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

### Sorting and Ordering Parameters

Source: https://github.com/apiato/documentation/blob/master/docs/components/optional-components/repository/repositories.mdx

Examples of URL query parameters for sorting data by field and direction.

```text
?orderBy=id&sortedBy=asc
```

```text
?orderBy=created_at&sortedBy=desc
?orderBy=name&sortedBy=asc
```

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

### Request Relationships via Query Parameters

Source: https://github.com/apiato/documentation/blob/master/docs/components/main-components/transformers.mdx

Examples of using query parameters to request specific or nested relationships.

```text
api.apiato.test/v1/users?include=roles
```

```text
api.apiato.test/v1/users?include=roles,avatar
```

```text
api.apiato.test/v1/users?include=avatar,avatar.image
```

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

### Define API Routes

Source: https://github.com/apiato/documentation/blob/master/docs/components/main-components/routes.mdx

Examples of route definitions mapped to their corresponding generated API endpoints.

```php
Route::post('orders', CreateOrderController::class);
```

```php
Route::post('orders', AnotherCreateOrderController::class);
```

```php
Route::get('orders', ListOrdersController::class);
```

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

### Include a container in composer.json

Source: https://github.com/apiato/documentation/blob/master/docs/pacakges/readme.md

Add the vendor/project dependency to your project's composer.json file to enable installation via Composer.

```json
{
  "require": {
    "apiato/some-container": "^2.0.1"
  }
}
```

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

### Action Calling Multiple Tasks

Source: https://github.com/apiato/documentation/blob/master/docs/components/main-components/actions.md

Example of an Action class that injects and executes multiple tasks within its run method.

```php
use App\Ship\Parents\Actions\Action as ParentAction;

class DemoAction extends ParentAction
{
    public function __construct(
        private readonly DemoATask $demoATask,
        private readonly DemoBTask $demoBTask
    ) {
    }
    
    public function run($xxx, $yyy, $zzz): void
    {
        $foo = $this->demoATask->run($xxx, $yyy);
        $bar = $this->demoBTask->run($zzz);
    }
}
```

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

### Create a new Apiato project

Source: https://github.com/apiato/documentation/blob/master/docs/getting-started/installation.mdx

Use this command to initialize a new project directory named example-app using Composer.

```bash
composer create-project apiato/apiato example-app
```

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

### Initialize Apiato Configuration

Source: https://github.com/apiato/documentation/blob/master/docs/digging-deeper/advance-configuration.mdx

Use the configure method in the bootstrap file to initialize the application builder.

```php
$apiato = Apiato::configure(basePath: '/path/to/app')->create();
```

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

### Available Apiato Make Commands

Source: https://github.com/apiato/documentation/blob/master/docs/the-basics/code-generator.md

A comprehensive list of commands used to scaffold various container components.

```bash
php artisan apiato:make:action           Create a Action file for a Container
php artisan apiato:make:configuration    Create a Configuration file for a Container
php artisan apiato:make:container        Create a Container for apiato from scratch
php artisan apiato:make:container:api    Create a Container for apiato from scratch (API Part)
php artisan apiato:make:container:web    Create a Container for apiato from scratch (WEB Part)
php artisan apiato:make:controller       Create a controller for a container
php artisan apiato:make:event            Create a new Event class and its corresponding Listener
php artisan apiato:make:exception        Create a new Exception class
php artisan apiato:make:factory          Create a new Model Factory class for a given Model
php artisan apiato:make:job              Create a new Job class
php artisan apiato:make:listener         Create a new Event Listener class
php artisan apiato:make:mail             Create a new Mail class
php artisan apiato:make:middleware       Create a new Middleware class
php artisan apiato:make:migration        Create an "empty" migration file for a Container
php artisan apiato:make:model            Create a new Model class
php artisan apiato:make:notification     Create a new Notification class
php artisan apiato:make:policy           Create a new Policy class
php artisan apiato:make:provider         Create a Service Provider for a Container
php artisan apiato:make:readme           Create a README file for a Container
php artisan apiato:make:repository       Create a new Repository class
php artisan apiato:make:request          Create a new Request class
php artisan apiato:make:route            Create a new Route class
php artisan apiato:make:seeder           Create a new Seeder class
php artisan apiato:make:subaction        Create a new SubAction class
php artisan apiato:make:task             Create a Task file for a Container
php artisan apiato:make:test:functional  Create a Functional Test file.
php artisan apiato:make:test:testcase    Create the TestCase file.
php artisan apiato:make:test:unit        Create a Unit Test file.
php artisan apiato:make:transformer      Create a new Transformer class for a given Model
php artisan apiato:make:value            Create a new Value class
```

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

### JSON Request Payload

Source: https://github.com/apiato/documentation/blob/master/docs/components/main-components/requests.md

Example JSON structure for a request to be sanitized.

```json
{
  "data": {
    "name": "Demo",
    "description": "Some description",
    "is_private": false,
    "address": "",
    "foo": {
      "number": 1,
      "bar": "bar"
    }
  },
  "meta": "some meta data"
}
```

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

### Run Database Migrations

Source: https://github.com/apiato/documentation/blob/master/docs/getting-started/installation.mdx

Executes migrations to create the necessary database tables.

```bash
php artisan migrate
```

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

### Configure Repositories

Source: https://github.com/apiato/documentation/blob/master/docs/digging-deeper/advance-configuration.mdx

Use withRepositories to define custom logic for binding models to repositories.

```php
Apiato::configure()
    ->withRepositories(
        function (\Apiato\Foundation\Configuration\Repository $repository) {
            $repository->resolveModelNameUsing(function (string $repositoryName) {
                return $modelClassName;
            });
        },
    );
```

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

### Example JSON Response with Includes

Source: https://github.com/apiato/documentation/blob/master/docs/components/main-components/transformers.mdx

The resulting JSON structure when a relationship is included in the response.

```json
{
  "data": [
    {
      "type": "User",
      "id": "0one37vjk49rp5ym",
      "roles": [
        {
          "type": "Role",
          "id": "bmo7y84xpgeza06k"
        }
      ]
    }
  ]
}
```

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

### Generate API documentation

Source: https://github.com/apiato/documentation/blob/master/docs/pacakges/documentation.mdx

Execute the command to generate documentation based on the defined DocBlocks.

```shell
php artisan apiato:apidoc
```

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

### Generate a container readme

Source: https://github.com/apiato/documentation/blob/master/docs/architecture-concepts/container.md

Use this command to create a readme.md file for a specific container.

```bash
php artisan apiato:make:readme
```

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

### Configure Views

Source: https://github.com/apiato/documentation/blob/master/docs/digging-deeper/advance-configuration.mdx

Use withViews to register view paths and define custom namespace building logic for templates.

```php
Apiato::configure()
    ->withViews(
        function (\Apiato\Foundation\Configuration\View $view) {
            $view->loadFrom(
                shared_path('Views'),
                shared_path('Mails/Templates'),
                '/app/Containers/ExampleSection/ExampleContainer/UI/WEB/Views',
            );

            // Custom namespace builder
            $view->buildNamespaceUsing(function (string $path) {
                return $namespace;
            });
        },
    );
```

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

### Create SQLite Database File

Source: https://github.com/apiato/documentation/blob/master/docs/getting-started/installation.mdx

Initializes an empty SQLite database file within the application's database directory.

```bash
touch database/database.sqlite
```

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

### Generate a repository using Artisan

Source: https://github.com/apiato/documentation/blob/master/docs/components/optional-components/repository/repositories.mdx

Use this command to interactively create a new repository within the appropriate container directory.

```bash
php artisan apiato:make:repository
```

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

### API ID Input Formats

Source: https://github.com/apiato/documentation/blob/master/docs/security/hash-id.mdx

Examples of how hashed IDs are passed to the API via different request methods.

```text
/items/XbPW7awNkzl83LD6
```

```text
/items?id=XbPW7awNkzl83LD6
```

```json
{
    "id": "XbPW7awNkzl83LD6"
}
```

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

### Create Admin User

Source: https://github.com/apiato/documentation/blob/master/docs/getting-started/installation.mdx

Launches an interactive command to create a new administrator user.

```bash
php artisan apiato:create:admin
```

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

### Build Static Content

Source: https://github.com/apiato/documentation/blob/master/README.md

Compiles the project into static files located in the build directory.

```bash
$ yarn build
```

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

### Configure Fractal Includes

Source: https://github.com/apiato/documentation/blob/master/docs/components/main-components/transformers.mdx

Set global include settings in the config/fractal.php file.

```php
'auto_includes' => [
    'enabled' => true,
    'request_key' => 'include',
],
```

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

### Define validation rules in a Request class

Source: https://github.com/apiato/documentation/blob/master/docs/components/main-components/requests.md

Example of defining specific validation rules for user registration fields within a Request class.

```php
use App\Ship\Parents\Requests\Request as ParentRequest;

class RegisterUserRequest extends ParentRequest
{
    public function rules(): array
    {
        return [
            'email'    => 'required|email|max:200|unique:users,email',
            'password' => 'required|min:20|max:300',
            'name'     => ['required', 'min:2', 'max:400'],
        ];
    }

}
```

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

### Registering Apps in Configuration

Source: https://github.com/apiato/documentation/blob/master/docs/the-basics/apps.md

Define application classes and their base URLs within the apiato.php configuration file.

```php
'apps' => [
    'web' => [
        'class' => \App\Ship\Apps\Web::class,
        'url' => env('WEB_APP_URL', 'https://myapp.com'),
    ],
    'mobile' => [
        'class' => \App\Ship\Apps\Mobile::class,
        'url' => env('MOBILE_APP_URL', 'https://myapp.test'),
    ],
],
```

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

### List Actions Command

Source: https://github.com/apiato/documentation/blob/master/versioned_docs/version-13.x/components/main-components/actions.md

Use this command to retrieve a list of all existing Actions in the application.

```shell
php artisan apiato:list:actions
```

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

### Configure Base Path

Source: https://github.com/apiato/documentation/blob/master/docs/digging-deeper/advance-configuration.mdx

Initializes the builder with a specific base path, or defaults to environment variables if omitted.

```php
$builder = Apiato::configure('/path/to/app');
```

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

### Apply pagination to a repository

Source: https://github.com/apiato/documentation/blob/master/docs/components/optional-components/repository/repositories.mdx

Use the paginate method on a repository instance to enable automatic pagination.

```php
{
    $this->userRepository->paginate();
}
```

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

### View the configuration directory structure

Source: https://github.com/apiato/documentation/blob/master/docs/components/optional-components/configs.mdx

Standard directory layout for container-specific and global ship configurations.

```markdown
app
├── Containers
│   └── Section
│       └── Container
│           └── Configs
│               ├── section-container.php
│               ├── another.php
│               └── ...
├── Ship
│   └── Configs
│       ├── another-thing.php
│       ├── and-another.php
│       └── ...
└── config
    ├── app.php
    └── ...
```

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

### Configure Repository Caching

Source: https://github.com/apiato/documentation/blob/master/docs/components/optional-components/repository/repositories.mdx

Enable caching for repositories using the configuration file or environment variables.

```php
'cache' => [
    'enabled' => true,
],
```

```dotenv
ELOQUENT_QUERY_CACHE=true
```

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

### Generate a Controller

Source: https://github.com/apiato/documentation/blob/master/docs/components/main-components/controllers.md

Use the artisan command to interactively create a new controller.

```bash
php artisan apiato:make:controller
```

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

### Configure Service Providers

Source: https://github.com/apiato/documentation/blob/master/docs/digging-deeper/advance-configuration.mdx

Use withProviders to define custom provider loading paths, replacements, merges, or exclusions.

```php
Apiato::configure()
    ->withProviders(
        function (\Apiato\Foundation\Configuration\Provider $provider) {
            $provider->loadFrom(
                shared_path('Providers'),
                '/app/Containers/ExampleSection/ExampleContainer/Providers',
            );

            $provider->replace([
                OldProvider::class => NewProvider::class,
            ]);

            $provider->merge([
                CustomProvider::class,
            ]);

            $provider->except([
                UnwantedProvider::class,
            ]);
        },
    );
```

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

### Finalize Configuration

Source: https://github.com/apiato/documentation/blob/master/docs/digging-deeper/advance-configuration.mdx

Call create() to finalize the configuration chain and return the Apiato instance.

```php
$apiato = Apiato::configure()->create();
```

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

### Retrieving App Instance and URLs

Source: https://github.com/apiato/documentation/blob/master/docs/the-basics/apps.md

Access the current application instance and its associated URL methods using the AppFactory.

```php
$app = AppFactory::current();

$app->url();
$app->verifyEmailUrl();
$app->resetPasswordUrl();
```

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

### Configure executable path

Source: https://github.com/apiato/documentation/blob/master/docs/pacakges/documentation.mdx

Update the vendor-documentation.php config file to point to the correct apidoc executable.

```php
/*
|--------------------------------------------------------------------------
| Executable
|--------------------------------------------------------------------------
|
| Specify how you run or access the `apidoc` tool on your machine.
|
*/

'executable' => 'node_modules/.bin/apidoc',
// 'executable' => 'apidoc',
```

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

### Generate Events and Listeners via Artisan

Source: https://github.com/apiato/documentation/blob/master/docs/components/optional-components/events.mdx

Use these commands to scaffold new event and listener classes within the Apiato structure.

```bash
php artisan apiato:make:event
php artisan apiato:make:listener
```

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

### Generate a Service Provider

Source: https://github.com/apiato/documentation/blob/master/docs/components/optional-components/service-providers.mdx

Use the artisan command to create a new service provider within the Apiato structure.

```bash
php artisan apiato:make:provider
```

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

### Generate a new configuration file

Source: https://github.com/apiato/documentation/blob/master/docs/components/optional-components/configs.mdx

Use the artisan command to interactively create a new configuration file within the project.

```bash
php artisan apiato:make:configuration
```

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

### Generate a Factory

Source: https://github.com/apiato/documentation/blob/master/docs/components/optional-components/factories.mdx

Use the artisan command to interactively create a new factory file.

```bash
php artisan apiato:make:factory
```

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

### Configure SQLite in .env

Source: https://github.com/apiato/documentation/blob/master/docs/getting-started/installation.mdx

Updates the database connection settings in the .env file to use SQLite instead of MySQL.

```diff
+ DB_CONNECTION=sqlite
- DB_CONNECTION=mysql
- DB_HOST=127.0.0.1
- DB_PORT=3306
- DB_DATABASE=homestead
- DB_USERNAME=homestead
- DB_PASSWORD=secret
```

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

### List existing tasks

Source: https://github.com/apiato/documentation/blob/master/docs/components/main-components/tasks.md

Use the artisan command to retrieve a list of all tasks currently defined in the application.

```shell
php artisan apiato:list:tasks
```

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

### Refactor Service Provider Registration

Source: https://github.com/apiato/documentation/blob/master/docs/prologue/upgrade-guide.mdx

Demonstrates moving from property-based registration to explicit register method calls.

```php
// before
public array $serviceProviders = [
    ThirdPartyServiceProvider::class,
];

public array $aliases = [
    'something' => ThirdPartyServiceProvider::class,
];

// after
public function register(): void
{
    // Reminder: providers under Containers or Ship are autoloaded
    // and don't need to be registered manually.
    $this->app->register(ThirdPartyServiceProvider::class);
    $this->app->alias(ThirdPartyServiceProvider::class, 'something');
}
```

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

### Generate middleware using Artisan

Source: https://github.com/apiato/documentation/blob/master/docs/components/optional-components/middleware.md

Use the interactive command to scaffold new middleware files within the project structure.

```bash
php artisan apiato:make:middleware
```

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

### Generate a Policy

Source: https://github.com/apiato/documentation/blob/master/docs/components/optional-components/policies.md

Use the interactive artisan command to create a new policy file.

```bash
php artisan apiato:make:policy
```

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

### Create Password Grant Client

Source: https://github.com/apiato/documentation/blob/master/docs/security/authentication.mdx

Use this Artisan command to generate a password grant client for your application.

```bash
php artisan passport:client --password
```

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

### POST /register

Source: https://github.com/apiato/documentation/blob/master/docs/security/registration.mdx

Registers a new user by providing an email address and password.

```APIDOC
## POST /register

### Description
Registers a new user in the system using email and password credentials.

### Method
POST

### Endpoint
/v1/register

### Request Body
- **email** (string) - Required - The user's email address.
- **password** (string) - Required - The user's password.

### Request Example
{
  "email": "gandalg@the.grey",
  "password": "password"
}

### Response
#### Success Response (200)
- **data** (object) - The created user object.
- **meta** (object) - Metadata including includes and custom fields.

#### Response Example
{
  "data": {
    "type": "User",
    "id": "XbPW7awNkzl83LD6",
    "name": null,
    "email": "john@doe.com",
    "email_verified_at": null,
    "gender": null,
    "birth": null
  },
  "meta": {
    "include": [
        "roles",
        "permissions"
    ],
    "custom": []
  }
}
```

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

### Publish configuration files

Source: https://github.com/apiato/documentation/blob/master/docs/pacakges/documentation.mdx

Publish the package configuration to the application's config directory.

```shell
php artisan vendor:publish
```

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

### View Directory Structure

Source: https://github.com/apiato/documentation/blob/master/docs/components/main-components/views.mdx

The standard file system hierarchy for container-specific views.

```markdown
app
└── Containers
    └── Section
        └── Container
            └── UI
                └── WEB
                    └── Views
                        ├── view-a.php
                        ├── view-b.php
                        └── ...
```

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

### Generate and List Actions

Source: https://github.com/apiato/documentation/blob/master/docs/components/main-components/actions.md

Commands to create new actions or list existing ones in an Apiato application.

```shell
php artisan apiato:make:action
```

```shell
php artisan apiato:list:actions
```

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

### Implement custom models

Source: https://github.com/apiato/documentation/blob/master/docs/components/main-components/models.md

Use the ResourceKeyAware interface and InteractsWithApiato trait for models that do not extend standard parent classes.

```php
use Apiato\Core\Models\InteractsWithApiato;
use Apiato\Http\Resources\ResourceKeyAware;

class Demo implements ResourceKeyAware
{
    use InteractsWithApiato;
}
```

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

### Configure Routing

Source: https://github.com/apiato/documentation/blob/master/docs/digging-deeper/advance-configuration.mdx

Use withRouting to set URL prefixes, load route files, disable auto-versioning, or resolve API versions dynamically.

```php
Apiato::configure()
    ->withRouting(
        function (\Apiato\Foundation\Configuration\Routing $routing) {
            $routing->prefixApiUrlsWith('api/')
                ->loadApiRoutesFrom('/app/Containers/ExampleSection/ExampleContainer/UI/API/Routes')
                ->loadWebRoutesFrom('/app/Containers/ExampleSection/ExampleContainer/UI/WEB/Routes');

            // Disable API version auto-prefixing
            $routing->disableApiVersionAutoPrefix();

            // Custom API version resolver
            $routing->resolveApiVersionUsing(function (string $file) {
                return $version;
            });
        },
    );
```

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

### Deploy to GitHub Pages

Source: https://github.com/apiato/documentation/blob/master/README.md

Commands for deploying the site to the gh-pages branch, supporting both SSH and HTTPS authentication methods.

```bash
$ USE_SSH=true yarn deploy
```

```bash
$ GIT_USER=<Your GitHub username> yarn deploy
```

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

### Generate a new container

Source: https://github.com/apiato/documentation/blob/master/docs/architecture-concepts/container.md

Use this command to interactively scaffold a new container and its associated components.

```bash
php artisan apiato:make:container
```

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

### Generate a new job

Source: https://github.com/apiato/documentation/blob/master/docs/components/optional-components/jobs.md

Use the interactive artisan command to scaffold a new job file.

```bash
php artisan apiato:make:job
```

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

### Migration directory structure

Source: https://github.com/apiato/documentation/blob/master/docs/components/optional-components/migrations.mdx

Visual representation of where migration files should be located within the project structure.

```markdown
app
├── Containers
│   └── Section
│       └── Container
│           └── Data
│               └── Migrations
│                   ├── 0000_01_01_000001_create_things_table.php
│                   └── ...
└── Ship
    └── Migrations
        ├── 0000_02_02_000002_create_another_things_table.php
        └── ...
```

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

### Specifying App via Header

Source: https://github.com/apiato/documentation/blob/master/docs/the-basics/apps.md

Use the App-Identifier header in API requests to select the target application configuration.

```bash
-H "App-Identifier: web"
```

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

### Apply Criteria to a Repository

Source: https://github.com/apiato/documentation/blob/master/docs/components/optional-components/repository/criteria.mdx

Use the pushCriteria method on a repository instance to apply query conditions.

```php
public function run()
{
    $repository = app(UserRepository::class);

    $repository->pushCriteria(new IsNullCriteria('email'));
    $repository->pushCriteria(OrderByNameCriteria::class);

    return $repository->paginate();
}
```

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

### Event and Listener Folder Structure

Source: https://github.com/apiato/documentation/blob/master/docs/components/optional-components/events.mdx

Visual representation of the required directory layout for events, listeners, and their respective service providers.

```php
app
├── Containers
│   └── Section
│       └── Container
│           ├── Events
│           │   ├── DemoEvent.php
│           │   └── ...
│           ├── Listeners
│           │   ├── DemoListener.php
│           │   └── ...
│           └── Providers
                // highlight-start
│               ├── EventServiceProvider.php
                // highlight-end
│               └── ...
└── Ship
    ├── Events
    │   ├── ShipDemoEvent.php
    │   └── ...
    ├── Listeners
    │   ├── ShipDemoListener.php
    │   └── ...
    └── Providers
        // highlight-start
        ├── EventServiceProvider.php
        // highlight-end
        └── ...
```

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

### Factory Directory Structure

Source: https://github.com/apiato/documentation/blob/master/docs/components/optional-components/factories.mdx

Standard file path convention for placing factory files within an Apiato container.

```markdown
app
└── Containers
    └── Section
        └── Container
            └── Data
                └── Factories
                    ├── ModelFactory.php
                    └── ...
```

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

### Register Available or Default Includes

Source: https://github.com/apiato/documentation/blob/master/docs/components/main-components/transformers.mdx

Add relationship names to the available or default includes arrays.

```php
protected array $availableIncludes = [
    'roles',
];

// or

protected array $defaultIncludes = [
    'roles',
];
```

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

### Implement a Web Controller

Source: https://github.com/apiato/documentation/blob/master/docs/components/main-components/controllers.md

Web controllers must extend WebController and typically return a view.

```php
use App	Ship	Parents	Controllers	WebController;

class Controller extends WebController
{
    public function show()
    {
        return view('sectionName@containerName::view-name');
    }
}
```

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

### Basic Action Implementation

Source: https://github.com/apiato/documentation/blob/master/docs/components/main-components/actions.md

Standard structure for an Action class extending ParentAction and executing a task.

```php
use App\Ship\Parents\Actions\Action as ParentAction;

class DemoAction extends ParentAction
{
    public function __construct(
        private readonly DemoTask $demoTask
    ) {
    }

    public function run(DemoRequest $request)
    {
        return $this->demoTask->run();
    }
}
```

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

### Generate a new migration

Source: https://github.com/apiato/documentation/blob/master/docs/components/optional-components/migrations.mdx

Use the interactive artisan command to create a new migration file.

```bash
php artisan apiato:make:migration
```

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

### Configure Database Seeders

Source: https://github.com/apiato/documentation/blob/master/docs/digging-deeper/advance-configuration.mdx

Use withSeeders to specify custom seeder paths and implement custom sorting logic for seeder classes.

```php
Apiato::configure()
    ->withSeeders(
        function (\Apiato\Foundation\Configuration\Seeding $seeding) {
            $seeding->loadFrom(
                '/app/Containers/ExampleSection/ExampleContainer/Data/Seeders',
            );

            // Custom seeder sorting
            $seeding->sortUsing(function (array $classMapGroupedByDirectory) {
                // Custom sorting logic
                return $sortedClassNames;
            });
        },
    );
```

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

### Configure bootstrap/app.php for Apiato 13

Source: https://github.com/apiato/documentation/blob/master/docs/prologue/upgrade-guide.mdx

Replace the existing bootstrap/app.php file with this structure to integrate Apiato's providers, routing, and middleware using the new fluid API.

```php
<?php

use Apiato\Foundation\Apiato;
use Apiato\
Http\Middleware\ProcessETag;
use Apiato\Http\Middleware\ValidateJsonContent;
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

$basePath = dirname(__DIR__);
$apiato = Apiato::configure(basePath: $basePath)->create();

return Application::configure(basePath: $basePath)
    ->withProviders($apiato->providers())
    ->withEvents($apiato->events())
    ->withRouting(
        web: $apiato->webRoutes(),
        channels: __DIR__ . '/../app/Ship/Broadcasts/channels.php',
        health: '/up',
        then: static fn () => $apiato->registerApiRoutes(),
    )
    ->withMiddleware(function (Middleware $middleware) {
        // Previously applied via app/Ship/Kernels/HttpKernel class
        $middleware->api(append: [
            ValidateJsonContent::class,
            ProcessETag::class,
        ]);

        // Uncomment and adjust these if using web routes:
        // $middleware->redirectUsersTo(fn ($request): string => action(HomePageController::class));
        // $middleware->redirectGuestsTo(fn ($request): string => action([LoginController::class, 'showForm']));
    })
    ->withCommands($apiato->commands())
    ->withExceptions(static function (Exceptions $exceptions) {})
    ->create();
```

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

### Middleware directory structure

Source: https://github.com/apiato/documentation/blob/master/docs/components/optional-components/middleware.md

Visual representation of where container-specific and general middleware should be located.

```text
app
├── Containers
│   └── Section
│       └── Container
│           └── Middleware
│               ├── DemoMiddleware.php
│               └── ...
└── Ship
    └── Middleware
        ├── AnotherMiddleware.php
        └── ...
```

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

### Generate a new request

Source: https://github.com/apiato/documentation/blob/master/docs/components/main-components/requests.md

Use the interactive artisan command to scaffold a new request class.

```bash
php artisan apiato:make:request
```