Scheduler Attributes and Listener Discovery Control in Laravel 13.12.0

Laravel 13.12.0 adds the ability to attach metadata to scheduled events via a new withAttributes() 方法，一种 ShouldBeDiscovered interface that gives auto-discovered listeners control over their own registration, opt-out behavior for worker restarts on lost connections, SQLite file: URI support, and a handful of testing and string improvements.

• Custom attributes on scheduled events via withAttributes()
• ShouldBeDiscovered interface for conditional listener auto-discovery
• Opt out of queue worker restart on lost connection
• SQLite URI-based connections using the file: 前缀
• normalize 参数 Str::studly() 和 Str::pascal()
• Client\Request::uri() for HTTP client middleware
• assertJsonPathsCanonicalizing() 在 TestResponse
• 禁止 cache:clear 和 key:generate 命令
• Fix for scheduler lifecycle callback parameter resolution by type

# 什么是新的

# Custom Attributes on Scheduled Events

Scheduled events now support a withAttributes() method that lets you attach arbitrary key-value data directly to an event. These attributes are accessible inside lifecycle callbacks — useful for tagging events with metadata for monitoring, metrics, or logging without resorting to parsing the command string or description.

日程
::
后
（
功能
（
事件
$event) {
$标签
=
$事件
->
属性[
'tag'
]
？？

无效的
;

如果
($tag) {

指标
::
增量
（
$事件
->
退出代码
===

0

？

'scheduled.succeeded'

:

'scheduled.failed'
,

标签
：[
'命令'

=>
$tag]
（英文）：
}
}）
->
团体
（
功能
（
日程
$schedule) {
$时间表
->
命令
（
'audio:import-podcasts --only-premium'
）

->
不重叠
（）

->
带有属性
（[
'tag'

=>

'import-premium-podcasts'
]);
$时间表
->
命令
（
'audio:import-free'
）

->
不重叠
（）

->
带有属性
（[
'tag'

=>

'import-free-podcasts'
]);
});

公关稿： #60255 经过 @cosmastech

# Listener Discovery Opt-Out via ShouldBeDiscovered

新的 ShouldBeDiscovered interface lets auto-discovered listeners decide whether to register themselves. Implementing the interface and returning false from its static shouldBeDiscovered() method prevents the listener from being included during discovery, without needing to remove it from the listeners directory or move logic into the handle 方法。

This is particularly useful for listeners that implement ShouldQueue — skipping discovery at the class level means the job is never dispatched at all, rather than being queued and then deciding to do nothing in handle 。

使用

Illuminate\Contracts\Events\ShouldBeDiscovered
;
使用

照亮\合约\队列\应该队列
;
班级

NotifyExternalCrm

实现

ShouldBeDiscovered
,
应该排队
{

民众

静止的

功能

shouldBeDiscovered
（）
:

布尔值
{

返回

应用程序
（）
->
环境
（
'生产'
（英文）：
}

民众

功能

处理
（
CustomerRegistered
$event)
:

空白
{

Http
::
邮政
（
配置
（
'services.crm.webhook'
), [

'电子邮件'

=>
$事件
->
顾客
->
电子邮件，
]);
}
}

公关稿： #60209 经过 @jackbayliss

# Opt Out of Worker Restart on Lost Connection

Queue workers currently restart themselves whenever a database connection is lost. This can cause boot-looping when using multiple database connections (such as replicas) and one becomes temporarily unavailable. A new static property lets you disable this behavior:

使用

Illuminate\Queue\Worker
;
工人
::
$stopOnLostConnection
=

错误的
;

当设置为 false , the worker logs the lost connection and continues polling rather than exiting. This is opt-in and does not change the default behavior.

公关稿： #60201 经过 @jackbayliss

# SQLite URI-Based Connections

SQLite connections now accept the file: URI prefix format introduced in PHP 8.1 and PDO. This allows specifying SQLite options such as cache=shared 和 mode=ro directly in the connection string:

'默认'

=>
[

'司机'

=>

'sqlite'
,

'数据库'

=>

'file:/absolute/path/to/database.sqlite?cache=shared'
,
]，

公关稿： #60261 经过 @crynobone

# Str::studly() 和 Str::pascal() Normalization

两个都 Str::studly() 和 Str::pascal() now accept a normalize 参数。当 true , any all-uppercase word segment is lowercased before conversion, so strings like ALL_CAPS or acronyms produce the expected StudlyCase output:

力量
::
studly
（
'ALL_CAPS'
（英文）：
// → 'ALLCAPS'
力量
::
studly
（
'ALL_CAPS'
,
正常化
:
真的
（英文）：
// → 'AllCaps'
力量
::
studly
（
'CBOR'
,
正常化
:
真的
（英文）：
// → 'Cbor'
力量
::
studly
（
'AllJersey'
,
正常化
:
真的
（英文）：
// → 'AllJersey' (mixed-case unchanged)

The default is false , so existing behavior is preserved.

公关稿： #60229 经过 @热流星

# Client\Request::uri() for HTTP Client Middleware

HTTP client request objects now have a uri() method that returns the full UriInterface for the request. This is useful in middleware when you need the complete URI — including scheme, host, path, and query string — without manually reconstructing it:

Http
::
withRequestMiddleware
（
功能
（
请求接口
$request) {
$类型
=
$请求
->
类型
（）；
// returns a UriInterface

日志
::
信息
（
'Outgoing request'
，[
'url'

=>
（
细绳
) $uri]);

返回
$request;
}）
->
得到
（
'https://example.com/api/resource'
（英文）：

公关稿： #60282 经过 @史蒂夫鲍曼

# assertJsonPathsCanonicalizing() 在 TestResponse

新的 assertJsonPathsCanonicalizing() 方法 TestResponse asserts that a set of JSON paths contain the expected values, comparing them in a canonicalized (order-independent) way. This complements the existing assertJsonPath() 和 assertJsonPathCanonicalizing() for single paths.

公关稿： #60225 经过 @Tresor-Kasenda

# 禁止 cache:clear 和 key:generate 命令

两个都 cache:clear 和 key:generate Artisan commands can now be prohibited using Artisan::prohibit() . This is consistent with other prohibitable commands and useful in production environments where you want to prevent accidental key rotation or cache flushes:

// In AppServiceProvider::boot()
如果
（
$this
->
应用程序
->
是生产
（））{

\Illuminate\Console\Commands\KeyGenerateCommand
::
禁止
（）；
}

PR： #60215 , #60224 经过 @jackbayliss

# Scheduler Callback Parameter Resolution Fixed

A bug introduced in v13.10.0 caused scheduled event lifecycle callbacks to only inject the Event instance when the parameter was literally named $event . Parameters with any other name — such as $scheduledEvent 或者 $task — would cause a BindingResolutionException . The fix now resolves the parameter by type rather than by name, matching how the rest of the Laravel container works:

// Previously failed with BindingResolutionException
日程
::
命令
（
'inspire'
）

->
前
（
功能
（
事件
$scheduledEvent) {

日志
::
信息
（
"Starting {
$scheduledEvent
->
命令
}”
（英文）：
});

公关稿： #60197 经过 @kayw极客

# 其他修复和改进

• Fix path separator encoding in LocalFilesystemAdapter 和 temporaryUrl — path separators are no longer double-encoded for local disk operations ( #60194 , #60230 经过 @jackbayliss , @kayw极客 ）
• Fix async HTTP retries with array backoff values — passing an array of backoff intervals to async HTTP retry now works correctly ( #60214 经过 @LucasCavalheri ）
• JsonSchema fluent boolean flags can now be unset — calling a fluent boolean setter with false now removes the flag rather than setting it to false in the schema output ( #60239 经过 @LucasCavalheri ）
• Factory pivot stub — the generated stub for pivot models now includes a factory reference ( #60204 经过 @ludo237 ）
• Up/Down commands report exceptions — db:wipe / inspire and similar commands now surface exceptions through the registered exception handler ( #60232 经过 @jackbayliss ）
• ManagedQueueNotFoundException for missing managed queues — a dedicated exception is thrown when a managed queue cannot be found, improving error messages for Laravel Cloud queue setups ( #60275 经过 @kieranbrown ）

参考

• Official changelog
• Compare v13.11.2...v13.12.0