Redis Cluster Support for Queues in Laravel 13.5.0

Laravel v13.5.0 adds first-class Redis Cluster support for the queue driver and concurrency limiter, fixing CROSSSLOT errors on AWS ElastiCache Serverless and other Redis Cluster deployments. It also completes #[Delay] attribute coverage for queued mailables, adds Controller Middleware attribute inheritance, expands enum support across manager classes, and includes a number of bug fixes.

• First-class Redis Cluster support for Queue and ConcurrencyLimiter
• #[Delay] attribute now works on queued mailables
• Controller Middleware attributes are inherited by child controllers
• Enum support expanded across Cache, Mail, Auth, and other manager drivers
• Closure values accepted in updateOrCreate 和 firstOrNew
• 新的 Cache::handleUnserializableClassUsing() hook for detecting broken cache values
• 修复 ShouldBeUniqueUntilProcessing jobs releasing locks they don't own

# 什么是新的

# First-Class Redis Cluster Support for Queue and ConcurrencyLimiter

When using AWS ElastiCache Serverless (Valkey) or any Redis Cluster deployment, Laravel's Redis queue and ConcurrencyLimiter previously failed with CROSSSLOT errors. The queue's Lua scripts operate across multiple keys — queues:default , queues:default:reserved ， 和 queues:default:notify — that hash to different cluster slots, which Redis Cluster prohibits in a single command.

Laravel now automatically wraps queue names in Redis hash tags when the connection is a cluster, ensuring all related keys hash to the same slot:

queues:{default}           → slot for "default"
queues:{default}:delayed   → slot for "default"
queues:{default}:reserved  → slot for "default"
queues:{default}:notify    → slot for "default"

Different queues ( {emails} , {notifications} ) still distribute across the cluster naturally. The public getQueue() method is unchanged, so existing integrations that consume queue names continue to see the same format as before, while Redis operations themselves use cluster-safe keys. Non-cluster users are unaffected.

这 ConcurrencyLimiter receives the same treatment — slot keys are now wrapped in hash tags on cluster connections, so the mget Lua script no longer crosses slots.

On phpredis 5.3.2 and newer, the PhpRedis cluster connector also gains ACL auth support and max_retries , backoff_algorithm , backoff_base ， 和 backoff_cap options to improve compatibility with ElastiCache Serverless scaling behavior.

拉取请求： #59533 经过 @timmylindh

# #[Delay] Attribute Support on Queued Mailables

这 #[Delay] attribute support added across queued event listeners, jobs, and notifications in v13.4.0 now applies to queued mailables too. Previously, mailables only checked the $delay property and ignored the attribute entirely.

使用

Illuminate\Queue\Attributes\Delay
;
#[
Delay
（
30
）]
班级

WelcomeEmail

延伸

可邮寄

实现

应该排队
{

// Now correctly delayed by 30 seconds when queued
}

这 $delay property still takes precedence when explicitly set, matching the behavior of the other dispatchers.

拉取请求： #59580 经过 @sumaiazaman

# Controller Middleware Attribute Inheritance

这 #[Middleware] attribute on a base controller is now inherited by child controllers. Previously, child controllers ignored middleware attributes defined on their parent, requiring duplication across each class.

使用

Illuminate\Routing\Attributes\Middleware
;
#[
中间件
（
‘授权’
）]
#[
中间件
（
'log:api'
）]
抽象的

班级

AdminBaseController

延伸

控制器
{

// Common admin logic
}
班级

AdminController

延伸

AdminBaseController
{

民众

功能

指数
（）
{

// Inherits 'auth' and 'log:api' middleware from the parent
}
}

Attributes are collected in parent-to-child order, consistent with how PHP resolves class hierarchies.

拉取请求： #59597 经过 @niduranga

# Enum Support Expanded Across Manager Classes

Enum support has been added to several manager classes that were previously missing it:

缓存管理器 — store() , driver() , memo() , forgetDriver() , purge() ， 和 setDefaultDriver() now accept a UnitEnum :

枚举

CacheStore
:
细绳
{

案件

雷迪斯

=

'redis'
;

案件

大批

=

'大批'
;
}
缓存
::
店铺
（
CacheStore
::
雷迪斯
）
->
放
（
'钥匙'
,
'价值'
（英文）：

MailManager — mailer() , driver() ， 和 purge() now accept enums.

AuthManager — guard() , shouldUse() ， 和 setDefaultDriver() now accept enums.

Laravel also added enum support to the base Manager::driver() method, extending the same pattern to other manager classes that inherit from it.

This continues the enum-support wave that already covered QueueManager , LogManager , DatabaseManager , FilesystemManager , RedisManager ， 和 BroadcastManager 。

拉取请求： #59637 , #59645 , #59646 , #59659 经过 @yousefkadah 和 @scabarcas17

# Closure Values in updateOrCreate 和 firstOrNew

updateOrCreate 和 firstOrNew now accept a Closure 为了 $values argument, completing the lazy-evaluation pattern introduced in v13.x for firstOrCreate 和 createOrFirst . This allows you to defer expensive operations — like geocoding or API calls — until you know the record actually needs to be created or updated:

位置
=

地点
::
更新或创建
（
[
'地址'

=>
$address]，

fn
() => [
坐标

=>

地理编码器
::
解决
($address)],
（英文）：

The closure is called exactly once per method call. On firstOrNew , the closure is never invoked when the record already exists.

拉取请求： #59647 经过 @yousefkadah

# Detect Unserializable Cache Values

新的 Cache::handleUnserializableClassUsing() hook lets you register a callback that runs when a cache value deserializes to __PHP_Incomplete_Class — which can happen when the serializable_classes config is in use and a class is missing from the allow-list.

缓存
::
handleUnserializableClassUsing
（
功能
（
细绳
$key，
？细绳
$class)
:

空白
{

如果
（
应用程序
（）
->
是生产
（））{

日志
::
警告
（
"Cache hit [{
$键
}] returned unserializable class [{
$class
}]"
（英文）：

返回
;
}

扔

新的

运行时异常
（
"Cache hit [{
$键
}] returned unserializable class [{
$class
}]"
（英文）：
});

No handler is registered by default, so this is purely opt-in with no behavior changes for existing applications.

拉取请求： #59630 经过 @jackbayliss

# 其他修复和改进

Queue:

• 固定的 ShouldBeUniqueUntilProcessing job retries releasing locks they don't own ( #59567 经过 @kohlerdominik ）

Redis:

• Normalized phpredis SSL context options for single and cluster connections ( #59569 经过 @timmylindh ）

授权：

• 固定的 redirectUsersTo() overwriting the redirectGuestsTo() callback ( #59633 经过 @timmylindh ）
• Fixed a loose comparison false positive in NotPwnedVerifier with magic hash passwords ( #59644 经过 @scabarcas17 ）

测试：

• Memoized the result of TestCase::withoutBootingFramework() to avoid redundant work ( #59610 经过 @cosmastech ）

其他：

• Fixed a custom driver binding bug in Manager classes ( #59614 经过 @ollieread ）
• 额外 spatie/fork to Composer suggestions for concurrency support ( #59660 经过 @jnoordsij ）
• Moved the Scope 界面 @template from method-level to class-level to fix an LSP violation ( #59675 经过 @kayw极客 ）

参考

• 官方更新日志
• GitHub 发布
• 全面比较