transform
Applies a callback only when the value is filled, returning a default for blank values.
transform(mixed $value, callable $callback, mixed $default = null): mixedParameters
| Parameter | Type | Description |
|---|---|---|
$$value | mixed | The value tested with filled() and passed to the callback. |
$$callback | callable | Called with the value when the value is not blank. |
$$defaultoptional | mixed= null | Returned when the value is blank; if callable, it is invoked with the original value. |
Return value
mixedThe callback's return value when the value is filled, otherwise the default (invoked with the value if it is callable).
Errors
Nothing of its own; exceptions raised inside the callback or the callable default propagate to the caller.
See also
transform() is with() plus a blankness guard. It runs filled() on the value; if the value is filled the callback runs and its result is returned, otherwise you get the default. A callable default is invoked with the original value, so the fallback can be built from whatever was actually there.
When to reach for it
Reach for it when a nullable input needs exactly one cheap conversion and a three-line if would be noise: turning an optional date string into a Carbon instance, casting an optional query parameter to an integer, formatting a nullable money column for display.
What trips people up
"Blank" is not "falsy". filled(0) and filled(false) are both true, so transform(0, $callback) runs the callback and you get 0 doubled rather than the default. What actually counts as blank is null, a string that is empty after trim(), an empty Countable such as an empty Collection, and anything else PHP's empty() reports as empty. An empty array is blank; the integer zero is not.
Note too that a non-callable default is returned exactly as given — it is never passed through the callback.
Example
When to use it
- Convert an optional request date string into a Carbon instance, or a fallback label.
- Format a nullable price column, showing a dash when it is not set.
- Cast an optional filter parameter to an int without writing a null check.
Frequently asked questions
Does transform() run the callback when the value is 0?
Yes. transform() guards on filled(), and filled(0) is true because blank() explicitly reports numeric and boolean values as not blank. Only null, whitespace-only strings, empty Countables and values PHP's empty() rejects fall through to the default.
What is the difference between transform() and with()?
with() always calls the callback; transform() calls it only when the value is filled and otherwise returns a default. If your input can never be blank, the two are equivalent and with() is the simpler read.
Can the default argument of transform() be a closure?
Yes, and it is called with the original blank value. transform($value, $callback, fn ($v) => ...) lets you build the fallback from whatever was there, which is useful when you want to distinguish null from an empty string in the result.
More examples
Blank versus falsy, side by side
Prints 10 for 5, 0 for both 0 and false (the callback ran and doubled a falsy-but-filled value), and 'DEFAULT' for the empty string, the whitespace-only string, the empty array and null. This is the exact boundary filled() draws, and it is not the boundary a plain if ($value) would draw.
<?php
$double = fn ($v) => $v * 2;
$values = [
'int 5' => 5,
'int 0' => 0,
'false' => false,
'empty string' => '',
'spaces' => ' ',
'empty array' => [],
'null' => null,
];
foreach ($values as $label => $value) {
printf("%-13s => %s\n", $label, var_export(transform($value, $double, 'DEFAULT'), true));
}An optional date field
The first call parses the date because the string is filled; the second never touches Carbon::parse(), which would have thrown on null. Carbon::setTestNow() pins the clock so the output is identical on every run.
<?php
use Carbon\Carbon;
Carbon::setTestNow('2026-03-01 12:00:00');
$input = ['published_at' => '2026-02-14', 'archived_at' => null];
$published = transform($input['published_at'], fn (string $d) => Carbon::parse($d)->toDateString());
$archived = transform($input['archived_at'], fn (string $d) => Carbon::parse($d)->toDateString(), 'not archived');
echo $published, "\n"; // 2026-02-14
echo $archived, "\n"; // not archivedA callable default sees the original value
When the default is callable it is invoked with the same value the callback would have received, so the fallback can report or log which kind of blank it was. A non-callable default, by contrast, is returned verbatim without ever seeing the value.
<?php
$default = function ($value) {
return 'blank input: '.var_export($value, true);
};
echo transform('', fn (string $v) => strtoupper($v), $default), "\n";
// blank input: ''
echo transform(null, fn (string $v) => strtoupper($v), $default), "\n";
// blank input: NULL
Discussion