docs: document allowCreate for PUT upsert

core/operations.md

@@ -63,6 +63,60 @@ Item operations:
 > properties not included in the payload are **not** removed, their current values are preserved. To
 > remove an existing property, its value must be explicitly set to `null`.
 
+## Upsert: Creating a Resource With PUT
+
+By default, sending a `PUT` request to an item that does not exist returns a `404 Not Found`. To
+enable an "upsert" behavior (update the resource if it exists, create it otherwise), set the
+`allowCreate` property to `true` on the `PUT` operation. The identifier provided in the URI is then
+used for the new resource and a `201 Created` response is returned when the item did not exist.
+
+<code-selector>
+
+```php
+<?php
+// api/src/Entity/Book.php
+namespace App\Entity;
+
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Put;
+
+#[ApiResource(
+    operations: [
+        new Put(allowCreate: true),
+    ]
+)]
+class Book
+{
+    // ...
+}
+```
+
+```yaml
+# api/config/api_platform/resources.yaml
+resources:
+    App\Entity\Book:
+        operations:
+            ApiPlatform\Metadata\Put:
+                allowCreate: true
+```
+
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<!-- api/config/api_platform/resources.xml -->
+<resources xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+           xmlns="https://api-platform.com/schema/metadata/resources-3.0"
+           xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
+           https://api-platform.com/schema/metadata/resources-3.0.xsd">
+    <resource class="App\Entity\Book">
+        <operations>
+            <operation class="ApiPlatform\Metadata\Put" allowCreate="true" />
+        </operations>
+    </resource>
+</resources>
+```
+
+</code-selector>
+
 ## Enabling and Disabling Operations
 
 If no operation is specified, all default CRUD operations are automatically registered. It is also

laravel/index.md

@@ -734,7 +734,9 @@ You can change the default configuration (for instance, which operations are ena
 the config (`config/api-platform.php`).
 
 For the rest of this tutorial, we'll assume that at least all default operations are enabled (you
-can also enable `PUT` if you want to support upsert operations).
+can also enable `PUT`, optionally with
+[`allowCreate: true`](../core/operations.md#upsert-creating-a-resource-with-put) if you want to
+support upsert operations).
 
 ## Adding Filters