[12.x] Fix: Add $forceWrap property to JsonResource for consistent API response #56724

src/Illuminate/Http/Resources/Json/JsonResource.php

@@ -49,6 +49,13 @@ class JsonResource implements ArrayAccess, JsonSerializable, Responsable, UrlRou
      */
     public static $wrap = 'data';
 
+    /**
+     * Whether to force wrapping even if the $wrap key exists in underlying resource data.
+     *
+     * @var bool
+     */
+    public static bool $forceWrapping = false;
+
     /**
      * Create a new resource instance.
      *

src/Illuminate/Http/Resources/Json/ResourceResponse.php

@@ -80,6 +80,10 @@ protected function wrap($data, $with = [], $additional = [])
      */
     protected function haveDefaultWrapperAndDataIsUnwrapped($data)
     {
+        if ($this->resource instanceof JsonResource && $this->resource::$forceWrapping) {
+            return $this->wrapper() !== null;
+        }
+
         return $this->wrapper() && ! array_key_exists($this->wrapper(), $data);
     }
 

tests/Integration/Http/ResourceTest.php

@@ -1853,6 +1853,61 @@ public function testItThrowsNoErrorInStrictModeWhenResourceIsPaginated()
         }
     }
 
+    public function testResourceSkipsWrappingWhenDataKeyExists()
+    {
+        $resource = new class(['id' => 5, 'title' => 'Test', 'data' => 'some data']) extends JsonResource
+        {
+            public static $wrap = 'data';
+        };
+
+        $response = $resource->toResponse(request());
+        $content = json_decode($response->getContent(), true);
+
+        $this->assertEquals([
+            'id' => 5,
+            'title' => 'Test',
+            'data' => 'some data',
+        ], $content);
+    }
+
+    public function testResourceWrapsWhenDataKeyDoesNotExist()
+    {
+        $resource = new class(['id' => 5, 'title' => 'Test']) extends JsonResource
+        {
+            public static $wrap = 'data';
+        };
+
+        $response = $resource->toResponse(request());
+        $content = json_decode($response->getContent(), true);
+
+        $this->assertEquals([
+            'data' => [
+                'id' => 5,
+                'title' => 'Test',
+            ],
+        ], $content);
+    }
+
+    public function testResourceForceWrapOverridesDataKeyCheck()
+    {
+        $resource = new class(['id' => 5, 'title' => 'Test', 'data' => 'some data']) extends JsonResource
+        {
+            public static $wrap = 'data';
+            public static bool $forceWrapping = true;
+        };
+
+        $response = $resource->toResponse(request());
+        $content = json_decode($response->getContent(), true);
+
+        $this->assertEquals([
+            'data' => [
+                'id' => 5,
+                'title' => 'Test',
+                'data' => 'some data',
+            ],
+        ], $content);
+    }
+
     private function assertJsonResourceResponse($data, $expectedJson)
     {
         Route::get('/', function () use ($data) {