Collection::transform
Replaces every item in place with the callback's return value, mutating the collection.
public function transform(callable $callback): staticParameters
| Parameter | Type | Description |
|---|---|---|
$callback | callable(TValue, TKey): mixed | Receives each item and its key and returns the replacement value for that key. |
Return value
$thisThe same collection instance, now holding the transformed items, so the call can be chained.
transform is map that writes back: it computes $this->map($callback)->all() and assigns the result to the collection's own items, then returns $this. Keys are untouched — only values are replaced.
When to reach for it
Rarely, and deliberately. It is the right call when a collection is held in a property or passed by reference and other code already has the same instance, so a replacement object would not be seen: normalising values on a shared collection, or applying a fix-up inside a method whose caller keeps the original handle. It also avoids one array copy in a hot loop over a very large collection, though that is a micro-optimisation you should measure before relying on.
What trips people up
Everything else in the Collection API is immutable, so transform breaks the mental model people have built. The failure is quiet: a helper that calls $collection->transform(...) changes its caller's data, and nothing in the signature warns you. If the collection came from outside your function, prefer map.
The return value is the same instance, not a new one, so $new = $old->transform(...) leaves $new and $old pointing at one object — a strict === comparison between them is true.
Example
When to use it
- Normalise values on a collection stored in an object property
- Trim and lowercase imported rows in place before validating them
- Apply a fix-up inside a method whose caller keeps the original handle
- Avoid a full array copy when rewriting a very large collection
Frequently asked questions
What is the difference between transform and map in Laravel?
transform rewrites the collection you called it on and returns that same instance, while map leaves the source untouched and returns a new collection. Use map unless you specifically need other holders of the collection to see the change.
Can transform() change the keys of a collection?
No. It only replaces values, keeping every key in place. Use mapWithKeys to produce new keys, or keyBy to re-key by a field of each item.
Does transform() return a new collection?
No, it returns $this — the same object. Assigning the result to another variable gives you a second reference to one collection, so a === comparison between them is true.
More examples
The aliasing bug
$raw was never reassigned, yet its contents changed, and $clean is not a copy but the same object. This is the bug report that brings people here. Swapping transform for map inside normalise leaves $raw as the untouched original and hands back a genuinely separate collection.
<?php
function normalise(Illuminate\Support\Collection $emails): Illuminate\Support\Collection
{
// Looks harmless. Rewrites the caller's collection.
return $emails->transform(fn (string $e) => strtolower(trim($e)));
}
$raw = collect([' [email protected] ', '[email protected]']);
$clean = normalise($raw);
print_r($raw->all());
var_dump($raw === $clean);
// Output:
// Array ( [0] => [email protected] [1] => [email protected] )
// bool(true)Keys are preserved, values are not
The callback receives the key as its second argument, which lets each value absorb its own key while the key sequence itself is left alone. Note print_r renders the false boolean as an empty string. transform can change the shape of the values completely; what it can never do is add, remove or rename a key.
<?php
$stock = collect([
'DESK-1' => 4,
'CHAIR-2' => 0,
'LAMP-3' => 12,
]);
$stock->transform(fn (int $qty, string $sku) => [
'sku' => $sku,
'qty' => $qty,
'available' => $qty > 0,
]);
print_r($stock->get('CHAIR-2'));
echo $stock->keys()->implode(', '), "\n";
// Output:
// Array ( [sku] => CHAIR-2 [qty] => 0 [available] => )
// DESK-1, CHAIR-2, LAMP-3
Discussion