fix(laravel): partial patch validation config to replace required with sometimes (#7882)

Fixes #7648

Author: soyuka

src/Laravel/ApiPlatformDeferredProvider.php

@@ -246,7 +246,8 @@ public function register(): void
                             $this->app->make(LoggerInterface::class)
                         ),
                         $app->make('filters')
-                    )
+                    ),
+                    (bool) $config->get('api-platform.partial_patch_validation', false)
                 ),
                 true === $config->get('app.debug') ? 'array' : $config->get('api-platform.cache', 'file')
             );

src/Laravel/Eloquent/Metadata/Factory/Resource/EloquentResourceCollectionMetadataFactory.php

@@ -54,6 +54,7 @@ final class EloquentResourceCollectionMetadataFactory implements ResourceMetadat
 
     public function __construct(
         private readonly ResourceMetadataCollectionFactoryInterface $decorated,
+        private readonly bool $partialPatchValidation = false,
     ) {
     }
 
@@ -97,6 +98,13 @@ public function create(string $resourceClass): ResourceMetadataCollection
                     $operation = $operation->withProcessor($operation instanceof DeleteOperationInterface ? RemoveProcessor::class : PersistProcessor::class);
                 }
 
+                if ($this->partialPatchValidation && $operation instanceof Patch) {
+                    $rules = $operation->getRules();
+                    if (\is_array($rules)) {
+                        $operation = $operation->withRules($this->replaceRequiredWithSometimes($rules));
+                    }
+                }
+
                 $operations->add($operationName, $operation);
             }
 
@@ -130,4 +138,26 @@ public function create(string $resourceClass): ResourceMetadataCollection
 
         return $resourceMetadataCollection;
     }
+
+    /**
+     * Replaces 'required' with 'sometimes' in validation rules for partial updates.
+     *
+     * @param array<string, mixed> $rules
+     *
+     * @return array<string, mixed>
+     */
+    private function replaceRequiredWithSometimes(array $rules): array
+    {
+        foreach ($rules as $field => $fieldRules) {
+            if (\is_string($fieldRules)) {
+                $parts = explode('|', $fieldRules);
+                $parts = array_map(static fn (string $rule): string => 'required' === $rule ? 'sometimes' : $rule, $parts);
+                $rules[$field] = implode('|', $parts);
+            } elseif (\is_array($fieldRules)) {
+                $rules[$field] = array_map(static fn (mixed $rule): mixed => 'required' === $rule ? 'sometimes' : $rule, $fieldRules);
+            }
+        }
+
+        return $rules;
+    }
 }

src/Laravel/Tests/ValidationTest.php

@@ -19,6 +19,7 @@
 use Illuminate\Foundation\Testing\RefreshDatabase;
 use Orchestra\Testbench\Concerns\WithWorkbench;
 use Orchestra\Testbench\TestCase;
+use Workbench\Database\Factories\Issue7648CommentFactory;
 
 class ValidationTest extends TestCase
 {
@@ -34,6 +35,7 @@ protected function defineEnvironment($app): void
         tap($app['config'], static function (Repository $config): void {
             $config->set('api-platform.formats', ['jsonld' => ['application/ld+json']]);
             $config->set('api-platform.docs_formats', ['jsonld' => ['application/ld+json']]);
+            $config->set('api-platform.partial_patch_validation', true);
         });
     }
 
@@ -76,6 +78,29 @@ public function testRouteWithRequirements(): void
         $response->assertStatus(200);
     }
 
+    /**
+     * @see https://github.com/api-platform/core/issues/7648
+     */
+    public function testPatchDoesNotRequireRelationshipFields(): void
+    {
+        $comment = Issue7648CommentFactory::new()->create();
+        $iri = $this->getIriFromResource($comment);
+
+        // PATCH with empty body should not fail on 'required' for relationship fields
+        $response = $this->patchJson($iri, [], ['accept' => 'application/ld+json', 'content-type' => 'application/merge-patch+json']);
+        $response->assertStatus(200);
+    }
+
+    /**
+     * @see https://github.com/api-platform/core/issues/7648
+     */
+    public function testPostStillRequiresRelationshipFields(): void
+    {
+        $response = $this->postJson('/api/issue7648_comments', ['content' => 'test'], ['accept' => 'application/ld+json', 'content-type' => 'application/ld+json']);
+        $response->assertStatus(422);
+        $response->assertJsonFragment(['propertyPath' => 'article', 'message' => 'The article field is required.']);
+    }
+
     public function testGetCollectionWithFormRequestValidation(): void
     {
         $response = $this->get('/api/slots/dropoff', ['accept' => 'application/ld+json']);

src/Laravel/config/api-platform.php

@@ -42,6 +42,10 @@
         'json' => ['application/merge-patch+json'],
     ],
 
+    // When true, 'required' validation rules are replaced with 'sometimes'
+    // on PATCH operations, allowing partial updates without requiring all fields.
+    'partial_patch_validation' => false,
+
     'docs_formats' => [
         'jsonld' => ['application/ld+json'],
         // 'jsonapi' => ['application/vnd.api+json'],

src/Laravel/workbench/app/Models/Issue7648Article.php

@@ -0,0 +1,37 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Workbench\App\Models;
+
+use ApiPlatform\Metadata\ApiResource;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+#[ApiResource(
+    rules: [
+        'title' => ['required', 'max:255'],
+        'content' => ['required'],
+    ],
+)]
+class Issue7648Article extends Model
+{
+    use HasFactory;
+
+    protected $table = 'issue7648_articles';
+
+    public function comments(): HasMany
+    {
+        return $this->hasMany(Issue7648Comment::class, 'article_id');
+    }
+}

src/Laravel/workbench/app/Models/Issue7648Comment.php

@@ -0,0 +1,37 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Workbench\App\Models;
+
+use ApiPlatform\Metadata\ApiResource;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+#[ApiResource(
+    rules: [
+        'article' => ['required'],
+        'content' => ['required'],
+    ],
+)]
+class Issue7648Comment extends Model
+{
+    use HasFactory;
+
+    protected $table = 'issue7648_comments';
+
+    public function article(): BelongsTo
+    {
+        return $this->belongsTo(Issue7648Article::class, 'article_id');
+    }
+}

src/Laravel/workbench/database/factories/Issue7648ArticleFactory.php

@@ -0,0 +1,37 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Workbench\Database\Factories;
+
+use Illuminate\Database\Eloquent\Factories\Factory;
+use Workbench\App\Models\Issue7648Article;
+
+/**
+ * @template TModel of Issue7648Article
+ *
+ * @extends Factory<TModel>
+ */
+class Issue7648ArticleFactory extends Factory
+{
+    /** @var class-string<TModel> */
+    protected $model = Issue7648Article::class;
+
+    /** @return array<string, mixed> */
+    public function definition(): array
+    {
+        return [
+            'title' => fake()->sentence(),
+            'content' => fake()->paragraph(),
+        ];
+    }
+}

src/Laravel/workbench/database/factories/Issue7648CommentFactory.php

@@ -0,0 +1,37 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Workbench\Database\Factories;
+
+use Illuminate\Database\Eloquent\Factories\Factory;
+use Workbench\App\Models\Issue7648Comment;
+
+/**
+ * @template TModel of Issue7648Comment
+ *
+ * @extends Factory<TModel>
+ */
+class Issue7648CommentFactory extends Factory
+{
+    /** @var class-string<TModel> */
+    protected $model = Issue7648Comment::class;
+
+    /** @return array<string, mixed> */
+    public function definition(): array
+    {
+        return [
+            'article_id' => Issue7648ArticleFactory::new(),
+            'content' => fake()->paragraph(),
+        ];
+    }
+}

src/Laravel/workbench/database/migrations/2026_03_25_000000_create_issue7648_tables.php

@@ -0,0 +1,41 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    public function up(): void
+    {
+        Schema::create('issue7648_articles', static function (Blueprint $table): void {
+            $table->id();
+            $table->string('title');
+            $table->text('content');
+            $table->timestamps();
+        });
+
+        Schema::create('issue7648_comments', static function (Blueprint $table): void {
+            $table->id();
+            $table->foreignId('article_id')->constrained('issue7648_articles');
+            $table->text('content');
+            $table->timestamps();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('issue7648_comments');
+        Schema::dropIfExists('issue7648_articles');
+    }
+};