Route Metadata Support in Laravel 13.17

The Laravel team released v13.17.0 with first-class route metadata support, Postgres transaction pooler integration, a new dev:list artisan command, and a Should Not Retry exception handler for queue jobs.

• Route metadata support with dot notation and group cascading
• Postgres transaction pooler support (PgBouncer, RDS Proxy, Neon)
• New dev:list command to list registered dev processes
• Should Not Retry exception handler for queue jobs
• between()/unlessBetween() timezone call-order fix
• --without-migration-data flag for schema:dump
• Reduced cache hits when debouncing with maxWait

#What's New

#Route Metadata Support

Routes can now carry structured metadata through the full route-building pipeline, including route:cache serialization and group inheritance. Previously, developers could stash custom data inside the route action array, but there was no supported path for attaching structured data consistently across the pipeline. This release promotes metadata to a first-class attribute on routes.

Add metadata directly to a route using the metadata() method:

Route::get('/users', [UserController::class, 'index'])
    ->metadata(['head' => ['title' => 'Users']]);

Read it back from the resolved route using getMetadata(), which supports dot notation and an optional default:

$request->route()->getMetadata('head.title');          // 'Users'
$request->route()->getMetadata('head.author', 'Taylor');

Metadata set on a group cascades to every route inside it. Associative arrays merge recursively, so nested groups can layer values while lists and scalar values replace inherited ones:

Route::metadata(['head' => ['robots' => ['noindex'], 'author' => 'Taylor']])
    ->group(function () {
        Route::get('/users', [UserController::class, 'index'])
            ->metadata(['head' => ['title' => 'Users']]);
    });
 
// getMetadata('head') => [
//     'robots'  => ['noindex'],
//     'author'  => 'Taylor',
//     'title'   => 'Users',
// ]

Resource and singleton routes are supported too. Use setMetadata() on a route instance to replace rather than merge metadata. See #60530.

#Postgres Transaction Pooler Support

This release adds framework-level support for PostgreSQL connection proxies that use transaction-mode pooling, including PgBouncer, AWS RDS Proxy, and Neon. In transaction-mode pooling, a server connection is only held for the duration of a single transaction, which makes prepared statements incompatible with the pooler. Laravel now handles this automatically.

Enable pooled mode in your database.php config:

'pgsql' => [
    'driver'  => 'pgsql',
    'pooled'  => true,
    'url'     => env('DATABASE_URL'),
    // Optional: a direct (non-pooled) endpoint for DDL and migrations
    'direct'  => env('DATABASE_DIRECT_URL'),
    // ...
],

When pooled is true, the connection switches to emulated prepares, which are compatible with transaction-mode poolers. Commands that require a direct connection (migrations, schema:dump, db:wipe) route to the direct endpoint automatically. The php artisan db interactive command also defaults to the direct endpoint when one is configured.

Connections without pooled => true keep the existing native-prepare behavior, so the change is fully backward compatible. See #60425.

#dev:list Command

A new php artisan dev:list command lists all registered dev processes alongside the source that registered each one (your application or a vendor package). This builds on the artisan dev command added in 13.16.0.

php artisan dev:list
php artisan dev:list --except-vendor   # hide vendor-registered commands
php artisan dev:list --only-vendor     # show only vendor-registered commands
php artisan dev:list --filter=reverb   # filter by name
php artisan dev:list --json

This release also replaces the vendor auto-registration blocker from 13.16.0 with source tracking. Each dev command now knows whether it was registered from your application or from a vendor package, which dev:list uses to distinguish them in the output. See #60573.

#Should Not Retry Exception Handler

Queued jobs can now determine at the exception level whether a failure should be retried. The retry() method can live on the exception class itself:

class PaymentGatewayException extends RuntimeException
{
    public function retry(): bool
    {
        return false; // never retry this exception
    }
}

The same method can be registered through the withExceptions() handler in your application bootstrap for exceptions you do not own:

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->retry(PaymentGatewayException::class, function () {
        return false;
    });
})

When retry() returns false, the job is marked as failed immediately without consuming remaining attempts. See #60552.

#between()/unlessBetween() Timezone Call-Order Fix

The between() and unlessBetween() scheduler methods previously evaluated the timezone at definition time, so placing timezone() after them in the chain would silently use the wrong timezone:

// before: only this order worked correctly
$schedule->command('report')->timezone('Europe/Rome')->between('10:00', '12:00');
 
// before: this used UTC instead of Europe/Rome, silently
$schedule->command('report')->between('10:00', '12:00')->timezone('Europe/Rome');

Both chains now produce the same result. The timezone is read when the filter runs rather than when it is defined. See #60518.

#--without-migration-data Flag for schema:dump

The schema:dump command accepts a new --without-migration-data flag that omits the migration table rows from the output. This is useful when you want a clean schema dump for test setup without tracking which migrations have run:

php artisan schema:dump --without-migration-data

See #60570.

#Other Fixes and Improvements

• Reduced cache reads when debouncing jobs with maxWait, cutting reads from two per dispatch to one (#60559)
• Fixed FileStore cache deserialization for entries with short timestamps (#60543)
• Fixed DevCommands vendor registration check to skip userland frames correctly (#60538)
• Cleared transaction manager state on database disconnect (#60574)
• Allowed brick/math 0.18 (#60560)
• Improved typehints across InteractsWithData, boolean/numeric validation, and array shapes (#60536, #60549, #60553)

References

• Official changelog
• Release v13.17.0