Laravel Tutorials

Confidently Extract Single Array Items with Laravel's Arr::sole() Method

Published
Confidently Extract Single Array Items with Laravel's Arr::sole() Method image

Laravel enhances array manipulation with the powerful Arr::sole() method, bringing the functionality of Eloquent's 'sole' operation to standard PHP arrays. This method ensures you retrieve exactly one matching item, eliminating the need for multiple validation checks.

Retrieving an array item while verifying it's the only match typically requires separate checks for existence and uniqueness. The Arr::sole() method combines these operations into a single, expressive call:

use Illuminate\Support\Arr;

// Returns "foo" when it's the only item
Arr::sole(['foo']); // "foo"

// Throws an exception for empty arrays
Arr::sole([]); // Throws ItemNotFoundException

// Throws an exception for multiple items
Arr::sole(['foo', 'bar']); // Throws MultipleItemsFoundException

The method's true power emerges when filtering with callback functions:

use Illuminate\Support\Arr;

// Employee data array
$employees = [
    ['id' => 1, 'name' => 'Sarah', 'department' => 'Engineering'],
    ['id' => 2, 'name' => 'Mike', 'department' => 'Marketing'],
    ['id' => 3, 'name' => 'Alex', 'department' => 'Sales'],
];

// Get the sole engineering employee
$engineer = Arr::sole($employees, fn ($employee) => $employee['department'] === 'Engineering');
// Returns ['id' => 1, 'name' => 'Sarah', 'department' => 'Engineering']

// This would throw MultipleItemsFoundException if multiple engineers existed
// This would throw ItemNotFoundException if no engineers existed

The method's behavior adapts based on the search results:

// Throws ItemNotFoundException for no matches
Arr::sole(['apple', 'banana'], fn (string $fruit) => $fruit === 'orange');

// Throws MultipleItemsFoundException for multiple matches
Arr::sole(['orange', 'apple', 'orange'], fn (string $fruit) => $fruit === 'orange');

In a real application, you might use this for configuration retrieval where exactly one setting should match:

class SettingsManager
{
    public function getActivePaymentGateway(array $gateways)
    {
        return Arr::sole($gateways, fn ($gateway) => $gateway['enabled'] === true);
    }
    
    public function getPrimaryContact(array $contacts)
    {
        return Arr::sole($contacts, fn ($contact) => $contact['is_primary'] === true);
    }
}

The Arr::sole() method creates self-documenting code that clearly expresses your intention to find exactly one item, making your array operations more robust and meaningful.

Harris Raftopoulos photo

Senior Software Engineer • Staff & Educator @ Laravel News • Co-organizer @ Laravel Greece Meetup

Sponsored

laravelcloud logo
Laravel Cloud

Easily create and manage your servers and deploy your Laravel applications in seconds.

Visit Laravel Cloud

The latest

View all →
Laravel AI SDK 1.4 Lets Agents Recover From Tool Failures image

Laravel AI SDK 1.4 Lets Agents Recover From Tool Failures

Read article
Laravel Read Replicas: Check if a Replica Has Caught Up image

Laravel Read Replicas: Check if a Replica Has Caught Up

Read article
UUID Request Input and Migration Failure Events in Laravel 13.42 image

UUID Request Input and Migration Failure Events in Laravel 13.42

Read article
Replay Missed Laravel Scheduled Tasks With Schedule Catchup image

Replay Missed Laravel Scheduled Tasks With Schedule Catchup

Read article
Search Polymorphic Relations and Filament Tables With Laravel Searchable image

Search Polymorphic Relations and Filament Tables With Laravel Searchable

Read article
Laravel Rest Api 3.0: Typed Fields, Metrics, and OpenAPI Docs image

Laravel Rest Api 3.0: Typed Fields, Metrics, and OpenAPI Docs

Read article