Getting Started

Minimal Setup

Installation:

composer require api-platform/laravel

Run migrations if included in the package:

php artisan migrate

Basic Configuration:
- Publish the config file:
```
php artisan vendor:publish --provider="ApiPlatform\Laravel\ApiPlatformServiceProvider" --tag="api-platform"
```
- Configure config/api-platform.php to match your API needs (e.g., enable/disable features like filters, pagination, or serialization groups).
First Use Case:
- Annotate a model with #[ApiResource]:
```
use ApiPlatform\Metadata\ApiResource;

#[ApiResource]
class Post
{
    // Model logic
}
```
- Test the API endpoint at /api/posts (or your configured route prefix).

Implementation Patterns

Common Workflows

Resource Configuration:

Use attributes to define API behavior:

#[ApiResource(
    operations: [
        new Get(),
        new Post(),
        new GetCollection(),
        new Patch(),
        new Delete(),
    ],
    normalizationContext: ['groups' => ['post:read']],
    denormalizationContext: ['groups' => ['post:write']],
)]
class Post {}

Override operations dynamically via ApiResource methods (e.g., getOperations()).

State Providers:

Handle custom logic for POST, PUT, or PATCH:

use ApiPlatform\Metadata\Operation;
use ApiPlatform\State\ProcessorInterface;

#[ApiResource(processor: MyCustomProcessor::class)]
class Post {}

class MyCustomProcessor implements ProcessorInterface
{
    public function process($data, Operation $operation, array $uriVariables = [], array $context = [])
    {
        // Custom logic (e.g., validation, business rules)
        return $data;
    }
}

Filters and Pagination:
- Enable built-in filters (e.g., search, date, boolean) in config/api-platform.php:
```
'collection' => [
    'pagination' => ['enabled' => true, 'items_per_page' => 30],
    'filters' => ['search', 'date', 'boolean'],
],
```
- Create custom filters by implementing ApiFilterInterface.

Serialization Groups:

Use groups to control which fields are exposed:

#[Groups(['post:read'])]
#[ApiProperty(identifier: true)]
public ?int $id = null;

#[Groups(['post:write'])]
public ?string $title = null;

Authentication/Authorization:
- Integrate with Laravel’s auth (e.g., Sanctum, Passport):
```
#[ApiResource(
    security: "is_granted('ROLE_ADMIN')",
    securityMessage: 'Access denied.'
)]
class AdminPost {}
```
- Use #[Security] attribute for granular control.

Event Handling:

Listen to API events (e.g., pre.extract, post.persist):

use ApiPlatform\Symfony\EventListener\EventPriorities;

public function onPostPersist(PostPersistEvent $event)
{
    $post = $event->getData();
    // Custom logic (e.g., logging, notifications)
}

Integration Tips

Laravel Mix/Vite: Ensure API routes are proxied if using frontend frameworks (e.g., Vue/React).

Testing: Use ApiPlatform\Bundle\Test\ApiTestCase for API tests:

public function testGetPosts(): void
{
    $response = $this->get('/api/posts');
    $this->assertResponseIsSuccessful();
}

Documentation: Auto-generate OpenAPI/Swagger docs via #[OpenApi] attributes or api-platform/openapi package.

Gotchas and Tips

Pitfalls

Caching:
- API Platform caches responses by default. Disable or configure in config/api-platform.php:
```
'http_cache' => [
    'enabled' => false,
    // or customize TTL/headers
],
```
- Clear cache after schema changes:
```
php artisan api-platform:cache:clear
```
Route Conflicts:
- Ensure #[ApiResource] routes don’t clash with Laravel’s web routes. Use route() middleware to prioritize:
```
Route::group(['middleware' => 'api'], function () {
    // API Platform routes
});
```
Serialization Issues:
- Circular references (e.g., Post ↔ User) may cause errors. Use #[ApiProperty(serialize: false)] or implement ApiResource\Metadata\PostSerialize:
```
#[ApiResource]
class Post
{
    #[ApiProperty(serialize: false)]
    public User $author;
}
```
Pagination:
- Default pagination may not work with custom queries. Use #[ApiFilter] or override getCollection():
```
#[ApiResource(getCollection: MyCustomCollection::class)]
class Post {}
```
Validation:
- Laravel’s validation rules (e.g., #[Assert\NotBlank]) work, but API Platform may override them. Use denormalizationContext to enforce:
```
#[ApiResource(
    denormalizationContext: ['validation_groups' => ['default', 'post']]
)]
```
Database Drivers:
- API Platform assumes Eloquent. For custom ORMs (e.g., Doctrine), configure ApiPlatform\Doctrine\Orm\Extension\QueryCollectionExtension.

Debugging Tips

Enable API Debug Toolbar:
```
// config/api-platform.php
'debug' => env('APP_DEBUG', false),
```
- View request/response details, filters, and serialization groups.

Log Serialization:

Enable serialization logging:

#[ApiResource(
    serializationContext: ['groups' => ['post:read'], 'enable_max_depth' => true]
)]

Common Errors:
- "No route found": Verify #[ApiResource] is annotated and routes are generated (php artisan route:list).
- 500 Errors: Check Laravel logs (storage/logs/laravel.log) for validation or ORM issues.
- CORS Issues: Configure CORS middleware (e.g., fruitcake/laravel-cors) if needed.

Extension Points

Custom Formats:
- Add support for formats (e.g., JSON-LD, XML) via ApiPlatform\Metadata\Format:
```
#[ApiResource(formats: ['jsonld', 'html'])]
```
GraphQL:
- Use api-platform/graphql to expose GraphQL endpoints alongside REST.
Webhooks:
- Trigger webhooks on API events (e.g., post.persist) using ApiPlatform\Symfony\EventListener\EventPriorities.
Admin Panel:
- Integrate with api-platform/admin for a built-in admin interface.

Testing:

Extend ApiTestCase for reusable test logic:

class CustomApiTestCase extends ApiTestCase
{
    protected function createTestPost(): Post
    {
        return Post::factory()->create();
    }
}

Laravel Laravel Package