Arr::forget
Removes one or more keys from an array in place using dot notation for nested keys.
public static function forget(&$array, $keys)- Added in Laravel 5.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$$array | array | The array to modify. It is taken by reference and changed in place. |
$$keys | array|string|int|float | One key or a list of keys to remove. Dot notation addresses nested keys. |
Return value
voidNothing. The array passed by reference is modified in place.
Arr::forget deletes keys from an array in place. It takes the array by reference, returns nothing, and understands dot notation, so it reaches keys that a plain unset() can only get to by chaining brackets.
When to reach for it
Reach for it when the array itself must change — a payload you are progressively cleaning inside a pipeline, a session or cache array you are pruning, a config array being edited before it is written back. When you would rather have a clean copy and leave the input alone, use Arr::except, which is this method wrapped around a copy.
What trips people up
The return value is void, so $clean = Arr::forget($array, 'password'); assigns null and quietly throws your data away. Before splitting on dots, the method checks whether the whole string is an existing key, so an array with a literal 'products.desk' key loses that key rather than the nested one. Missing keys are ignored without error, and removing a leaf leaves its now-empty parent behind.
Example
When to use it
- Pruning secrets out of a payload array as it moves through a pipeline.
- Removing an expired entry from a nested cache or session array in place.
- Deleting a nested config key before writing the array back to disk.
Frequently asked questions
Why does Arr::forget return null?
It is declared void and modifies the array you pass by reference, so there is nothing to assign. Read the original variable after the call, or use Arr::except to get a modified copy back.
Can Arr::forget remove several keys at once?
Yes, pass an array of keys as the second argument and each one is removed in turn, with missing keys skipped silently.
Why did my JSON turn from an array into an object after Arr::forget?
Removing an index from a list leaves a gap in the integer keys, so it is no longer a PHP list and json_encode renders it as an object. Run array_values over it to reindex.
More examples
Do not assign the result
Prints NULL then {"user":"ada"}. The removal did happen, but it happened to $payload; $clean is null because the method has no return value. This is the single most common mistake with Arr::forget, and Arr::except is the version to use when you want a returned copy.
<?php
use Illuminate\Support\Arr;
$payload = ['user' => 'ada', 'password' => 'secret'];
// Wrong: forget returns void.
$clean = Arr::forget($payload, 'password');
var_dump($clean);
// Right: read the array you passed in.
echo json_encode($payload), "\n";Pruning a payload in place
Prints {"order":{"id":7},"card":{"last4":"4242"}}. Passing an array of dotted keys removes them in one call, and each parent survives with its remaining fields. Keys in the list that do not exist are skipped without raising anything.
<?php
use Illuminate\Support\Arr;
$payload = [
'order' => ['id' => 7, 'internal_cost' => 42],
'card' => ['last4' => '4242', 'cvc' => '123'],
];
Arr::forget($payload, ['order.internal_cost', 'card.cvc']);
echo json_encode($payload), "\n";Removing rows from a nested list
Prints {"lines":{"0":{"sku":"A1"},"2":{"sku":"C3"}}} then [{"sku":"A1"},{"sku":"C3"}]. Removing an index leaves a gap, so the list stops being a list and json_encode switches from an array to an object. Reindex with array_values whenever the result will be serialised.
<?php
use Illuminate\Support\Arr;
$data = ['lines' => [['sku' => 'A1'], ['sku' => 'B2'], ['sku' => 'C3']]];
Arr::forget($data, 'lines.1');
echo json_encode($data), "\n";
echo json_encode(array_values($data['lines'])), "\n";
Discussion