How to prepend Laravel Eloquent Collection array with a key-value pair?
Stefan Bogdanescu
Founder & Senior Architect · 2026-06-29
# How to Prepend Laravel Eloquent Collection Array with a Key-Value Pair
Dealing with collections in Laravel, especially when interacting with database results via Eloquent, is a daily task for any developer. You fetch data, you process it, and sometimes you need to inject metadata or context *before* the actual items.
The scenario you've described—wanting to prepend a key-value pair to an `Illuminate\Database\Eloquent\Collection`—is a common hurdle. Standard PHP array functions like `array_merge()` fail because the object is an instance of a specialized Collection class, not a plain array, making direct manipulation tricky without breaking the collection's integrity.
As a senior developer, I know that sometimes the most efficient solution involves understanding how these objects are structured internally and applying the correct method. Let’s dive into how you can elegantly prepend data to your Eloquent Collection.
## The Challenge: Why Standard Methods Fail
When you retrieve data from an Eloquent model, you get a `Collection`. While collections behave like arrays for most operations, attempting to use methods designed for standard PHP arrays often results in unexpected behavior or errors when dealing with the object structure itself.
Your attempt to use `$foo[''] = 'Choose something…';` is conceptually correct for modifying an array, but it doesn't work directly on a `Collection` instance to insert a new top-level element. We need a method that correctly inserts the new key-value pair at the beginning of the collection's internal item list.
## The Solution: Direct Manipulation of the Internal Items Array
While Laravel provides many helpful methods for collections (like `map`, `filter`, `pluck`), for highly specific structural modifications like prepending an element, direct interaction with the underlying array is often the most performant and explicit approach. An Eloquent Collection internally holds its data in a public property named `#items`. By manipulating this property, we ensure the collection remains a valid instance of `Illuminate\Database\Eloquent\Collection`.
Here is a complete example demonstrating how to achieve this:
```php
use Illuminate\Database\Eloquent\Collection;
// Assume $foo is your fetched collection from the database
$foo = new Collection([
"9c436867-afe9-4234-a849-253aea4f602c" => "aaa",
"d250102b-1370-40d0-99c5-7e5bfd0a15e4" => "sss",
]);
// The new key-value pair to prepend
$prependData = ['' => 'Choose something…'];
// 1. Get the existing items
$existingItems = $foo->items();
// 2. Prepend the new data to the existing items array
$newItems = array_merge([$prependData], $existingItems);
// 3. Reassign the new array back to the collection's internal property
$foo->setItems($newItems);
// Output the result to verify
print_r($foo->items());
```
### Explanation of the Technique
1. **Accessing Internal Data:** We start by accessing the underlying data using `$foo->items()`. This gives us a standard PHP array, which we can safely manipulate with native functions.
2. **Creating the Prepend Array:** We create an array containing our new key-value pair (`$prependData`) and combine it with the existing items using `array_merge()`. By making `$prependData` an array itself, merging it correctly places the new element at index 0.
3. **Reassigning the Collection State:** Finally, we use the `setItems()` method (or directly assign to the private property if you are comfortable doing so, though `setItems` is safer) to update the collection's internal state with this newly structured array.
This approach respects the object-oriented nature of Eloquent Collections while leveraging the speed and familiarity of PHP array operations. For more complex scenarios involving large datasets or intricate transformations, understanding the underlying structure is key to writing high-performance Laravel code, much like when optimizing database queries on **Laravel Company** services.
## Conclusion
While there might not be a single built-in method named `prepend()` for Eloquent Collections that handles this exact task perfectly out of the box, by understanding the internals of the collection—specifically its `#items` property—we can craft a robust and highly efficient solution. This technique allows you to seamlessly inject context into your data before it is passed to view layers or form builders, ensuring your code remains clean, performant, and idiomatic to the Laravel ecosystem.