API Platform for Laravel

https://github.com/api-platform/laravel
Admin
API Platform for Laravel integrates the Laravel framework and Illuminate components with the API...
Tokens:103,241
Snippets:675
Trust Score:9.8
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### InstallCommand usage

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

Command to install API Platform resources. Publishes `config/api-platform.php` and `public/vendor/api-platform` assets.

```bash
php artisan api-platform:install
# publishes config/api-platform.php and public/vendor/api-platform assets
```

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

### Pointing an operation at a custom controller

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/controllers.md

Two-part example: first, a resource class uses the Get operation with a custom controller. Second, the custom controller implements __invoke, using the provider and processor to handle the request. The custom controller must be a class with an __invoke method.

```php
// app/ApiResource/WithCustomController.php
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;

#[ApiResource(operations: [new Get(controller: WithCustomController::class)])]
class WithCustomController
{
    // ...
}
```

```php
// app/Http/Controllers/WithCustomControllerController.php
use ApiPlatform\Metadata\Operation;
use ApiPlatform\State\ProcessorInterface;
use ApiPlatform\State\ProviderInterface;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class WithCustomControllerController
{
    public function __construct(
        private ProviderInterface $provider,
        private ProcessorInterface $processor,
    ) {}

    public function __invoke(Request $request): Response
    {
        $operation = $request->attributes->get('_api_operation');
        $uriVariables = $request->attributes->get('_api_uri_variables', []);
        $body = $this->provider->provide($operation, $uriVariables, ['request' => $request, 'resource_class' => $operation->getClass()]);

        return $this->processor->process($body, $operation, $uriVariables, [
            'request' => $request,
            'resource_class' => $operation->getClass(),
        ]);
    }
}
```

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

### GET /{index?}{_format?}

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/endpoints.md

Returns the Hydra entrypoint listing all available resources. The index parameter is constrained to 'index'.

```APIDOC
## GET /{index?}{_format?}

### Description
Returns the Hydra entrypoint listing all available resources. The `index` parameter is constrained to `index`.

### Method
GET

### Endpoint
`/{index?}{_format?}`

### Parameters
#### Path Parameters
- **index** (string) - Optional - Must be `index` if provided.
- **_format** (string) - Optional - The response format (e.g., `jsonld`).

### Response
#### Success Response (200)
- Hydra entrypoint object listing all resources.
```

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

### Policy-driven authorization example

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/security.md

Example BookPolicy class with methods for viewAny, view, create, update, and delete. This policy is auto-detected by EloquentResourceCollectionMetadataFactory, mapping operations to policy methods.

```php
// app/Policies/BookPolicy.php — auto-detected by EloquentResourceCollectionMetadataFactory
class BookPolicy
{
    public function viewAny(?User $user): bool { return true; }
    public function view(?User $user, Book $book): bool { return $user->id === $book->user_id; }
    public function create(?User $user): bool  { return (bool) $user; }
    public function update(?User $user, Book $book): bool { return $user->id === $book->user_id; }
    public function delete(?User $user, Book $book): bool { return $user->id === $book->user_id; }
}
```

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

### InstallCommand signature and description

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

Defines the command name and description for the `api-platform:install` command. The `handle()` method runs `vendor:publish` for the `api-platform-assets` and `api-platform-config` tags and prints a success message.

```php
protected $signature = 'api-platform:install';
protected $description = 'Install all of the API Platform resources';

public function handle(): void     // line 35
```

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

### GET /api/books/{id}

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/endpoints.md

Example of a dynamically generated resource route for retrieving a single book.

```APIDOC
## [GET] /api/books/{id}

### Description
Retrieves a single book resource by its identifier. The response is serialized according to the configured formats and serializer groups.

### Method
GET

### Endpoint
/api/books/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier of the book resource.

### Response
#### Success Response (200)
- **@context** (string) - The JSON-LD context URL.
- **@id** (string) - The IRI of the resource.
- **@type** (string) - The resource type.
- **id** (string) - The resource identifier.
- **title** (string) - The book title.

#### Response Example
{
  "@context": "/api/contexts/Book",
  "@id": "/api/books/1",
  "@type": "Book",
  "id": 1,
  "title": "Example Book"
}
```

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

### GET /contexts/{shortName?}{_format?}

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/endpoints.md

Retrieves the JSON-LD context for a resource. The shortName parameter is optional and defaults to 'Entrypoint'.

```APIDOC
## GET /contexts/{shortName?}{_format?}

### Description
Returns the JSON-LD `@context` for a resource. The `shortName` defaults to `'Entrypoint'` if not provided.

### Method
GET

### Endpoint
`/contexts/{shortName?}{_format?}`

### Parameters
#### Path Parameters
- **shortName** (string) - Optional - The resource short name (e.g., `Book`). Defaults to `'Entrypoint'`.
- **_format** (string) - Optional - The response format (e.g., `jsonld`).

### Response
#### Success Response (200)
- JSON-LD context object for the resource.

#### Error Responses
- 400/404-style problem responses for unknown or non-resource short names.
```

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

### POST /api/books

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/endpoints.md

Example of a dynamically generated resource route for creating a new book.

```APIDOC
## [POST] /api/books

### Description
Creates a new book resource. The request body must be in one of the supported formats.

### Method
POST

### Endpoint
/api/books

### Parameters
#### Request Body
- **title** (string) - Required - The title of the book.

### Request Example
{
  "title": "New Book"
}

### Response
#### Success Response (201)
- **@context** (string) - The JSON-LD context URL.
- **@id** (string) - The IRI of the created resource.
- **@type** (string) - The resource type.
- **id** (string) - The resource identifier.
- **title** (string) - The book title.

#### Response Example
{
  "@context": "/api/contexts/Book",
  "@id": "/api/books/2",
  "@type": "Book",
  "id": 2,
  "title": "New Book"
}
```

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

### Drop the SQLite database for fresh fixtures

Source: https://github.com/api-platform/laravel/blob/main/AGENTS.md

Use to drop the SQLite database for a fresh fixtures start. Run from the src/Laravel directory.

```bash
vendor/bin/testbench workbench:drop-sqlite-db
```

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

### Run tests, clean database, and serve the app

Source: https://github.com/api-platform/laravel/blob/main/CONTRIBUTING.md

Commands for running the test suite: first, set up dependencies and run the package tests (or directly run PHPUnit); second, drop the SQLite database when needed; third, start the test server.

```shell
cd src/Laravel
composer global require soyuka/pmu
composer global link ../../
vendor/bin/testbench workbench:build
vendor/bin/testbench api-platform:install 
vendor/bin/testbench package:test
# or
vendor/bin/phpunit

```

```shell
vendor/bin/testbench workbench:drop-sqlite-db

```

```shell
vendor/bin/testbench serve

```

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

### GET /api/books

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/endpoints.md

Example of a dynamically generated resource route for retrieving a collection of books.

```APIDOC
## [GET] /api/books

### Description
Retrieves a collection of book resources. Supports pagination and filtering via query parameters.

### Method
GET

### Endpoint
/api/books

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number for pagination.
- **itemsPerPage** (integer) - Optional - The number of items per page.
- **pagination** (boolean) - Optional - Whether to enable pagination.
- **partial** (boolean) - Optional - Whether to return a partial collection.

### Response
#### Success Response (200)
- **@context** (string) - The JSON-LD context URL.
- **@id** (string) - The IRI of the collection.
- **@type** (string) - The collection type.
- **hydra:member** (array) - The list of resources.
- **hydra:totalItems** (integer) - The total number of items.
- **hydra:view** (object) - Paging links when partial.

#### Response Example
{
  "@context": "/api/contexts/Book",
  "@id": "/api/books",
  "@type": "hydra:Collection",
  "hydra:member": [
    {
      "@id": "/api/books/1",
      "@type": "Book",
      "id": 1,
      "title": "Example Book"
    }
  ],
  "hydra:totalItems": 1
}
```

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

### GET /graphiql

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/endpoints.md

GraphiQL interactive IDE for exploring the GraphQL endpoint. Only available when enabled.

```APIDOC
## GET /graphiql

### Description
GraphiQL interactive IDE for exploring the GraphQL endpoint. Only available when `api-platform.graphiql.enabled` is true (default).

### Method
GET

### Endpoint
/graphiql

### Response
#### Success Response (200)
- HTML page for GraphiQL IDE.

### Notes
- Honors `graphiql.domain` and `graphiql.middleware` configuration.
```

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

### Usage example for ApiTestAssertionsTrait

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/testing.md

Example of using the trait in a Laravel TestCase for feature tests. Shows assertJsonContains and getIriFromResource usage.

```php
use ApiPlatform\Laravel\Test\ApiTestAssertionsTrait;
use Illuminate\Foundation\Testing\TestCase;

class BookApiTest extends TestCase
{
    use ApiTestAssertionsTrait;

    public function test_collection_payload_contains_expected_fields(): void
    {
        $response = $this->getJson('/api/books?name=Foundation');
        $response->assertOk();

        $json = $response->json();
        $this->assertJsonContains(
            ['hydra:member' => [['title' => 'Foundation', 'isbn' => '978-0-553-29335-7']]],
            $json,
        );
    }

    public function test_item_iri(): void
    {
        $book = \App\Models\Book::find(1);
        $iri = $this->getIriFromResource($book);   // "/api/books/1"
    }
}
```

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

### Add middleware to API routes via config/api-platform.php

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/controllers.md

Configuration example showing how to add middleware like 'auth:sanctum' to every API route group or per-route via operation middleware.

```php
// config/api-platform.php — add to every API route group, or per-route via operation middleware
'defaults' => [
    'middleware' => ['auth:sanctum'],
],
```

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

### JSON:API SortFilter usage example

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/eloquent-filters.md

Example of using SortFilter with a query parameter 'sort' and properties 'name' and 'createdAt'. The query ?sort=-createdAt,name sorts by createdAt descending and name ascending.

```php
#[QueryParameter(key: 'sort', filter: SortFilter::class, properties: ['name', 'createdAt'])]
// ?sort=-createdAt,name
```

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

### PUT /api/books/{id}

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/endpoints.md

Example of a dynamically generated resource route for updating a book.

```APIDOC
## [PUT] /api/books/{id}

### Description
Replaces an existing book resource identified by its ID.

### Method
PUT

### Endpoint
/api/books/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier of the book resource.

#### Request Body
- **title** (string) - Required - The title of the book.

### Request Example
{
  "title": "Updated Book"
}

### Response
#### Success Response (200)
- **@context** (string) - The JSON-LD context URL.
- **@id** (string) - The IRI of the resource.
- **@type** (string) - The resource type.
- **id** (string) - The resource identifier.
- **title** (string) - The book title.

#### Response Example
{
  "@context": "/api/contexts/Book",
  "@id": "/api/books/1",
  "@type": "Book",
  "id": 1,
  "title": "Updated Book"
}
```

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

### OrFilter usage example

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/eloquent-filters.md

Example of using OrFilter with an EqualsFilter on a query parameter 'name2'. The query ?name2[]=Foo&name2[]=Bar produces a WHERE clause with OR conditions.

```php
#[QueryParameter(key: 'name2', filter: new OrFilter(new EqualsFilter()), property: 'name')]
// GET /api/books?name2[]=Foo&name2[]=Bar  =>  WHERE (name = 'Foo' OR name = 'Bar')
```

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

### PartialSearchFilter usage with QueryParameter attribute

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/eloquent-filters.md

Shows how to apply PartialSearchFilter with a minimum length constraint. The example query searches for ISBNs starting with '978'.

```php
#[QueryParameter(key: 'isbn', filter: PartialSearchFilter::class, constraints: 'min:2')]
// GET /api/books?isbn=978
```

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

### GET /docs{_format?}

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/endpoints.md

Provides the API documentation in OpenAPI, Hydra, or HTML formats. Supports query parameters for spec version and API gateway normalization.

```APIDOC
## GET /docs{_format?}

### Description
Returns the API documentation in various formats: OpenAPI spec, Hydra docs, or HTML UI (Swagger UI/ReDoc/Scalar).

### Method
GET

### Endpoint
`/docs{_format?}`

### Parameters
#### Path Parameters
- **_format** (string) - Optional - The response format (e.g., `json`, `html`).

#### Query Parameters
- **spec_version** (string) - Optional - The OpenAPI spec version (from `LegacyOpenApiNormalizer::SPEC_VERSION`).
- **api_gateway** (boolean) - Optional - Whether to use the API Gateway normalizer (from `ApiGatewayNormalizer::API_GATEWAY`).

### Response
#### Success Response (200)
- For OpenAPI formats: serialized `ApiPlatform\OpenApi\OpenApi` object.
- For Hydra: serialized `ApiPlatform\Documentation\Documentation` object.
- For HTML: Swagger UI/ReDoc/Scalar interface.

#### Supported Formats
- `application/ld+json` (Hydra docs)
- `application/vnd.openapi+json` (OpenAPI)
- `application/json`
- `text/html` (Swagger UI/ReDoc/Scalar when enabled)
```

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

### PATCH /api/books/{id}

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/endpoints.md

Example of a dynamically generated resource route for partially updating a book.

```APIDOC
## [PATCH] /api/books/{id}

### Description
Partially updates an existing book resource. The request body must be in merge-patch JSON format.

### Method
PATCH

### Endpoint
/api/books/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier of the book resource.

#### Request Body
- **title** (string) - Optional - The title of the book.

### Request Example
{
  "title": "Partially Updated Book"
}

### Response
#### Success Response (200)
- **@context** (string) - The JSON-LD context URL.
- **@id** (string) - The IRI of the resource.
- **@type** (string) - The resource type.
- **id** (string) - The resource identifier.
- **title** (string) - The book title.

#### Response Example
{
  "@context": "/api/contexts/Book",
  "@id": "/api/books/1",
  "@type": "Book",
  "id": 1,
  "title": "Partially Updated Book"
}
```

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

### Custom filter implementation (AwesomeFilter)

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/eloquent-filters.md

Example of a custom filter generated via make:filter. It uses QueryPropertyTrait and applies a LIKE constraint using the whereClause from context (default 'where'). If values is not a string, it returns the builder unchanged.

```php
use ApiPlatform\Laravel\Eloquent\Filter\FilterInterface;
use ApiPlatform\Laravel\Eloquent\Filter\QueryPropertyTrait;
use ApiPlatform\Metadata\Parameter;
use Illuminate\Database\Eloquent\Builder;

final class AwesomeFilter implements FilterInterface
{
    use QueryPropertyTrait;

    public function apply(Builder $builder, mixed $values, Parameter $parameter, array $context = []): Builder
    {
        if (!is_string($values)) {
            return $builder;
        }

        return $builder->{$context['whereClause'] ?? 'where'}($this->getQueryProperty($parameter), 'like', '%'.$values.'%');
    }
}
```

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

### GET/POST /graphql

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/endpoints.md

GraphQL endpoint for executing queries and mutations. Supports GET and POST with JSON or multipart/form-data.

```APIDOC
## GET/POST /graphql

### Description
GraphQL endpoint for executing GraphQL queries and mutations. Supports GET and POST requests with various content types.

### Method
GET, POST

### Endpoint
/graphql

### Parameters
#### Query Parameters (GET)
- **query** (string) - Required - The GraphQL query string.
- **operationName** (string) - Optional - The name of the operation to execute.
- **variables** (string) - Optional - JSON-encoded string of variables.

#### Request Body (POST JSON)
- **query** (string) - Required - The GraphQL query string.
- **variables** (object|string) - Optional - Variables as an object or JSON string.
- **operationName** (string) - Optional - The name of the operation to execute.

#### Request Body (POST multipart/form-data)
- **operations** (string) - Required - JSON string containing the GraphQL operation.
- **map** (string) - Required - JSON string mapping file keys to variables paths.
- **file fields** (file) - Required - The file fields referenced in the map.

### Request Example
```json
{
  "query": "query { user(id: 1) { name } }",
  "variables": { "id": 1 },
  "operationName": null
}
```

### Response
#### Success Response (200)
- **data** (object) - The result data.
- **errors** (array) - List of errors, if any.

#### Response Example
```json
{
  "data": {
    "user": {
      "name": "John Doe"
    }
  }
}
```

### Error Handling
- Missing `operations` or `map` in multipart request: `BadRequestHttpException('GraphQL multipart request does not respect the specification.')`
- Missing file: `'GraphQL multipart request file has not been sent correctly.'`
- Invalid paths: `'... path in map is invalid.'` / `'... does not match the variables.'`
- Invalid variables JSON: `'GraphQL variables are not valid JSON.'`
```

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

### Array rules on an operation

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/state-providers.md

Example of using array rules on an operation. The rules are passed directly to the Post operation and validated by ValidateProvider.

```php
use ApiPlatform\Metadata\Post;

#[ApiResource(
    operations: [
        new Post(rules: [
            'name' => 'required|string|max:255',
            'price' => 'required|numeric|min:0',
        ]),
    ],
)]
class Product
{
    public ?int $id = null;
    public ?string $name = null;
    public ?float $price = null;
}
```

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

### ServiceLocator constructor and methods

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/types.md

Shows the public API of the array-backed service locator. `get()` returns `null` for missing ids instead of throwing `NotFoundException`, deviating from PSR-11. Used for tagged filter/providers locators, GraphQL type/resolver locators, and `CallableProvider`/`CallableProcessor`.

```php
public function __construct(array $services = [])   // string keys preserved; class names used for numeric keys
public function get(string $id): mixed              // returns null for missing ids (not an exception)
public function has(string $id): bool
```

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

### Custom TrashExtension implementing QueryExtensionInterface

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/eloquent-filters.md

Example of a custom query extension that automatically includes soft-deleted models. It checks if the model uses the SoftDeletes trait and applies withTrashed() if so. This extension is automatically tagged when it implements QueryExtensionInterface.

```php
use ApiPlatform\Laravel\Eloquent\Extension\QueryExtensionInterface;
use ApiPlatform\Metadata\Operation;
use Illuminate\Database\Eloquent\Builder;

final class TrashExtension implements QueryExtensionInterface
{
    public function apply(Builder $builder, array $uriVariables, Operation $operation, $context = []): Builder
    {
        if (method_exists($builder->getModel(), 'trashed')) {
            return $builder->withTrashed();
        }

        return $builder;
    }
}
```

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

### FormRequest class rules

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/state-providers.md

Example of using a FormRequest class for rules. The resource references the request class, which is instantiated by the container and its authorize() and rules() methods are called.

```php
use ApiPlatform\Metadata\GetCollection;

#[ApiResource(operations: [new GetCollection(rules: GetDropOffSlotsRequest::class)])]
class SlotsForDate
{
    // ...
}
```

```php
// app/Http/Requests/GetDropOffSlotsRequest.php
use Illuminate\Foundation\Http\FormRequest;

class GetDropOffSlotsRequest extends FormRequest
{
    public function authorize(): bool { return true; }

    public function rules(): array
    {
        return [
            'pickupDate' => 'required|date|after_or_equal:today',
        ];
    }
}
```

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

### Usage example: stable ids within a request

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/routing.md

Demonstrates that getIriFromResource returns the same id for the same object within a request (object cache hit), and that reset() clears the cache after each request.

```php
$iri1 = $skolemIriConverter->getIriFromResource($embedded);   // "/.well-known/genid/ab12cd34...
$iri2 = $skolemIriConverter->getIriFromResource($embedded);   // same id (object cache hit)
$skolemIriConverter->reset();                                 // called automatically after each request
```

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

### EntrypointController::provide()

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/controllers.md

Static method that returns a new Entrypoint instance using the cached resource name collection.

```php
public static function provide(): Entrypoint
{
    return new Entrypoint(self::$resourceNameCollection);
}
```

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

### AbstractMakeStateCommand constructor and handle method

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

Shows the constructor and handle method of the abstract command class. The constructor injects Filesystem, StateTemplateGenerator, and StateAppServiceProviderTagger. The handle method is where the command logic runs.

```php
public function __construct(
    private readonly Filesystem $filesystem,
    private readonly StateTemplateGenerator $stateTemplateGenerator,
    private readonly StateAppServiceProviderTagger $stateAppServiceProviderTagger,
) {                                                                                          // line 28
}

public function handle(): int    // line 39
```

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

### Link root dependencies and build workbench fixtures

Source: https://github.com/api-platform/laravel/blob/main/AGENTS.md

Run from the src/Laravel directory to link the root dependencies and build the workbench fixtures. Required before running tests in this component.

```bash
composer link ../../
vendor/bin/testbench workbench:build
```

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

### DELETE /api/books/{id}

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/endpoints.md

Example of a dynamically generated resource route for deleting a book.

```APIDOC
## [DELETE] /api/books/{id}

### Description
Deletes an existing book resource identified by its ID.

### Method
DELETE

### Endpoint
/api/books/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier of the book resource.

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

#### Response Example
(empty)
```

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

### DocumentationController constructor

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/controllers.md

Constructor for DocumentationController with dependency injection for resource name collection, title, description, version, OpenAPI factory, provider, processor, negotiator, documentation formats, and UI toggles. Sets the negotiator to a new instance if not provided.

```php
public function __construct(
    private readonly ResourceNameCollectionFactoryInterface $resourceNameCollectionFactory,
    private readonly string $title = '',
    private readonly string $description = '',
    private readonly string $version = '',
    private readonly ?OpenApiFactoryInterface $openApiFactory = null,
    private readonly ?ProviderInterface $provider = null,
    private readonly ?ProcessorInterface $processor = null,
    ?Negotiator $negotiator = null,
    private readonly array $documentationFormats = [OpenApiNormalizer::JSON_FORMAT => ['application/vnd.openapi+json'], OpenApiNormalizer::FORMAT => ['application/json']],
    private readonly bool $swaggerUiEnabled = true,
    private readonly bool $scalarEnabled = true,
    private readonly bool $redocEnabled = true,
) {
    $this->negotiator = $negotiator ?? new Negotiator();
}
```

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

### provide() method signature

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/eloquent-state.md

Full signature of the provide method.

```php
public function provide(Operation $operation, array $uriVariables = [], array $context = []): object|array|null
{
    // ...
}
```

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

### Usage of maker commands

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

Shows the artisan commands to run the makers. The state-provider and filter commands prompt for a class name interactively.

```bash
php artisan make:state-provider   # "Choose a class name for your state provider (e.g. AwesomeStateProvider)"
php artisan make:state-processor
php artisan make:filter           # "Choose a class name for your filter (e.g. AwesomeFilter)"
```

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

### Publishing config and assets via artisan commands

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/service-providers.md

Commands to publish the package configuration and assets. The first command calls vendor:publish for both tags, while the latter two target each tag individually.

```bash
php artisan api-platform:install            # calls vendor:publish for both tags
php artisan vendor:publish --tag=api-platform-config
php artisan vendor:publish --tag=api-platform-assets
```

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

### GET /.well-known/genid/{id}

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/endpoints.md

This route is intentionally not exposed and always throws an exception. It serves as the target for Skolem IRIs.

```APIDOC
## GET /.well-known/genid/{id}

### Description
This route is the target for Skolem IRIs. It always throws a `NotExposedHttpException` with message 'This route is not exposed on purpose. ...'.

### Method
GET

### Endpoint
`/.well-known/genid/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier for the Skolem IRI.

### Response
#### Error Response
- Always returns a `NotExposedHttpException` (HTTP 404) with message 'This route is not exposed on purpose. ...'.
```

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

### MakeFilterCommand constructor and handle method

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

Shows the constructor and handle method of the MakeFilterCommand. The constructor injects Filesystem, FilterTemplateGenerator, and FilterAppServiceProviderTagger. The handle method is where the command logic runs.

```php
public function __construct(
    private readonly Filesystem $filesystem,
    private readonly FilterTemplateGenerator $filterTemplateGenerator,
    private readonly FilterAppServiceProviderTagger $filterAppServiceProviderTagger,
) {                                                                                          // line 30
}

public function handle(): int    // line 41
```

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

### GET /validation_errors/{id}

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/endpoints.md

This route is intentionally not exposed and always throws an exception. It serves as the `@id` for `ValidationError` resources.

```APIDOC
## GET /validation_errors/{id}

### Description
This route is used as the `@id` for `ValidationError` resources. It always throws a `NotExposedHttpException` with message 'Not exposed.'.

### Method
GET

### Endpoint
`/validation_errors/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier of the validation error.

### Response
#### Error Response
- Always returns a `NotExposedHttpException` (HTTP 404) with message 'Not exposed.'.
```

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

### Error handling / integration

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/security.md

Shows how to handle denial when invoking the checker directly, using abort(403) to return an HTTP error.

```php
if (!$checker->isGranted(Book::class, 'update', ['object' => $book])) {
    abort(403, 'Access Denied.');
}
```

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

### GraphiQlController constructor and __invoke

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/controllers.md

Constructor and __invoke method for ApiPlatform\Laravel\GraphQl\Controller\GraphiQlController. The constructor takes a prefix (defaulting to api-platform.defaults.route_prefix, '' default) and __invoke returns a Response rendering the GraphiQL view.

```php
public function __construct(private readonly string $prefix)   // api-platform.defaults.route_prefix, '' default
public function __invoke(): Response
```

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

### Catch ValidationError

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/state-providers.md

Example of catching the ValidationError thrown by ValidateProvider. Provides access to violations and the HTTP status code (422).

```php
use ApiPlatform\Laravel\ApiResource\ValidationError;

try {
    // ... call into the provider chain, e.g. through ApiPlatformController
} catch (ValidationError $e) {
    $violations = $e->getViolations();   // [['propertyPath' => ..., 'message' => ..., 'code' => ...], ...]
    $status = $e->getStatusCode();       // 422
}
```

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

### Options::__construct

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/eloquent-state.md

Constructor for the Options class. Accepts an optional model class and custom link handling.

```APIDOC
## Options::__construct

### Description
Creates a new Options instance to bind an API resource to an Eloquent model and optionally override link handling.

### Method
Constructor

### Signature
```php
public function __construct(
    protected ?string $modelClass = null,
    protected mixed $handleLinks = null,
)
```

### Parameters
- **modelClass** (?string) - Optional - FQCN of the backing Eloquent model. Used by CollectionProvider/ItemProvider to instantiate the model, and by EloquentOperationResourceClassResolver to resolve resource classes.
- **handleLinks** (mixed) - Optional - Custom link handling: a callable or the ID of a service implementing LinksHandlerInterface resolved from the provider's handleLinksLocator.

### Usage Example
```php
use ApiPlatform\Laravel\Eloquent\State\Options;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;
use App\Models\Product as ProductModel;

#[ApiResource(
    operations: [new GetCollection()],
    stateOptions: new Options(modelClass: ProductModel::class),
)]
class Product
{
    public ?int $id = null;
    public ?string $name = null;
}
```
```

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

### IRI dereference with getResourceFromIri

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/routing.md

Uses the IriConverterInterface to load an Eloquent model from an IRI. The example returns the loaded Book model for the given IRI.

```php
use ApiPlatform\Metadata\IriConverterInterface;

$iriConverter = app(IriConverterInterface::class);

$book = $iriConverter->getResourceFromIri('/api/books/5d379e2a-2d1f-4a7f-8b0e-63c3d1c72672');
// returns the loaded Eloquent Book model
```

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

### DumpMetadataCommand signature and constructor

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

Defines the command name and description for the `api-platform:metadata:dump` command. The constructor injects the resource name collection factory and the model metadata service.

```php
protected $signature = 'api-platform:metadata:dump {--path= : Where to write the dumped metadata file (defaults to the api-platform.metadata_dump config value)}';
protected $description = 'Dump the Eloquent model metadata to a file so the app can boot without hitting the database';

public function __construct(
    private readonly ResourceNameCollectionFactoryInterface $resourceNameCollectionFactory,
    private readonly ModelMetadata $modelMetadata,
) {                                                                                          // line 36
}

public function handle(): int     // line 43
```

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

### provide() method signature

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/state-providers.md

Declares the provide method that returns an object, array, or null. It accepts the Operation, URI variables, and context, and returns the decorated provider result when validation is disabled or no Request is present.

```php
public function provide(Operation $operation, array $uriVariables = [], array $context = []): object|array|null
```

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

### getIriFromResource method implementation

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/testing.md

Protected method that uses the container's IriConverterInterface to get the IRI for a resource. Used in application feature tests.

```php
protected function getIriFromResource(object $resource): ?string
{
    $iriConverter = $this->app->make(IriConverterInterface::class);

    return $iriConverter->getIriFromResource($resource);
}
```

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

### EloquentPropertyMetadataFactory constructor and create method

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/metadata.md

Constructor and create method of EloquentPropertyMetadataFactory. The constructor accepts ModelMetadata and an optional decorated factory. The create method returns an ApiProperty instance for the given resource class and property.

```php
public function __construct(
    private readonly ModelMetadata $modelMetadata,
    private readonly ?PropertyMetadataFactoryInterface $decorated = null,
) {                                                                          // line 37
}

public function create(string $resourceClass, string $property, array $options = []): ApiProperty   // line 48
```

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

### ItemProvider usage with nested relation identifier

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/eloquent-state.md

GET /api/products/{id}/reviews/{reviewId} with a Link configured on the operation: ItemProvider uses LinksHandler to join/filter through the relation.

```php
// GET /api/products/{id}/reviews/{reviewId} with a Link configured on the operation:
// ItemProvider uses LinksHandler to join/filter through the relation.
```

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

### Options constructor with modelClass and handleLinks

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/eloquent-state.md

Constructor for the Options class implementing ApiPlatform\.State\OptionsInterface. Passed to #[ApiResource(stateOptions: ...)] to bind an API resource to an Eloquent model and override link handling. The handleLinks parameter accepts a callable or a service ID implementing LinksHandlerInterface, resolved from the provider's handleLinksLocator.

```php
/**
 * @param string|callable $handleLinks experimental callable, typed mixed as we may want a service name in the future
 *
 * @see LinksHandlerInterface
 */
public function __construct(
    protected ?string $modelClass = null,
    protected mixed $handleLinks = null,
) {
}
```

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

### Configure middleware for API Platform routes

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/controllers.md

Set the 'middleware' array in the 'routes' configuration to apply 'web' and 'auth:sanctum' middleware to every API Platform route. The 'domain' key is set to null.

```php
// config/api-platform.php
'routes' => [
    'domain' => null,
    'middleware' => ['web', 'auth:sanctum'], // applied to every API Platform route
],
```

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

### FilterQueryExtension constructor and apply method

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/eloquent-filters.md

Shows the constructor and apply method of the FilterQueryExtension. The constructor injects a filter locator, and the apply method is called for each query. It only applies to collection operations and resolves filters from parameters.

```php
public function __construct(
    private ContainerInterface $filterLocator,
) {                                                                                          // line 26
}

public function apply(Builder $builder, array $uriVariables, Operation $operation, $context = []): Builder   // line 38
```

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

### EntrypointController constructor

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/controllers.md

Constructor for EntrypointController. Injects ResourceNameCollectionFactoryInterface, ProviderInterface, ProcessorInterface, and an array of documentation formats.

```php
public function __construct(
    private readonly ResourceNameCollectionFactoryInterface $resourceNameCollectionFactory,
    private readonly ProviderInterface $provider,
    private readonly ProcessorInterface $processor,
    private readonly array $documentationFormats = [],
) {
}
```

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

### DateFilter usage with QueryParameter attributes

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/eloquent-filters.md

Shows how to apply DateFilter with and without include_nulls filter context. The first attribute filters by publication_date with a gte operator; the second includes nulls. The example query demonstrates both filters combined.

```php
#[QueryParameter(key: 'publicationDate', filter: DateFilter::class, property: 'publication_date')]
#[QueryParameter(key: 'publicationDateWithNulls', filter: DateFilter::class, property: 'publication_date', filterContext: ['include_nulls' => true])]
// GET /api/books?publicationDate[gte]=2020-01-01&publicationDateWithNulls[lt]=2024-01-01
```

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

### SwaggerUiProvider::provide() signature

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/state-providers.md

Declares the provide() method of the internal SwaggerUiProvider state provider. It returns the OpenAPI spec for the Swagger UI/ReDoc/Scalar page when an HTML request arrives and any documentation UI is enabled.

```php
public function provide(Operation $operation, array $uriVariables = [], array $context = []): object|array|null   // line 46
```

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

### SkolemIriConverter class constants and method signatures

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/routing.md

Shows the class constant SKOLEM_URI_TEMPLATE, constructor, reset method, and the two main methods getResourceFromIri and getIriFromResource with their signatures and line numbers.

```php
public const SKOLEM_URI_TEMPLATE = '/.well-known/genid/{id}';                    // line 28

public function __construct(private readonly RouterInterface $router)            // line 41

public function reset(): void                                                    // line 46 — clears both maps

public function getResourceFromIri(string $iri, array $context = [], ?Operation $operation = null): object   // line 55
// always throws ItemNotFoundException(sprintf('Item not found for "%s".', $iri))

public function getIriFromResource(object|string $resource, int $referenceType = UrlGeneratorInterface::ABS_PATH, ?Operation $operation = null, array $context = []): string   // line 63
```

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

### EntrypointController constructor

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/controllers.md

Constructor for ApiPlatform\Laravel\GraphQl\Controller\EntrypointController. It injects dependencies and sets the debug flag based on the $debug parameter.

```php
public function __construct(
    private readonly SchemaBuilderInterface $schemaBuilder,
    private readonly ExecutorInterface $executor,
    private readonly GraphiQlController $graphiQlAction,
    private readonly NormalizerInterface $normalizer,
    private readonly ErrorHandlerInterface $errorHandler,
    bool $debug = false,
    ?Negotiator $negotiator = null,
    private readonly array $formats = [],
) {
    $this->debug = $debug ? DebugFlag::INCLUDE_DEBUG_MESSAGE | DebugFlag::INCLUDE_TRACE : DebugFlag::NONE;
}
```

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

### Usage: keeping custom renderable callbacks

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/error-handling.md

Usage example showing that no changes are needed in the application's exception handler because the ErrorHandler decorates it automatically. To restrict API error rendering to API routes, use the expectsJson() check, as API Platform decides via ErrorRenderer::shouldRender().

```php
// app/Exceptions/Handler.php — nothing to change; the ErrorHandler decorates it automatically.
// To render API errors only for API routes and keep your own handler elsewhere:
$request->expectsJson()  // API Platform decides via ErrorRenderer::shouldRender()
```

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

### Options::getModelClass

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/eloquent-state.md

Returns the model class FQCN.

```APIDOC
## Options::getModelClass

### Description
Returns the modelClass property, which is the FQCN of the backing Eloquent model.

### Method
public function getModelClass(): ?string

### Returns
?string - The model class FQCN or null if not set.
```

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

### DumpMetadataCommand usage

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

Command to dump Eloquent model metadata to a file. Use the `--path` option or set the `metadata_dump` config value to specify the output file.

```bash
php artisan api-platform:metadata:dump --path=metadata.php
# or set 'metadata_dump' => base_path('storage/api-platform-metadata.php') in config
```

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

### Run PHPStan static analysis for Laravel component

Source: https://github.com/api-platform/laravel/blob/main/AGENTS.md

Run static analysis with PHPStan on the Laravel component. Useful for checking type safety and potential errors.

```bash
./vendor/bin/phpstan analyse
```

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

### ItemProvider constructor with links handler and query extensions

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/eloquent-state.md

Constructor for the Eloquent ItemProvider. Injects the required LinksHandlerInterface and optional query extensions and handle-links locator. Use when instantiating the provider with custom extension iterables.

```php
/**
 * @param LinksHandlerInterface<Model>      $linksHandler
 * @param iterable<QueryExtensionInterface> $queryExtensions
 */
public function __construct(
    private readonly LinksHandlerInterface $linksHandler,
    ?ContainerInterface $handleLinksLocator = null,
    private iterable $queryExtensions = [],
) {
    $this->handleLinksLocator = $handleLinksLocator;
}
```

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

### GET/POST/DELETE/OPTIONS /mcp

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/endpoints.md

Documentation for the MCP endpoint that exposes API Platform resources as MCP tools.

```APIDOC
## GET/POST/DELETE/OPTIONS /mcp

### Description
This endpoint exposes the API Platform resources as MCP (Model Context Protocol) tools. It is only registered when the `api-platform/mcp` and `mcp/sdk` packages are installed and the `api-platform.mcp.enabled` configuration option is set to `true` (default). The endpoint delegates to the `McpController::handle()` method, which processes the request and returns the appropriate MCP response.

### Method
GET, POST, DELETE, OPTIONS

### Endpoint
`/mcp`

### Parameters
No parameters are documented.

### Request Example
No request body is documented.

### Response
#### Success Response
No response schema is documented.

#### Response Example
No response example is documented.

### Notes
- This endpoint is outside the API prefix.
- It requires a PSR-17 implementation (e.g., `php-http/discovery`). If not available, the `McpController` constructor throws a `RuntimeException`.
- The endpoint pushes the Laravel request onto a Symfony `RequestStack`, delegates to `McpController::handle()`, and pops the stack in a `finally` block.
- Tool and response semantics are defined by `api-platform/mcp` (registry `SecureRegistry`, `PolicyAccessChecker`, `StructuredContentProcessor`, `McpIriConverter`).
```

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

### EloquentExtractor constructor

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/serialization.md

Constructor for the EloquentExtractor class. Requires a ModelMetadata instance.

```php
public function __construct(private readonly ModelMetadata $modelMetadata)
```

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

### Run a specific Laravel test via Testbench

Source: https://github.com/api-platform/laravel/blob/main/AGENTS.md

Runs a specific test file in the Laravel bridge using Testbench. Execute from the src/Laravel directory.

```bash
vendor/bin/testbench package:test Tests/NoOperationResourceTest.php
```

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

### IriConverter constructor

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/routing.md

Constructor for IriConverter with dependency injection. The decorated parameter defaults to null and is used for Skolem IRI fallback.

```php
/**
 * @param ProviderInterface<object> $provider
 */
public function __construct(
    private readonly ProviderInterface $provider,
    private readonly OperationMetadataFactoryInterface $operationMetadataFactory,
    private readonly RouterInterface $router,
    private readonly IdentifiersExtractorInterface $identifiersExtractor,
    ResourceClassResolverInterface $resourceClassResolver,
    private readonly ResourceMetadataCollectionFactoryInterface $resourceMetadataCollectionFactory,
    private readonly ?IriConverterInterface $decorated = null,
    private readonly ?OperationResourceClassResolverInterface $operationResourceResolver = null,
) {
    $this->resourceClassResolver = $resourceClassResolver;
}
```

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

### EloquentNameConverter constructor and methods

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/serialization.md

Constructor and method signatures for EloquentNameConverter. The constructor takes a NameConverterInterface, and normalize/denormalize methods accept property name, class, format, and context. Falls back between normalize and denormalize on UnexpectedPropertyException.

```php
public function __construct(private readonly NameConverterInterface $nameConverter)   // line 21

public function normalize(string $propertyName, ?string $class = null, ?string $format = null, array $context = []): string   // line 28
public function denormalize(string $propertyName, ?string $class = null, ?string $format = null, array $context = []): string   // line 40
```

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

### ApiPlatformMiddleware constructor

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/controllers.md

Constructor that injects an OperationMetadataFactory to resolve operations from operation/route names.

```php
public function __construct(
    protected OperationMetadataFactory $operationMetadataFactory,
) {
}
```

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

### Router methods signatures

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/routing.md

Method signatures for the Router class: setContext, getContext, getRouteCollection, match, and generate.

```php
public function setContext(RequestContext $context): void                        // line 49
public function getContext(): RequestContext                                     // line 57
public function getRouteCollection(): RouteCollection                            // line 65
public function match(string $pathInfo): array                                   // line 86
public function generate(string $name, array $parameters = [], ?int $referenceType = null): string   // line 99
```

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

### Router constructor

Source: https://github.com/api-platform/laravel/blob/main/_autodocs/api-reference/routing.md

Constructor for the Router decorator. Accepts the underlying Laravel router and an optional URL generation strategy, defaulting to ABS_PATH.

```php
public function __construct(
    private readonly BaseRouter $router,
    private readonly int $urlGenerationStrategy = UrlGeneratorInterface::ABS_PATH,
) {
}
```
Tokens:
Raw