Laravel JSON:API

https://github.com/laravel-json-api/laravel
Admin
Laravel JSON:API implements feature-rich JSON:API compliant APIs in Laravel applications, enabling...
Tokens:65,417
Snippets:485
Trust Score:6.6
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Example with custom controller and options

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/routing.md

Example of registering a resource with a custom controller, limiting to index and show actions, setting a custom parameter name, and applying middleware.

```php
$server->resource('posts', MyCustomController::class)
    ->only('index', 'show')
    ->parameter('post')
    ->middleware('auth:api');
```

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

### Example — resource query class

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/requests-query.md

Example of a custom resource query class extending ResourceQuery.

```APIDOC
## Example — resource query class

```php
namespace App\JsonApi\V1\Posts;

use LaravelJsonApi\Laravel\Http\Requests\ResourceQuery;
use LaravelJsonApi\Validation\Rule as JsonApiRule;

class PostQuery extends ResourceQuery
{
    protected array $mediaTypes = ['text/html'];  // allow HTML browsing of the endpoint

    public function rules(): array
    {
        return [
            'fields' => ['nullable', 'array', JsonApiRule::fieldSets()],
            'filter' => ['nullable', 'array', JsonApiRule::filter()->forget('id')],
            'filter.published' => ['boolean'],
            'include' => ['nullable', 'string', JsonApiRule::includePaths()],
            'page' => JsonApiRule::notSupported(),
            'sort' => JsonApiRule::notSupported(),
            'withCount' => ['nullable', 'string', JsonApiRule::countable()],
        ];
    }
}
```
```

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

### Example — error handling for unacceptable media types

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/requests-query.md

Example of handling HttpNotAcceptableException when the Accept header is not acceptable.

```APIDOC
## Example — error handling for unacceptable media types

```php
use LaravelJsonApi\Laravel\Exceptions\HttpNotAcceptableException;

try {
    $query = ResourceQuery::queryOne('posts');
} catch (HttpNotAcceptableException $e) {
    // 406 — the client's Accept header was not the JSON:API media type
    return response()->json(['error' => 'Unacceptable media type'], 406);
}
```
```

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

### Example usage of JsonApiRoute::server

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/service-provider.md

Registers a server named 'v1' with prefix, namespace, and resources.

```php
use LaravelJsonApi\Laravel\Facades\JsonApiRoute;

JsonApiRoute::server('v1')
    ->prefix('v1')
    ->namespace('Api\V1')
    ->resources(function ($server) {
        $server->resource('posts');
    });
```

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

### Example resource query class (PostQuery)

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/requests-query.md

Example of a resource query class extending ResourceQuery. It defines validation rules for query parameters, including fields, filter, include, page, sort, and withCount. It also sets mediaTypes to allow HTML browsing of the endpoint.

```php
namespace App\JsonApi\V1\Posts;

use LaravelJsonApi\Laravel\Http\Requests\ResourceQuery;
use LaravelJsonApi\Validation\Rule as JsonApiRule;

class PostQuery extends ResourceQuery
{
    protected array $mediaTypes = ['text/html'];  // allow HTML browsing of the endpoint

    public function rules(): array
    {
        return [
            'fields' => ['nullable', 'array', JsonApiRule::fieldSets()],
            'filter' => ['nullable', 'array', JsonApiRule::filter()->forget('id')],
            'filter.published' => ['boolean'],
            'include' => ['nullable', 'string', JsonApiRule::includePaths()],
            'page' => JsonApiRule::notSupported(),
            'sort' => JsonApiRule::notSupported(),
            'withCount' => ['nullable', 'string', JsonApiRule::countable()],
        ];
    }
}
```

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

### Install laravel-json-api/laravel via Composer

Source: https://github.com/laravel-json-api/laravel/blob/develop/README.md

Installs the Laravel JSON:API package via Composer as the primary dependency. This command should be run from your project directory after ensuring Composer is installed.

```bash
composer require laravel-json-api/laravel
```

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

### Example: configuring a posts resource

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/routing-pending.md

Demonstrates fluent configuration of a resource: restricting actions, overriding the parameter name, setting route names, defining relationships, and adding custom actions.

```php
$server->resource('posts')
    ->only('index', 'show', 'store')
    ->parameter('post')
    ->names(['index' => 'posts.list', 'store' => 'posts.create'])
    ->relationships(function ($relationships) {
        $relationships->hasOne('author')->readOnly();
        $relationships->hasMany('comments');
    })
    ->actions(function ($actions) {
        $actions->get('featured');
    });
```

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

### Relationships usage example

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/routing-pending.md

Shows how to define a to-one and a to-many relationship in the relationships() callback.

```php
$relationships->hasOne('author')->readOnly();
$relationships->hasMany('tags');
```

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

### Registering a server with JsonApiRoute

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/routing.md

Example of registering a JSON:API server's routes using the JsonApiRoute facade. It sets a prefix and namespace, and defines resources within a closure.

```php
use LaravelJsonApi\Laravel\Facades\JsonApiRoute;

JsonApiRoute::server('v1')
    ->prefix('v1')
    ->namespace('Api\V1')
    ->resources(function ($server) {
        // ...
    });
```

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

### ActionProxy usage example

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/routing-pending.md

Example of using ActionProxy: explicit naming with name() and auto-naming with the controller method when name() is not called.

```php
$actions->get('me')->name('users.me');           // explicit name
$actions->withId()->post('publish');             // auto-named "publish"
```

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

### Using env() for server config

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/configuration.md

Example of using env() to drive the 'servers' config value. The package itself reads no environment variables directly.

```php
'servers' => [
    'v1' => env('JSON_API_V1_SERVER', \App\JsonApi\V1\Server::class),
],
```

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

### PendingResourceRegistration

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/routing-pending.md

Documentation for the PendingResourceRegistration class, including its constructor, fluent configuration methods, overloads, and an example.

```APIDOC
## PendingResourceRegistration

### Description
Fluent configuration object returned by `ResourceRegistrar::resource($resourceType, $controller)` for defining resource routes, relationships, and custom actions.

### Constructor

```php
public function __construct(
    ResourceRegistrar $registrar,
    string $resourceType,
    string $controller
)
```

### Methods

#### `only`

- **Signature**: `public function only(string ...$actions): self`
- **Description**: Restricts resource routes to the given actions; aliases resolved via `$map`.

#### `except`

- **Signature**: `public function except(string ...$actions): self`
- **Description**: Excludes the given actions; aliases resolved via `$map`.

#### `readOnly`

- **Signature**: `public function readOnly(): self`
- **Description**: Equals `only('index', 'show')`.

#### `names`

- **Signature**: `public function names(array $names): self`
- **Description**: Sets route names per action (keys may be aliases).

#### `name`

- **Signature**: `public function name(string $method, string $name): self`
- **Description**: Route name for one action; `$method` resolved via `$map`.

#### `parameter`

- **Signature**: `public function parameter(string $parameter): self`
- **Description**: Overrides the route parameter name.

#### `middleware`

- **Signature**: `public function middleware(...$middleware): self`
- **Description**: Applies middleware to all actions (list form) or per-action (associative form). See overloads below.

#### `withoutMiddleware`

- **Signature**: `public function withoutMiddleware(string ...$middleware): self`
- **Description**: Adds to `excluded_middleware`.

#### `relationships`

- **Signature**: `public function relationships(Closure $callback): self`
- **Description**: Stores the relationship callback (executed at `register()`).

#### `actions`

- **Signature**: `public function actions($prefixOrCallback, ?Closure $callback = null): self`
- **Description**: Stores a custom-actions callback; either `actions($callback)` or `actions($prefix, $callback)`.

#### `register`

- **Signature**: `public function register(): RouteCollection`
- **Description**: Registers resource routes + relationships + actions, returns them.

### `middleware()` Overloads

```php
// list form → applied to all actions
->middleware('auth:api', 'throttle:60,1')

// associative form → per-action middleware ('*' applies to all)
->middleware([
    '*' => 'auth:api',
    'index' => 'cache.headers:private',
    'store' => 'auth:api',
])
```

When a single argument is passed it is wrapped with `Arr::wrap()`. The list form sets `options['middleware']`; the associative form sets both `options['middleware']` (from `'*'`) and `options['action_middleware']`.

### `actions()` Overloads

```php
// no prefix — callback only
->actions(function ($actions) { $actions->get('me'); })

// with URI prefix
->actions('-actions', function ($actions) { $actions->delete('purge'); })
```

Invalid argument combinations throw `InvalidArgumentException('Invalid arguments when registering custom resource actions.')`.

### Example

```php
$server->resource('posts')
    ->only('index', 'show', 'store')
    ->parameter('post')
    ->names(['index' => 'posts.list', 'store' => 'posts.create'])
    ->relationships(function ($relationships) {
        $relationships->hasOne('author')->readOnly();
        $relationships->hasMany('comments');
    })
    ->actions(function ($actions) {
        $actions->get('featured');
    });
```
```

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

### register() method

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/routing.md

Registers the resource's own routes (index/store/show/update/destroy) filtered by the only/except options. Each route gets Route::RESOURCE_TYPE as a default; single-resource routes also get Route::RESOURCE_ID_NAME.

```php
public function register(string $resourceType, string $controller, array $options = []): RouteCollection
```

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

### GET /{uri}/me

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/endpoints.md

Registers a custom action route for a GET request to the `me` endpoint of a resource.

```APIDOC
## GET /{uri}/me

### Description
Registers a custom action route for a GET request to the `me` endpoint of a resource. The controller method defaults to `Str::camel($uri)` and the route is named after the controller method unless an explicit name is provided.

### Method
GET

### Endpoint
`/{uri}/me`

### Parameters
#### Path Parameters
- **uri** (string) - Required - The resource URI (e.g., `posts`).

### Response
#### Success Response (200)
The response is determined by the controller method; no standard response schema is defined.

#### Response Example
```json
{}
```
```

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

### Custom resolver hooks example

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/requests-form.md

Shows how to override the default request class guessing using guessResourceRequestUsing and guessQueryManyUsing.

```php
use LaravelJsonApi\Laravel\Http\Requests\ResourceRequest;
use LaravelJsonApi\Laravel\Http\Requests\ResourceQuery;

// Globally guess request classes from an alternate mapping:
ResourceRequest::guessResourceRequestUsing(function (string $resourceType) {
    return match ($resourceType) {
        'articles' => new App\Http\Requests\ArticleRequest(),
        default => new RequestResolver(RequestResolver::REQUEST)($resourceType),
    };
});

ResourceQuery::guessQueryManyUsing(function (string $resourceType) {
    return (new RequestResolver(RequestResolver::COLLECTION_QUERY))($resourceType);
});
```

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

### GET /{uri}/me (with explicit name)

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/endpoints.md

Registers a custom action route for a GET request to the `me` endpoint of a resource, with an explicit route name.

```APIDOC
## GET /{uri}/me (with explicit name)

### Description
Registers a custom action route for a GET request to the `me` endpoint of a resource, with an explicit route name (e.g., `users.me`). The controller method defaults to `Str::camel($uri)`.

### Method
GET

### Endpoint
`/{uri}/me`

### Parameters
#### Path Parameters
- **uri** (string) - Required - The resource URI (e.g., `posts`).

### Response
#### Success Response (200)
The response is determined by the controller method; no standard response schema is defined.

#### Response Example
```json
{}
```
```

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

### Controller with lifecycle hooks (PostController)

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/controller-actions.md

Example controller implementing lifecycle hooks for the Laravel JSON:API. Hooks return null to continue with default behavior; a truthy Responsable/Response short-circuits the default response. The saved hook logs activity, readComments customizes the related-response, and deleting aborts with 409 for featured posts.

```php
namespace App\Http\Controllers\Api\V1;

use LaravelJsonApi\Laravel\Http\Controllers\JsonApiController;
use LaravelJsonApi\Laravel\Http\Requests\ResourceQuery;
use LaravelJsonApi\Laravel\Http\Requests\ResourceRequest;

class PostController extends JsonApiController
{
    public function searching(ResourceQuery $request)
    {
        if (! $request->isViewingAny()) {
            return null; // continue with default behavior
        }
        // e.g. add CORS headers via a custom response
    }

    public function saved($model, ResourceRequest $request, ResourceQuery $query)
    {
        activity()->log('post saved: ' . $model->getKey());
    }

    public function readComments($post, $comments, ResourceQuery $request)
    {
        // customize the related-response for the comments relation
        return null; // fall back to the default RelatedResponse
    }

    public function deleting($post, ResourceRequest $request)
    {
        if ($post->isFeatured()) {
            abort(409, 'Cannot delete a featured post.');
        }
    }
}
```

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

### Generate JSON:API server and resources with artisan commands

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/console-commands.md

Run these artisan commands in order to generate a JSON:API server, schema, resource, requests, authorizer, controller, and stubs. Generated files land in app/JsonApi/V1/Posts/ (request/query/schema/resource) and app/Http/Controllers/ (controller) by default.

```bash
php artisan jsonapi:server v1 --uri=/api/v1
php artisan jsonapi:schema posts --server=v1
php artisan jsonapi:resource posts --model="App\Models\Post" --server=v1
php artisan jsonapi:requests posts --server=v1
php artisan jsonapi:authorizer posts --resource --server=v1
php artisan jsonapi:controller PostsController
php artisan jsonapi:stubs --force
```

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

### ActionRegistrar::get()

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/routing.md

Registers a GET route for a custom action on the resource.

```APIDOC
## `get(string $uri, ?string $method = null): ActionProxy`

### Description
Registers a GET route for a custom action. The URI is normalized and used as the controller method if `$method` is not provided.

### Method
`get`

### Signature
```php
public function get(string $uri, ?string $method = null): ActionProxy
```

### Parameters
- **$uri** (string) - Required - Action URI, camel-cased and used as the controller method when `$method` is null (`Str::camel($uri)`).
- **$method** (?string) - Optional - Explicit controller method name. Default: `null`.

### Return Value
- **ActionProxy** - An action proxy for the registered route.

### Example
```php
$actions->get('me');
```
```

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

### FetchOne::show() method signature

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/controller-actions.md

Signature for the show action that fetches a single resource by ID. It resolves a query, invokes optional hooks, and returns a data response.

```php
public function show(Route $route, StoreContract $store)
```

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

### GET /{uri}/{parameter}/relationships/{fieldUri}

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/endpoints.md

Returns the resource identifier(s) for a given relationship.

```APIDOC
## GET /{uri}/{parameter}/relationships/{fieldUri}

### Description
Returns the resource identifier(s) for a given relationship.

### Method
GET

### Endpoint
/{uri}/{parameter}/relationships/{fieldUri}

### Parameters
#### Path Parameters
- **uri** (string) - Required - The resource type URI.
- **parameter** (string) - Required - The resource ID parameter.
- **fieldUri** (string) - Required - The relationship field URI.

### Response
#### Success Response (200)
- **data** (object|array) - A resource identifier (to-one) or identifier collection (to-many).

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

```

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

### jsonapi:server command properties

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/console-commands.md

Defines the command name and type for the jsonapi:server make command. The handle() method refuses to create a server if it is already registered unless --force is provided.

```php
protected $name = 'jsonapi:server';
protected $type = 'JSON:API server';
```

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

### GET /{uri}/{parameter}/{fieldUri}

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/endpoints.md

Returns the related resource(s) for a given relationship field.

```APIDOC
## GET /{uri}/{parameter}/{fieldUri}

### Description
Returns the related resource(s) for a given relationship field.

### Method
GET

### Endpoint
/{uri}/{parameter}/{fieldUri}

### Parameters
#### Path Parameters
- **uri** (string) - Required - The resource type URI.
- **parameter** (string) - Required - The resource ID parameter.
- **fieldUri** (string) - Required - The relationship field URI.

### Response
#### Success Response (200)
- **data** (object|array) - The related resource (to-one) or a paginated collection (to-many).

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

```

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

### withId() method signature

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/routing.md

Returns a clone with the id-parameter flag set, so subsequent routes are prefixed with `{parameter}/`. The original registrar is unchanged.

```php
public function withId(): self
```

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

### Registrar::server() method

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/routing.md

Returns a PendingServerRegistration for the given server name. If the repository is a ServerRepository, the server is instantiated once; otherwise, the server is fetched from the repository.

```php
public function server(string $name): PendingServerRegistration
```

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

### Registering classes in a server with LaravelJsonApi

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/laravel-json-api.md

Shows how to register collection queries, queries, requests, and authorizers in a server class by overriding the serving() method. Use this when setting up a JSON:API server with custom classes for media and posts resources.

```php
use LaravelJsonApi\Laravel\LaravelJsonApi;

class Server extends BaseServer
{
    public function serving(): void
    {
        LaravelJsonApi::registerCollectionQuery(Media\MediaCollectionQuery::class, 'media');
        LaravelJsonApi::registerQuery(Posts\PostQuery::class, 'posts');
        LaravelJsonApi::registerRequest(Posts\PostRequest::class, 'posts');
        LaravelJsonApi::registerAuthorizer(
            App\JsonApi\Authorizers\PostAuthorizer::class,
            Posts\PostSchema::class,
        );
    }
}
```

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

### boot method signature

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/service-provider.md

The boot method receives the Laravel router via method injection.

```php
public function boot(Router $router): void
```

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

### Catching HttpNotAcceptableException

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/errors.md

Example of catching HttpNotAcceptableException when calling a query that triggers validation preparation. Returns a JSON error response with status 406 and title 'Not Acceptable'.

```php
use LaravelJsonApi\Laravel\Exceptions\HttpNotAcceptableException;

try {
    $response = $this->query($query); // triggers validation preparation
} catch (HttpNotAcceptableException $e) {
    return response()->json(['errors' => [['status' => '406', 'title' => 'Not Acceptable']]], 406);
}

```

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

### FetchMany::index()

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/controller-actions.md

Lists all resources of a type. Resolves the resource query, invokes optional searching/searched hooks, and returns a paginated or collection response.

```APIDOC
## [GET] {uri}

### Description
Fetch a list of resources of the given type.

### Method
GET

### Endpoint
{uri}

### Parameters
#### Path Parameters
- **type** (string) - Required - The resource type.

### Response
#### Success Response (200)
- **data** (array) - Collection of resource objects.

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

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

### RequestResolver constructor and invocation

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/requests-form.md

Constructor and __invoke method signatures.

```php
public function __construct(string $type)

public function __invoke(string $resourceType, bool $allowNull = false): ?FormRequest
```

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

### Error handling for unacceptable media types

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/requests-query.md

Example of error handling for unacceptable media types. It catches HttpNotAcceptableException thrown when the client's Accept header is not the JSON:API media type, returning a 406 response with an error message.

```php
use LaravelJsonApi\Laravel\Exceptions\HttpNotAcceptableException;

try {
    $query = ResourceQuery::queryOne('posts');
} catch (HttpNotAcceptableException $e) {
    // 406 — the client's Accept header was not the JSON:API media type
    return response()->json(['error' => 'Unacceptable media type'], 406);
}
```

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

### CommentRequest accessing relationship modification data

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/requests-resource.md

Shows how to inspect models being attached during relationship modification without an extra query. The authorizeResource method checks if the request is modifying and attaching a relationship, then calls $this->toMany() to get the models. The rules method includes a toOne() rule for the author relationship, which must be validated for relationship endpoints.

```php
use LaravelJsonApi\Contracts\Auth\Authorizer;
use LaravelJsonApi\Laravel\Http\Requests\ResourceRequest;

class CommentRequest extends ResourceRequest
{
    public function rules(Authorizer $authorizer): array
    {
        return [
            'author' => JsonApiRule::toOne(),   // must be validated for relationship endpoints
            'content' => ['required', 'string'],
        ];
    }

    public function authorizeResource(Authorizer $authorizer): bool
    {
        if ($this->isModifyingRelationship() && $this->isAttachingRelationship()) {
            // Inspect models being attached without an extra query:
            $models = $this->toMany();
        }

        return parent::authorizeResource($authorizer);
    }
}
```

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

### ResourceQuery

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/requests-query.md

Documentation for the ResourceQuery class, including its static resolution methods and configurable properties.

```APIDOC
## ResourceQuery

### Description
Request class for JSON:API query parameters on read endpoints (index, show, related, relationship). Implements the `LaravelJsonApi\Contracts\Query\QueryParameters` contract so the values it returns (`IncludePaths`, `FieldSets`, `SortFields`, `FilterParameters`, page, and unrecognized parameters) can be consumed directly by the store.

### Class Signature
```php
namespace LaravelJsonApi\Laravel\Http\Requests;

class ResourceQuery extends FormRequest implements QueryParameters
```

### Static Methods

#### `guessQueryManyUsing(callable $resolver): void`
Overrides the resolver used by `queryMany()` globally.

#### `queryMany(string $resourceType): QueryParameters`
Resolves a collection-query instance via `RequestResolver(RequestResolver::COLLECTION_QUERY)`.

#### `guessQueryOneUsing(callable $resolver): void`
Overrides the resolver used by `queryOne()` globally.

#### `queryOne(string $resourceType): QueryParameters`
Resolves a single query instance via `RequestResolver(RequestResolver::QUERY)`.

### Properties (protected, configurable by subclasses)
- `$mediaTypes` (array) - additional acceptable media types
- `$defaultIncludePaths` (?array) - used when the client sends no `?include`
```

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

### resource() method

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/routing.md

Registers a resource type and returns a PendingResourceRegistration. The controller defaults to a guessed class name based on the singular resource type.

```php
public function resource(string $resourceType, ?string $controller = null): PendingResourceRegistration
```

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

### Default config/jsonapi.php

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/configuration.md

Default configuration file published to config/jsonapi.php. Sets the root namespace to 'JsonApi' and maps the 'v1' server to its class.

```php
<?php

return [
    'namespace' => 'JsonApi',

    'servers' => [
        'v1' => \App\JsonApi\V1\Server::class,
    ],
];
```

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

### register method signature

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/service-provider.md

The register method runs four private binders.

```php
public function register(): void
```

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

### middleware() overloads: list and associative forms

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/routing-pending.md

Shows the two accepted forms for middleware(): a list form applied to all actions, and an associative form for per-action middleware where '*' applies to all. The list form sets options['middleware']; the associative form sets both options['middleware'] (from '*') and options['action_middleware'].

```php
// list form → applied to all actions
->middleware('auth:api', 'throttle:60,1')

// associative form → per-action middleware ('*' applies to all)
->middleware([
    '*' => 'auth:api',
    'index' => 'cache.headers:private',
    'store' => 'auth:api',
])
```

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

### BootJsonApi constructor

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/middleware.md

Constructor for the BootJsonApi middleware. Injects the application container and the server repository; both are resolved automatically by the container.

```php
public function __construct(
    Container $container,   // Illuminate\.Container\.Container
    Repository $servers     // LaravelJsonApi\Contracts\Server\Repository
)
```

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

### Resource Routes

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/endpoints.md

Standard resource routes for JSON:API resources, including index, store, show, update, and destroy operations.

```APIDOC
## GET /{uri}

### Description
Returns a collection of resources of the given type, optionally filtered, sorted, paginated, and with related resources included.

### Method
GET

### Endpoint
/{uri}

### Parameters
#### Query Parameters
- **include** (string) - Optional - Comma-separated list of related resources to include.
- **fields[...]** (string) - Optional - Sparse fieldset to limit the attributes returned.
- **filter[...]** (string) - Optional - Filter criteria for the resource collection.
- **sort** (string) - Optional - Sort order for the collection.
- **page[...]** (string) - Optional - Pagination parameters.
- **withCount** (string) - Optional - Include related resource counts.

### Request Example
GET /posts?include=comments&filter[status]=published&sort=-created_at&page[number]=1&page[size]=10

### Response
#### Success Response (200)
- **data** (array) - Resource collection, possibly paginated.
- **links** (object) - Pagination links when a paginator is configured.
- **meta** (object) - Pagination metadata when a paginator is configured.

#### Response Example
{
  "data": [
    {
      "type": "posts",
      "id": "1",
      "attributes": {
        "title": "Hello World"
      }
    }
  ],
  "links": {
    "first": "http://example.com/posts?page[number]=1",
    "last": "http://example.com/posts?page[number]=10"
  },
  "meta": {
    "total": 100
  }
}

### Error Handling
- **406** - Accept header must include the JSON:API media type.
```

```APIDOC
## POST /{uri}

### Description
Creates a new resource of the given type. The request body must be a valid JSON:API create document.

### Method
POST

### Endpoint
/{uri}

### Parameters
#### Request Body
- **data** (object) - Required - The resource object.
  - **type** (string) - Required - The resource type.
  - **attributes** (object) - Optional - Resource attributes.
  - **relationships** (object) - Optional - Resource relationships.

### Request Example
{
  "data": {
    "type": "posts",
    "attributes": {
      "title": "Hello World"
    }
  }
}

### Response
#### Success Response (201)
- **data** (object) - The created resource.

#### Response Example
{
  "data": {
    "type": "posts",
    "id": "1",
    "attributes": {
      "title": "Hello World"
    }
  }
}

### Error Handling
- **415** - Content-Type must be application/vnd.api+json.
- **422** - Validation errors (spec or Laravel validation).
```

```APIDOC
## GET /{uri}/{parameter}

### Description
Returns a single resource identified by the given parameter.

### Method
GET

### Endpoint
/{uri}/{parameter}

### Parameters
#### Path Parameters
- **parameter** (string) - Required - The resource ID.

#### Query Parameters
- **include** (string) - Optional - Comma-separated list of related resources to include.
- **fields[...]** (string) - Optional - Sparse fieldset.

### Request Example
GET /posts/1?include=comments

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

#### Response Example
{
  "data": {
    "type": "posts",
    "id": "1",
    "attributes": {
      "title": "Hello World"
    }
  }
}

### Error Handling
- **406** - Accept header must include the JSON:API media type.
```

```APIDOC
## PATCH /{uri}/{parameter}

### Description
Updates an existing resource. The request body must be a valid JSON:API update document. Missing attributes keep their current values.

### Method
PATCH

### Endpoint
/{uri}/{parameter}

### Parameters
#### Path Parameters
- **parameter** (string) - Required - The resource ID.

#### Request Body
- **data** (object) - Required - The resource object.
  - **type** (string) - Required - The resource type.
  - **id** (string) - Required - The resource ID.
  - **attributes** (object) - Optional - Attributes to update.
  - **relationships** (object) - Optional - Relationships to update.

### Request Example
{
  "data": {
    "type": "posts",
    "id": "1",
    "attributes": {
      "title": "Updated Title"
    }
  }
}

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

#### Response Example
{
  "data": {
    "type": "posts",
    "id": "1",
    "attributes": {
      "title": "Updated Title"
    }
  }
}

### Error Handling
- **415** - Content-Type must be application/vnd.api+json.
- **422** - Validation errors.
```

```APIDOC
## DELETE /{uri}/{parameter}

### Description
Deletes an existing resource. No request body is required, but an optional body can be provided for validation purposes.

### Method
DELETE

### Endpoint
/{uri}/{parameter}

### Parameters
#### Path Parameters
- **parameter** (string) - Required - The resource ID.

#### Request Body (Optional)
- **meta** (object) - Optional - Additional metadata merged into data for validation.

### Request Example
DELETE /posts/1

### Response
#### Success Response (204)
No content.

### Error Handling
- **406** - Accept header must include the JSON:API media type.
```

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

### Static resolution methods for ResourceQuery

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/requests-query.md

Static methods for resolving query instances. guessQueryManyUsing and guessQueryOneUsing override the global resolvers, while queryMany and queryOne resolve instances via RequestResolver with COLLECTION_QUERY and QUERY constants respectively.

```php
public static function guessQueryManyUsing(callable $resolver): void
public static function queryMany(string $resourceType): QueryParameters
public static function guessQueryOneUsing(callable $resolver): void
public static function queryOne(string $resourceType): QueryParameters
```

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

### JsonApiRoute facade class

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/service-provider.md

The facade returns the Registrar class from the container.

```php
namespace LaravelJsonApi\Laravel\Facades;

class JsonApiRoute extends Facade
{
    protected static function getFacadeAccessor()
    {
        return Registrar::class;   // LaravelJsonApi\Laravel\Routing\Registrar
    }
}
```

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

### FetchMany::index() method signature

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/controller-actions.md

Signature for the index action that fetches a collection of resources. It resolves a query, invokes optional hooks, and returns a data response.

```php
public function index(Route $route, StoreContract $store)
```

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

### Static method annotation for server

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/service-provider.md

The @method annotation reveals the Registrar::server() method.

```php
@method static PendingServerRegistration server(string $name)
```

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

### Internal action map (aliases to canonical methods)

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/routing-pending.md

Maintains an internal action map that resolves aliases like 'create' to 'store', 'read' to 'show', and 'delete' to 'destroy'.

```php
private array $map = [
    'create' => 'store',
    'read' => 'show',
    'delete' => 'destroy',
];
```

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

### RequestResolver::__construct

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/requests-form.md

Constructor for the RequestResolver, initializes the request type.

```APIDOC
## RequestResolver::__construct

### Description
Constructor for the RequestResolver, initializes the request type.

### Method
`public function __construct(string $type)`

### Parameters
- **$type** (string) - Required - One of `QUERY`, `COLLECTION_QUERY`, `REQUEST`.

### Source
`src/Http/Requests/RequestResolver.php:76`
```

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

### ResourceRequest::forResource

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/requests-resource.md

Resolves the request instance for a resource type. Throws LogicException if it cannot be created.

```APIDOC
## [GET] /resource-request/for-resource

### Description
Resolve the request instance for a resource type. Throws `LogicException` via `RequestResolver` if it cannot be created.

### Method
GET

### Endpoint
/resource-request/for-resource

### Parameters
#### Path Parameters
- **resourceType** (string) - Required - The resource type to resolve.

### Request Example
{
  "resourceType": "posts"
}

### Response
#### Success Response (200)
- **request** (ResourceRequest) - Description: The resolved request instance.

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

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

### Store::store() method signature

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/controller-actions.md

Signature for the store action that creates a new resource. It resolves a request and query, invokes hooks, and returns a 201 response.

```php
public function store(Route $route, StoreContract $store)
```

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

### Registrar::server

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/routing.md

Returns a PendingServerRegistration for the given server name, allowing fluent route registration. Uses the repository to instantiate the server once if possible.

```APIDOC
## Registrar::server

### Description
Returns a PendingServerRegistration for the given server name, allowing fluent route registration. Uses the repository to instantiate the server once if possible.

### Method
server

### Parameters
- `$name` (string) - Required - Unique server name from `config('jsonapi.servers')`

### Returns
`PendingServerRegistration`

### Behavior
If the repository is a `LaravelJsonApi\Core\Server\ServerRepository`, `Repository::once($name)` is used (ensuring the server is instantiated once); otherwise `Repository::server($name)`.

### Example
```php
use LaravelJsonApi\Laravel\Facades\JsonApiRoute;

JsonApiRoute::server('v1')
    ->prefix('v1')
    ->namespace('Api\V1')
    ->resources(function ($server) {
        // ...
    });
```
```

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

### PendingServerRegistration

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/routing-pending.md

Fluent object returned by Registrar::server($name) that wraps a Server instance and provides methods to configure the route group attributes such as name, prefix, middleware, domain, and namespace.

```APIDOC
## PendingServerRegistration

### Description
Fluent object returned by `Registrar::server($name)` that wraps a `LaravelJsonApi\Contracts\Server\Server` instance. Provides methods to configure the route group attributes and register resources.

### Constructor

```php
public function __construct(RegistrarContract $router, Server $server)
```

Source: `src/Routing/PendingServerRegistration.php:42`

The initial route-group attributes are:

```php
$this->attributes = [
    'middleware' => "jsonapi:{$server->name()}",
    'as' => "{$server->name()}.",
];
```

### Fluent configuration methods

All return `self` unless noted.

| Method | Signature (source line) | Description |
|--------|------------------------|-------------|
| `name` | `public function name(string $name): self` (line 56) | Overrides the route group's `as` (name prefix) |
| `prefix` | `public function prefix(string $prefix): self` (line 67) | Sets the route group URI prefix, e.g. `v1` |
| `middleware` | `public function middleware(string ...$middleware): self` (line 80) | Merges middleware onto the group (appended to the `jsonapi:{name}` middleware) |
| `withoutMiddleware` | `public function withoutMiddleware(string ...$middleware)` (line 96) | Records `excluded_middleware` for the group |
| `domain` | `public function domain(string $domain): self` (line 110) | Sets the route group domain |
| `namespace` | `public function namespace(string $namespace): self` (line 121) | Sets the route group controller namespace |
| `resources` | `public function resources(\Closure $callback): void` (line 134) | Registers the group; invokes `$callback(new ResourceRegistrar($this->router, $this->server), $this->router)` |

### Example

```php
use LaravelJsonApi\Laravel\Facades\JsonApiRoute;

JsonApiRoute::server('v1')
    ->prefix('v1')
    ->domain('api.example.com')
    ->namespace('App\Http\Controllers\Api\V1')
    ->resources(function ($server, $router) {
        $server->resource('posts'); // PendingResourceRegistration
    });
```
```

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

### Lifecycle Hooks

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/controller-actions.md

Pre- and post-hooks for each action that can be implemented on a controller to customize behavior.

```APIDOC
## Lifecycle Hooks

### Description
Controller methods called by action traits via `method_exists()` checks. Implement them to customize behavior. A hook returning a truthy `Responsable`/`Response` short-circuits the default response.

### Hooks Table

| Action | Pre-hooks | Post-hooks |
|--------|-----------|------------|
| `index` | `searching($request)` | `searched($data, $request)` |
| `show` | `reading($request)` | `read($model, $request)` |
| `store` | `saving(null, $request, $query)` → `creating($request, $query)` | `created($model, $request, $query)` → `saved($model, $request, $query)` |
| `update` | `saving($model, $request, $query)` → `updating($model, $request, $query)` | `updated($model, $request, $query)` → `saved($model, $request, $query)` |
| `destroy` | `deleting($model, $request)` | `deleted($model, $request)` |
| `showRelated` | `readingRelated{Field}($model, $request)` | `readRelated{Field}($model, $data, $request)` |
| `showRelationship` | `reading{Field}($model, $request)` | `read{Field}($model, $data, $request)` |
| `updateRelationship` | `updating{Field}($model, $request, $query)` | `updated{Field}($model, $result, $request, $query)` |
| `attachRelationship` | `attaching{Field}($model, $request, $query)` | `attached{Field}($model, $result, $request, $query)` |
| `detachRelationship` | `detaching{Field}($model, $request, $query)` | `detached{Field}($model, $result, $request, $query)` |

### Example Controller

```php
namespace App\Http\Controllers\Api\V1;

use LaravelJsonApi\Laravel\Http\Controllers\JsonApiController;
use LaravelJsonApi\Laravel\Http\Requests\ResourceQuery;
use LaravelJsonApi\Laravel\Http\Requests\ResourceRequest;

class PostController extends JsonApiController
{
    public function searching(ResourceQuery $request)
    {
        if (! $request->isViewingAny()) {
            return null; // continue with default behavior
        }
        // e.g. add CORS headers via a custom response
    }

    public function saved($model, ResourceRequest $request, ResourceQuery $query)
    {
        activity()->log('post saved: ' . $model->getKey());
    }

    public function readComments($post, $comments, ResourceQuery $request)
    {
        // customize the related-response for the comments relation
        return null; // fall back to the default RelatedResponse
    }

    public function deleting($post, ResourceRequest $request)
    {
        if ($post->isFeatured()) {
            abort(409, 'Cannot delete a featured post.');
        }
    }
}
```
```

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

### ActionProxy methods

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/routing-pending.md

Method signatures for ActionProxy. __call forwards to Illuminate\Routing\Route, and name() sets the route name and marks it named.

```php
public function __call($name, $arguments)   // forwarded to Illuminate\Routing\Route
public function name(string $name): self
```

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

### Route constructor

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/route.md

Creates a new Route instance with the container, server, and underlying Laravel route. The constructor type-hints the Illuminate route as `IlluminateRoute`.

```php
public function __construct(
    Container $container,          // Illuminate\Contracts\Container\Container
    Server $server,                // LaravelJsonApi\Contracts\Server\Server
    IlluminateRoute $route         // Illuminate\Routing\Route
)
```

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

### Constructor signature for PendingResourceRegistration

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/routing-pending.md

Defines the constructor parameters: ResourceRegistrar $registrar, string $resourceType, string $controller. Source: src/Routing/PendingResourceRegistration.php:79.

```php
public function __construct(
    ResourceRegistrar $registrar,
    string $resourceType,
    string $controller
)
```

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

### actions() overloads: no prefix and with URI prefix

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/routing-pending.md

Shows the two overloads for actions(): one with a callback only, and one with a URI prefix and callback. Invalid argument combinations throw InvalidArgumentException('Invalid arguments when registering custom resource actions.') (line 245).

```php
// no prefix — callback only
->actions(function ($actions) { $actions->get('me'); })

// with URI prefix
->actions('-actions', function ($actions) { $actions->delete('purge'); })
```

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

### RequestResolver static methods

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/requests-form.md

Declarations for useDefault() and register() static methods.

```php
public static function useDefault(string $type, string $class): void
public static function register(string $type, string $resourceType, string $class): void
```

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

### Composer extra configuration for Laravel discovery

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/service-provider.md

Registers the service provider and aliases for JsonApi and JsonApiRoute facades in composer.json.

```json
"extra": {
    "laravel": {
        "aliases": {
            "JsonApi": "LaravelJsonApi\\Core\\Facades\\JsonApi",
            "JsonApiRoute": "LaravelJsonApi\\Laravel\\Facades\\JsonApiRoute"
        },
        "providers": [
            "LaravelJsonApi\\Laravel\\ServiceProvider"
        ]
    }
}
```

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

### Initial route-group attributes

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/routing-pending.md

Default attributes for the route group: middleware uses the jsonapi: prefix with the server name, and the name prefix (as) uses the server name followed by a dot.

```php
$this->attributes = [
    'middleware' => "jsonapi:{$server->name()}",
    'as' => "{$server->name()}.",
];
```

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

### jsonapi:stubs command signature and handle method

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/console-commands.md

Declares the jsonapi:stubs command signature with a --force option and the handle method return type. This command publishes stub files to stubs/jsonapi/ and only overwrites existing files when --force is used.

```php
protected $signature = 'jsonapi:stubs {--force : Overwrite any existing files}';
public function handle(): int
```

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

### registerQuery()

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/laravel-json-api.md

Registers a query class for single-resource reads for given resource types.

```APIDOC
## registerQuery()

### Description
Registers a query class for single-resource reads via RequestResolver::register().

### Method
registerQuery

### Signature
public static function registerQuery(string $queryClass, $resourceTypes): self

### Parameters
- **$queryClass** (string) - Required - Query class for single-resource reads
- **$resourceTypes** (mixed) - Required - Resource type or array of resource types (wrapped via Arr::wrap)

### Return Value
self (new instance)

### Usage Example
```php
LaravelJsonApi::registerQuery(MyQuery::class, 'posts');
```
```

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

### Relationships methods

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/routing-pending.md

Methods available on the Relationships class for defining to-one and to-many relations, plus registration.

```php
public function hasOne(string $fieldName): PendingRelationshipRegistration
public function hasMany(string $fieldName): PendingRelationshipRegistration
public function register(): RouteCollection
```

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

### ActionProxy constructor

Source: https://github.com/laravel-json-api/laravel/blob/develop/_autodocs/api-reference/routing-pending.md

Constructor signature for ActionProxy. Takes the actual Laravel route and the controller action name used as the default route name.

```php
public function __construct(IlluminateRoute $route, string $controllerMethod)
```
Tokens:
Raw