api-platform / api-platform/core

UUID primary keys cause IRI generation failure in Laravel

未关闭
#8,167 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
JSON:API Laravel
主要语言
PHP
星标
2.6k
派生
980
平均合并
2 天 5 小时
30 天内合并 PR
48

描述

**API Platform version(s) affected**: 4.1.20

**Description**
When using UUID as the primary key for Eloquent models with API Platform Laravel, the IriConverter fails to generate proper IRIs for individual items in collections. This results in a `InvalidArgumentException: Unable to generate an IRI for the item of type 'App\Models\Building'` error when trying to serialize collections in JSON:API format.

The issue occurs because API Platform generates malformed route names (`_api_/api/buildings{._format}_get`) that don't match the actual Laravel routes and don't include the UUID parameter.

**How to reproduce**

1. Create a Laravel model with UUID as primary key:

```php
use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Str;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\Post;
use ApiPlatform\Metadata\Put;
use ApiPlatform\Metadata\Delete;

#[ApiResource(
operations: [
new GetCollection(
uriTemplate: '/buildings',
name: 'api_buildings_get_collection'
),
new Get(
uriTemplate: '/buildings/{uuid}',
name: 'api_buildings_get_item'
),
new Post(
uriTemplate: '/buildings',
name: 'api_buildings_post'
),
new Put(
uriTemplate: '/buildings/{uuid}',
name: 'api_buildings_put'
),
new Delete(
uriTemplate: '/buildings/{uuid}',
name: 'api_buildings_delete'
)
],
normalizationContext: ['groups' => ['building:read']],
denormalizationContext: ['groups' => ['building:write']],
paginationEnabled: true
)]
class Building extends Model
{
protected $primaryKey = 'uuid';
protected $keyType = 'string';
public $incrementing = false;

protected static function boot()
{
parent::boot();
static::creating(function ($model) {
if (!$model->uuid) {
$model->uuid = (string) Str::uuid();
}
});
}
}
```

2. Create a migration with UUID primary key:

```php
Schema::create('buildings', function (Blueprint $table) {
$table->uuid('uuid')->primary();
$table->string('name');
$table->uuid('user_uuid');
$table->timestamps();
});
```

3. Configure API Platform (`config/api-platform.php`):

```php
return [
'formats' => [
'jsonapi' => ['application/vnd.api+json'],
],
'defaults' => [
'route_prefix' => '/api',
],
];
```

4. Make a request to the collection endpoint:

```php
// Test case
public function test_it_lists_buildings(): void
{
Building::factory()->count(3)->create();

$response = $this->get('/api/buildings', [
'Accept' => 'application/vnd.api+json',
]);

$response->assertOk(); // Fails with IRI generation error
}
```

**Error Output:**

```
InvalidArgumentException: Unable to generate an IRI for the item of type "App\Models\Building"

Stack trace:
#0 vendor/api-platform/laravel/Routing/IriConverter.php(182): Unable to generate an IRI for the item of type "App\Models\Building"
api-platform/api-platform#1 vendor/api-platform/laravel/Routing/IriConverter.php(149): ApiPlatform\Laravel\Routing\IriConverter->generateRoute()
api-platform/api-platform#2 vendor/api-platform/jsonapi/Serializer/ItemNormalizer.php(100): ApiPlatform\Laravel\Routing\IriConverter->getIriFromResource()
```

**Debug logs from IriConverter:**

```
[IriConverter] Generating route:
- routeName: "_api_/api/buildings{._format}_get"
- identifiers: ["uuid" => "550e8400-e29b-41d4-a716-446655440000"]
- operation_class: "ApiPlatform\Metadata\Get"
- operation_name: "_api_/api/buildings{._format}_get"
```

**Possible Solution**
The issue appears to be in `IriConverter::getIriFromResource()` where it creates a new Get operation without proper configuration:

```php
// Line 119-125 in IriConverter.php
if (!$operation) {
$operation = (new Get())->withClass($resourceClass);
}
```

This new operation doesn't have the correct route name or URI template. The IriConverter should:
1. Use the explicitly defined operation names from the ApiResource attribute
2. Properly detect and handle UUID identifiers
3. Generate route names that match Laravel's routing conventions

A potential fix would be to ensure the operation metadata is properly loaded from the resource metadata factory before attempting to generate IRIs.

**Additional Context**
- **Laravel version**: 12.x
- **PHP version**: 8.4+
- **Database**: MariaDB with UUID columns
- **Authentication**: Laravel Sanctum

The error occurs specifically when the JSON:API serializer tries to generate the `@id` field for each item in a collection. Individual item fetches may work if accessed directly, but collections fail during serialization.

This bug prevents any Laravel application using UUIDs as primary keys from working properly with API Platform, which is a significant limitation since UUIDs are commonly used in modern applications for distributed systems and better security.

**Workarounds attempted (all failed):**
- Defining explicit operations with names and uriTemplates
- Using custom State Providers
- Changing route prefix configurations
- Testing with different output formats (JSON:API, HAL+JSON)

贡献指南

打开贡献指南

评估

这个 Issue 还没有评估数据。

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。