[Bug]: toArray() on a mapped collection breaks inference

[rossbearman]

What happened?

We have a large number of resources that include data that is mapped over a collection. Due to reasons lost to time, the resulting Collection is cast to an array before being returned, with toArray().

If this happens directly in the Resource's toArray() method, Scramble infers it as a string. If the mapping happens in a separate method which type hints the array return, it's inferred as an array with no defined properties.

We're just going to work through the codebase and remove all the toArray() castings, as they're unnecessary, but I thought this report might help identify an issue in the inference engine, as the type data is all there in the AST.

How to reproduce the bug

class ProductEditResource extends JsonResource
{
    public function toArray($request): array
    {
        return [
            'variations' => $this->variations->map(function (Variation $variation) {
                return [
                    'id' => $variation->id,
                    'name' => $variation->name,
                    'product_variation_id' => $variation->pivot->id,
                ];
           })->toArray(),
        ];
    }
}

This returns the following in the schema:

"variations": {
  "type": "string"
}

If I extract the map into a method with an array return type:

class ProductEditResource extends JsonResource
{
    public function toArray($request): array
    {
        return [
            'variations' => $this->variations(),
        ];
    }

    private function variations(): array
    {
        return $this->variations->map(function (Variation $variation) {
            return [
                'id' => $variation->id,
                'name' => $variation->name,
                'product_variation_id' => $variation->pivot->id,
            ];
        })->toArray(),
    }
}

It gets rendered as this in the schema:

"variations": {
  "type": "array",
  "items": {}
}

If the toArray() is dropped from the map, it correctly infers the shape of the data.

Package Version

0.13.17

PHP Version

8.4

Laravel Version

10

Which operating systems does with happen with?

Linux

Notes

No response

[rossbearman]

We're actually seeing the same behaviour with a Collection in the following context. Scramble evalutes items to be a string.

class PageContentResource extends JsonResource
{
    public function toArray($request): array
    {
        $data = [
            'items' => $this->items(),
        ];

        return $this->processData($data);
    }

    private function items(): Collection
    {
        return $this->publishedItems->mapWithKeys(function (PageItem $item) {
            return [$item->key => $this->nodes($item)];
        });
    }

    private function nodes(PageItem|PageItemNode $item): Collection
    {
        return $item->nodes->map(function (PageItemNode $node) {
            $data = [
                'type' => $node->type,
            ];

            if ($node->content) {
                $data['content'] = $node->content->html;
            } else {
                $data['nodes'] = $this->nodes($node);
            }

            return $data;
        });
    }

[rossbearman]

Can confirm that last one is still present on Laravel 13.

[romalytvynenko]

@rossbearman I'm currently considering what to do with this issue. If you check the annotation of toArray(), you can see its return is annotated as array<TKey, mixed> (or something like that). So the information about the specific collection item shape is lost.

I'm currently evaluating what to do.

[rossbearman]

Thanks for looking into it @romalytvynenko!

Is it possible to provide a doc hint for Scramble in this situation?

[romalytvynenko]

Hey @rossbearman

Sorry for the late reply.

toArray loosing the objects shape, and that non-working second example are different issues (at least it looks like that).

In both cases you can use doc hint. However, I would also like to try to fix it in Scramble so you don't need a PHPDoc hint.

First of all, make sure you are on the latest Scramble (0.13.22 at the moment), there were inference improvements since 0.13.17.

If you still don't get good shapes, you can use PHPDoc:

class ProductEditResource extends JsonResource
{
    public function toArray($request): array
    {
        return [
+           /** @var array{id: int, name: string, product_variation_id: int}[] */
            'variations' => $this->variations(),
        ];
    }

    private function variations(): array
    {
        return $this->variations->map(function (Variation $variation) {
            return [
                'id' => $variation->id,
                'name' => $variation->name,
                'product_variation_id' => $variation->pivot->id,
            ];
        })->toArray(),
    }
}

(this second example seems like a bug or a possible improvement, but you can fix it like this):

class PageContentResource extends JsonResource
{
+   /**
+    * @scramble-return ...
+    */
    public function toArray($request): array
    {
        $data = [
            'items' => $this->items(),
        ];

        return $this->processData($data);
    }

    private function items(): Collection
    {
        return $this->publishedItems->mapWithKeys(function (PageItem $item) {
            return [$item->key => $this->nodes($item)];
        });
    }

    private function nodes(PageItem|PageItemNode $item): Collection
    {
        return $item->nodes->map(function (PageItemNode $node) {
            $data = [
                'type' => $node->type,
            ];

            if ($node->content) {
                $data['content'] = $node->content->html;
            } else {
                $data['nodes'] = $this->nodes($node);
            }

            return $data;
        });
    }
}

@scramble-return is undocumented annotation, so its behavior MAY change.

I will leave updates here soon.