[Bug]: Inferred data wrapping on nested arrays of Laravel Data objects

[ccrosby-super]

What happened?

With config('data.wrap') set to 'data', we're seeing Laravel Data objects with nested arrays of Laravel Data objects that have data wrapping in schema, despite their responses not being wrapped. i.e.:

class ProductData extends Data
{
    /**
     * Initialize a new ProductData (plans) instance.
     *
     * @param array<int, PriceData> $prices The collection of prices associated with the product
     */
    public function __construct(
        public readonly array $prices,
    ) {
    }
}

generates schema as:

"prices": {
    "type": "object",
    "properties": {
      "data": {
        "type": "array",

despite the response having prices not wrapped in 'data'.

The outer data wrapper (on ProductData as a whole) is expected.

How to reproduce the bug

Create a Laravel Data object that contains an array of Data Objects within it like my example above with ProductData and PriceData[].

Generate api.json with php artisan scramble:export

Observe schema that wraps PriceData[] in data, and observe responses that do not wrap PriceData[].

Package Version

Scramble PRO: 0.9.15, Scramble: 0.13.42

PHP Version

8.5.2

Laravel Version

13.26.1

Which operating systems does with happen with?

No response

Notes

We have attempted a few workarounds (using my example):

1. Using array<int, PriceData> and/or PriceData[] in the PHPDoc for the constructor of ProductData
2. Using @var annotations:

       /**
         * @var PriceData[]
        */
        public readonly array $prices,

3. Using #[DataCollectionOf(PriceData::class)]
4. Combinations of the above attempts

[romalytvynenko]

Hey @ccrosby-super

I cannot reproduce the issue.

Sorry for the large comment in advance.

Would be great if you can share the repo with the reproduction, I'll be happy to fix the issue!

Here is my Laravel Data config:

// config/data.php
<?php

return [
    // Global response wrapper used by Laravel Data.
    'wrap' => 'data',
];

Here is my test controller:

<?php

namespace App\Http\Controllers;

use App\Data\PriceData;
use App\Data\ProductData;
use Spatie\LaravelData\DataCollection;

class ProductDataController extends Controller
{
    public function show(): ProductData
    {
        return $this->product('Scramble Pro');
    }

    /**
     * @return DataCollection<int, ProductData>
     */
    public function index(): DataCollection
    {
        return new DataCollection(ProductData::class, [
            $this->product('Scramble'),
            $this->product('Scramble Pro'),
        ]);
    }

    private function product(string $name): ProductData
    {
        return new ProductData(
            name: $name,
            prices: [
                new PriceData(currency: 'USD', amount: 9900),
                new PriceData(currency: 'EUR', amount: 8900),
            ],
        );
    }
}

Here are my data classes:

// app/Data/ProductData.php

<?php

namespace App\Data;

use Spatie\LaravelData\Data;

class ProductData extends Data
{
    /**
     * @param  array<int, PriceData>  $prices
     */
    public function __construct(
        public readonly string $name,
        public readonly array $prices,
    ) {}
}

// app/Data/PriceData.php
<?php

namespace App\Data;

use Spatie\LaravelData\Data;

class PriceData extends Data
{
    public function __construct(
        public readonly string $currency,
        public readonly int $amount,
    ) {}
}

Here is how I registered the routes:

// routes/api.php
<?php

use App\Http\Controllers\ProductDataController;
use Illuminate\Support\Facades\Route;

Route::prefix('products')->controller(ProductDataController::class)->group(function (): void {
    Route::get('single', 'show');
    Route::get('collection', 'index');
});

And here are the versions of Laravel Data and Laravel:

laravel/framework                  13.25.0 
spatie/laravel-data                4.23.0

And finally (haha) here is the exported document:

{
    "openapi": "3.1.0",
    "info": {
        "title": "Laravel",
        "version": "0.0.1"
    },
    "servers": [
        {
            "url": "http://l12.test/api"
        }
    ],
    "paths": {
        "/products/single": {
            "get": {
                "operationId": "productData.show",
                "tags": [
                    "ProductData"
                ],
                "responses": {
                    "200": {
                        "description": "`ProductData`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/ProductData"
                                        }
                                    },
                                    "required": [
                                        "data"
                                    ]
                                }
                            }
                        }
                    }
                }
            }
        },
        "/products/collection": {
            "get": {
                "operationId": "productData.index",
                "tags": [
                    "ProductData"
                ],
                "responses": {
                    "200": {
                        "description": "The collection of `App.Data.ProductData`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/ProductData"
                                            }
                                        }
                                    },
                                    "required": [
                                        "data"
                                    ]
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "PriceData": {
                "type": "object",
                "properties": {
                    "currency": {
                        "type": "string"
                    },
                    "amount": {
                        "type": "integer"
                    }
                },
                "required": [
                    "currency",
                    "amount"
                ],
                "title": "PriceData"
            },
            "ProductData": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string"
                    },
                    "prices": {
                        "type": "object",
                        "properties": {
                            "data": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/PriceData"
                                }
                            }
                        },
                        "required": [
                            "data"
                        ]
                    }
                },
                "required": [
                    "name",
                    "prices"
                ],
                "title": "ProductData"
            }
        }
    }
}

And in this case, data wrapping actually matches the response:

[ccrosby-super]

Sorry, I actually have it mixed up a bit. We did some more playing around with it and it looks like we previously had nested arrays to avoid data wrapping, but that is truly changed in responses and schema. What sparked this issue was nested DataCollections being wrapped, despite their responses being unwrapped. I recreated your repro files but with the distinction that ProductData has a DataCollection of PriceData:

    /**
     * @param  string  $name
     * @param  DataCollection  $prices
     */
    public function __construct(
        public readonly string $name,
        /**
         * @var  PriceData[]  $prices
         */
        #[DataCollectionOf(PriceData::class)]
        public readonly DataCollection $prices,
    ) {}

prices is unwrapped in our responses, but wrapped in our generated schema.

Sorry again that I got that spun around!

[ccrosby-super]

We were also able to confirm that rolling back Scramble PRO to 0.9.14 with no other changes resulted in prices being correctly unwrapped in schema.

[romalytvynenko]

Hey @ccrosby-super

Thanks for clarification. Explored this rabbit hole and it seems like a bug in Laravel Data - DataCollection properties were wrapped in wrap key prior to 4.3.0 release (in 4.2.0 DataCollection property is wrapped). Also, this is the expected behaviour looking at their docs.

I will create issue and a PR in Laravel Data repo, and based on reply I'll decide what to do next. While it seems to be a bug, at the same time this created behaviour a lot of people rely on. I will keep you updated.

Let me know what you think!

P.S.: Scramble PRO 0.9.15 started wrapping properties according to the documentation, and it works well for all properties except DataCollection

[romalytvynenko]

Hey @ccrosby-super

Created the issue and a PR for Laravel Data.

The issue: spatie/laravel-data#1209
The PR: spatie/laravel-data#1208

The fix in Scramble PRO will depend on how Spatie team treats the issue. If they decide to keep current behavior due to this being a behavior for ~2 years - then I will adapt Scramble PRO to it.