`hasSole()` Collection Method in Laravel 12.49.0

Release Date: January 28, 2026 Laravel Version: 12.49.0

Summary

Laravel v12.49.0 introduces a new hasSole() collection method for checking if a collection contains exactly one matching item, along with subquery between columns support, fluent resource collection key preservation, and datetime support for the maintenance mode command. This release also expands enum support across session and cache components.

Key highlights include:

• New hasSole() collection method (deprecates containsOneItem())
• Subquery between columns in the query builder
• preserveKeys() method for fluent resource collection chaining
• Datetime values for down --retry option
• Enum support for Session now() and flash() methods
• Enum keys in Cache::flexible() and withoutOverlapping()
• Searchable prompt for db:table command
• Memory leak fix in Arr::dot()

#What's New

#hasSole() Collection Method

Laravel 12.49.0 adds the hasSole() method to collections, providing a concise way to check if a collection contains exactly one item matching specified criteria. This method aligns with Laravel's existing sole() nomenclature and deprecates the older containsOneItem() method.

// Check if collection has exactly one item
$collection->hasSole();
 
// With a callback filter
$collection->hasSole(fn ($item) => $item->active);
 
// With key/value pair
$collection->hasSole('status', 'pending');
 
// With operator syntax
$collection->hasSole('age', '>=', 21);

The method supports the same flexible filter signatures as sole(), making it intuitive for developers already familiar with Laravel's collection API.

Pull Request: #58463

#Subquery Between Columns

The query builder now supports comparing a subquery result against two database columns using whereBetweenColumns():

$query->whereBetweenColumns($subquery, ['min_value', 'max_value']);

This allows you to check if a subquery result falls between dynamic column values from the table, rather than hardcoded constants. This is a follow-up to previous work adding subquery support with static value ranges.

Pull Request: #58441

#preserveKeys() for Resource Collections

The AnonymousResourceCollection now includes a preserveKeys() method for fluent chaining, eliminating the need for intermediate variable assignment:

// Before
$collection = JsonResource::collection($posts);
$collection->preserveKeys = true;
return $collection;
 
// After
return JsonResource::collection($posts)->preserveKeys();

This improvement makes resource collection configuration more readable and consistent with Laravel's fluent API patterns.

Pull Request: #58443

#Datetime Support for Down Command

The php artisan down command's --retry option now accepts datetime strings in addition to numeric seconds:

# Retry at a specific datetime
php artisan down --retry="2026-01-28 15:30:00"
 
# Retry tomorrow at 2 PM
php artisan down --retry="tomorrow 14:00"
 
# Retry in 2 hours
php artisan down --retry="+2 hours"
 
# Unix timestamp
php artisan down --retry="@1735660200"

The datetime is converted to RFC 7231 format for the Retry-After header. A warning is displayed if a past datetime is provided, helping prevent configuration errors during maintenance windows.

Pull Request: #58509

#Expanded Enum Support

This release continues Laravel's enum integration by adding support in additional locations:

Session Methods: The now() and flash() session methods now accept enum values as keys, bringing them into consistency with other session methods.

Pull Request: #58459

Cache Methods: Cache::flexible() and Cache::withoutOverlapping() now accept enum keys, allowing for type-safe cache key management.

Pull Request: #58444

#Searchable db:table Prompt

The php artisan db:table command now uses a searchable prompt for table selection, making it easier to find tables in databases with many tables.

Pull Request: #58442

#Bug Fixes and Improvements

Bug Fixes:

• Fixed memory leak in Arr::dot() (#58458)
• Use multibyte-safe functions in Str::afterLast() (#58457)
• Clean up compiled views after parallel testing (#58440)
• Skip message serialization when log level not handled (#58475)
• Ignore deadlock on DatabaseLock release (#58507)
• Use assignment instead of mutation for immutable Carbon objects (#58498)

Improvements:

• Keep single NotificationSender instance for better performance (#58452)
• Make QueueFake::assertPushedTimes public (#58511)
• Enhanced index hint validation for multiple indexes (#58505)
• Added missing @param documentation to SessionGuard constructor (#58493)
• Bumped tar dependency from 7.5.3 to 7.5.6 (#58454)

Reverts:

• Reverted "aliasing when selecting database expressions" feature (#58469)

#Upgrade Notes

No breaking changes are expected for typical applications. Review the full changelog for complete details when upgrading.

#References

• Official Changelog
• Full Comparison