Arr::wrap
Wraps a value in an array, passing arrays through unchanged and turning null into an empty array.
public static function wrap($value)Parameters
| Parameter | Type | Description |
|---|---|---|
$$value | mixed | The value to normalise into an array. Arrays pass through unchanged; null becomes []. |
Return value
arrayThe value untouched if it is already an array, an empty array if it is null, otherwise a single-element array containing the value.
Arr::wrap exists so a method can accept either one item or many without branching. Its three rules are the entire implementation: null returns [], an array returns itself, anything else returns [$value].
When to reach for it
- Writing an API that takes a string or an array of strings — roles, tags, event names, class names — and normalising once at the top of the method.
- Making a nullable relation or optional config value safe to
foreachover without anif. - Preparing arguments before a spread or a
call_user_func_array.
What trips people up
The null rule is the whole point. (array) null gives [] too, but [$value] written by hand gives [null] — an array with one element that then runs the loop body once with a null. Arr::wrap gives you an empty loop instead, which is almost always what you meant.
It does not nest existing arrays. Passing ['a' => 1] returns ['a' => 1], not [['a' => 1]]. If you genuinely want to wrap an array inside another, write the literal.
Only null is special. false, 0 and '' are all wrapped as ordinary values, giving [false], [0] and [''].
It is not (array). Casting an object turns its properties into array entries; Arr::wrap puts the object itself in a one-element array.
Example
When to use it
- Let a method accept either a single role name or an array of them.
- Make a nullable value safe to iterate without an is_null check.
- Normalise a mixed string-or-array config option before merging it.
Frequently asked questions
What does Arr::wrap do with null?
It returns an empty array rather than [null], so the result is always safe to loop over without producing a null iteration.
What is the difference between Arr::wrap and casting with (array)?
They agree on null and on scalars, but differ on objects: (array) turns an object's properties into array entries, while Arr::wrap keeps the object as a single element.
Does Arr::wrap nest an array that is passed to it?
No. An array is returned exactly as given, keys and all. Write the literal [[...]] yourself if you really want a nested array.
More examples
Accepting one item or many
The third call is the one that matters: because Arr::wrap(null) is [], the loop body never runs and no null role is ever appended. Writing (array) $roles would behave the same here, but [$roles] would have granted a null role.
<?php
use Illuminate\Support\Arr;
function grant(string $user, string|array|null $roles): string
{
$granted = [];
// One call handles a string, an array, and "nothing".
foreach (Arr::wrap($roles) as $role) {
$granted[] = $role;
}
return $user . ': ' . ($granted ? implode(', ', $granted) : 'none');
}
echo grant('taylor', 'admin'), PHP_EOL;
echo grant('abigail', ['editor', 'reviewer']), PHP_EOL;
echo grant('li', null), PHP_EOL;
/*
taylor: admin
abigail: editor, reviewer
li: none
*/Arr::wrap versus the array cast
For objects the two are completely different: Arr::wrap keeps the object intact as a single element, while (array) converts its public properties into array entries. When you want "one or many of these objects", only Arr::wrap is correct.
<?php
use Illuminate\Support\Arr;
class Point
{
public function __construct(public int $x = 1, public int $y = 2) {}
}
$point = new Point;
// Arr::wrap puts the object in a one-element array.
$wrapped = Arr::wrap($point);
var_dump(count($wrapped), $wrapped[0] instanceof Point);
// The array cast explodes the object into its properties.
$cast = (array) $point;
print_r($cast);
/*
int(1)
bool(true)
Array
(
[x] => 1
[y] => 2
)
*/
Discussion