> For the complete documentation index, see [llms.txt](https://docs.opensoutheners.com/oss/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.opensoutheners.com/oss/laravel-apiable/getting-started/installation.md).

# Installation

Install and configure laravel-apiable in your Laravel application.

## Requirements

* PHP 8.2 or higher
* Laravel 12.x or higher

## Installing the package

Install the package via Composer:

```bash
composer require open-southeners/laravel-apiable
```

The package service provider is automatically discovered by Laravel, so no additional registration is required.

## Publishing the configuration

Publish the package configuration file to `config/apiable.php`:

```bash
php artisan vendor:publish --provider="OpenSoutheners\LaravelApiable\ServiceProvider"
```

## Setting up the resource type map

The `resource_type_map` in `config/apiable.php` is how the package knows which JSON:API type string to use for each Eloquent model. Open the published config and add your models:

```php
'resource_type_map' => [
    App\Models\Post::class   => 'post',
    App\Models\User::class   => 'user',
    App\Models\Tag::class    => 'tag',
],
```

{% hint style="info" %}
This mapping is conceptually similar to Laravel's [`Relation::enforceMorphMap()`](https://laravel.com/docs/master/eloquent-relationships#custom-polymorphic-types), but reversed: here the model class is the key and the type string is the value, whereas `enforceMorphMap` uses the type string as the key.
{% endhint %}

If a model is not listed in the map, the package falls back to a snake\_case version of the class basename (e.g. `BlogPost` becomes `blog_post`).

### Programmatic alternative

Instead of (or in addition to) the config file, you can register the map at runtime using the `Apiable::modelResourceTypeMap()` facade method. This is useful for packages or when you want to keep the mapping close to your model definitions:

{% tabs %}
{% tab title="Associative (explicit types)" %}

```php
use OpenSoutheners\LaravelApiable\Support\Apiable;

// In a service provider boot() method
Apiable::modelResourceTypeMap([
    App\Models\Post::class => 'post',
    App\Models\User::class => 'user',
    App\Models\Tag::class  => 'tag',
]);
```

{% endtab %}

{% tab title="Non-associative (auto-derived types)" %}

```php
use OpenSoutheners\LaravelApiable\Support\Apiable;

// Types are derived automatically from the class basename (snake_case)
Apiable::modelResourceTypeMap([
    App\Models\Post::class,
    App\Models\User::class,
    App\Models\Tag::class,
]);
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Calling `Apiable::modelResourceTypeMap()` replaces the entire in-memory map. If you call it multiple times, only the last call's entries will be active. Merge your entries into a single call, or rely on the config file for the baseline and use the method for additions in the same boot cycle.
{% endhint %}

## Next steps

Once installation is complete and the resource type map is configured, proceed to [Model Setup](/oss/laravel-apiable/getting-started/model-setup.md) to make your Eloquent models JSON:API-serializable.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.opensoutheners.com/oss/laravel-apiable/getting-started/installation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.