feat: PUT is now disabled by default (#1986)

Author: dunglas

core/getting-started.md

@@ -156,10 +156,14 @@ Method | URL            | Description
 GET    | /products      | Retrieve the (paginated) collection
 POST   | /products      | Create a new product
 GET    | /products/{id} | Retrieve a product
-PUT    | /products/{id} | Update a product
 PATCH  | /products/{id} | Apply a partial modification to a product
 DELETE | /products/{id} | Delete a product
 
+> [!NOTE]
+>
+> `PUT` (replace or create) isn't registered automatically,
+> but is entirely supported by API Platform and can be added explicitly.
+
 The same operations are available for the offer method (routes will start with the `/offers` pattern).
 Route prefixes are built by pluralizing the name of the mapped entity class.
 It is also possible to override the naming convention using [operation path namings](operation-path-naming.md).

core/operations.md

@@ -17,28 +17,30 @@ is also possible.
 
 There are two types of operations: collection operations and item operations.
 
-Collection operations act on a collection of resources. By default two routes are implemented: `POST` and `GET`. Item
-operations act on an individual resource. Four default routes are defined: `GET`, `PUT`, `DELETE` and `PATCH`. `PATCH` is supported
+Collection operations act on a collection of resources. By default two operations are implemented: `POST` and `GET`. Item
+operations act on an individual resource. Three default operation are defined: `GET`, `DELETE` and `PATCH`. `PATCH` is supported
 with [JSON Merge Patch (RFC 7396)](https://www.rfc-editor.org/rfc/rfc7386), or [using the JSON:API format](https://jsonapi.org/format/#crud-updating), as required by the specification.
 
+The `PUT` operation is also supported, but is not registered by default.
+
 When the `ApiPlatform\Metadata\ApiResource` annotation is applied to an entity class, the following built-in CRUD
 operations are automatically enabled:
 
 Collection operations:
 
-Method | Mandatory | Description
--------|-----------|------------------------------------------
-`GET`  | yes       | Retrieve the (paginated) list of elements
-`POST` | no        | Create a new element
+Method | Mandatory | Description                               | Registered by default
+-------|-----------|-------------------------------------------|----------------------
+`GET`  | yes       | Retrieve the (paginated) list of elements | yes
+`POST` | no        | Create a new element                      | yes
 
 Item operations:
 
-Method   | Mandatory | Description
----------|-----------|-------------------------------------------
-`GET`    | yes       | Retrieve an element
-`PUT`    | no        | Replace an element
-`PATCH`  | no        | Apply a partial modification to an element
-`DELETE` | no        | Delete an element
+Method   | Mandatory | Description                                | Registered by default
+---------|-----------|--------------------------------------------|----------------------
+`GET`    | yes       | Retrieve an element                        | yes
+`PUT`    | no        | Replace an element                         | no
+`PATCH`  | no        | Apply a partial modification to an element | yes
+`DELETE` | no        | Delete an element                          | yes
 
 Note: the `PATCH` method must be enabled explicitly in the configuration, refer to the [Content Negotiation](content-negotiation.md) section for more information.
 
@@ -563,7 +565,7 @@ class Weather
     // ...
 ```
 
-This will expose the `Weather` model, but also all the default CRUD routes: `GET`, `PUT`, `PATCH`, `DELETE` and `POST`, which is nonsense in our context.
+This will expose the `Weather` model, but also all the default CRUD routes: `GET`, `PATCH`, `DELETE` and `POST`, which is nonsense in our context.
 Since we are required to expose at least one route, let's expose just one:
 
 ```php

core/serialization.md

@@ -189,7 +189,7 @@ basis. API Platform will always use the most specific definition. For instance,
 at the resource level and at the operation level, the configuration set at the operation level will be used and the resource
 level ignored.
 
-In the following example we use different serialization groups for the `GET` and `PUT` operations:
+In the following example we use different serialization groups for the `GET` and `PATCH` operations:
 
 <code-selector>
 
@@ -200,15 +200,15 @@ namespace App\Entity;
 
 use ApiPlatform\Metadata\ApiResource;
 use ApiPlatform\Metadata\Get;
-use ApiPlatform\Metadata\Put;
+use ApiPlatform\Metadata\Patch;
 use Symfony\Component\Serializer\Annotation\Groups;
 
 #[ApiResource(normalizationContext: ['groups' => ['get']])]
 #[Get]
-#[Put(normalizationContext: ['groups' => ['put']])]
+#[Patch(normalizationContext: ['groups' => ['patch']])]
 class Book
 {
-    #[Groups(['get', 'put'])]
+    #[Groups(['get', 'patch'])]
     public $name;
 
     #[Groups('get')]
@@ -225,15 +225,15 @@ App\Entity\Book:
         groups: ['get']
     operations:
         ApiPlatform\Metadata\Get: ~
-        ApiPlatform\Metadata\Put:
+        ApiPlatform\Metadata\Patch:
             normalizationContext:
-                groups: ['put']
+                groups: ['patch']
 
 # api/config/serializer/Book.yaml
 App\Entity\Book:
     attributes:
         name:
-            groups: ['get', 'put']
+            groups: ['get', 'patch']
         author:
             groups: ['get']
 ```
@@ -257,12 +257,12 @@ App\Entity\Book:
         </normalizationContext>
         <operations>
             <operation class="ApiPlatform\Metadata\Get" />
-            <operation class="ApiPlatform\Metadata\Put">
+            <operation class="ApiPlatform\Metadata\Patch">
                 <normalizationContext>
             <values>
                 <value name="groups">
                     <values>
-                        <value>put</value>
+                        <value>patch</value>
                     </values>
                 </value>
             </values>
@@ -281,7 +281,7 @@ App\Entity\Book:
     <class name="App\Entity\Book">
         <attribute name="name">
             <group>get</group>
-            <group>put</group>
+            <group>patch</group>
         </attribute>
         <attribute name="author">
             <group>get</group>
@@ -293,7 +293,7 @@ App\Entity\Book:
 </code-selector>
 
 The `name` and `author` properties will be included in the document generated during a `GET` operation because the configuration
-defined at the resource level is inherited. However the document generated when a `PUT` request will be received will only
+defined at the resource level is inherited. However the document generated when a `PATCH` request will be received will only
 include the `name` property because of the specific configuration for this operation.
 
 Refer to the [operations](operations.md) documentation to learn more.

distribution/index.md

@@ -494,9 +494,11 @@ In Swagger UI, click on the `POST` operation of the `Book` resource type, click
 You just saved a new book resource through the bookshop API! API Platform automatically transforms the JSON document to
 an instance of the corresponding PHP entity class and uses Doctrine ORM to persist it in the database.
 
-By default, the API supports `GET` (retrieve, on collections and items), `POST` (create), `PUT` (replace), `PATCH` (partial update) and `DELETE` (self-explanatory)
+By default, the API supports `GET` (retrieve, on collections and items), `POST` (create), `PATCH` (partial update) and `DELETE` (self-explanatory)
 HTTP methods. Don't forget to [disable the ones you don't want](../core/operations.md#enabling-and-disabling-operations)!
 
+The `PUT` (replace or create) method is also supported, but is not enabled by default.
+
 Try the `GET` operation on the collection. The book we added appears. When the collection contains more than 30 items,
 the pagination will automatically show up, [and this is entirely configurable](../core/pagination.md). You may be interested
 in [adding some filters and adding sorts to the collection](../core/filters.md) as well.