Query Builder Expression Aliases in Laravel 12.48

Release Date: January 20, 2026
Laravel Version: 12.48.0

Summary

Laravel v12.48.0 introduces query builder expression aliases, new batch lifecycle events, enhanced JSON decoding options for HTTP responses, and a BatchFinished event. The release includes several type safety improvements, support for isolated view compilation during parallel testing, and a skipWhen method for the CORS middleware.

Key highlights include:

• Query builder aliases for raw expressions
• New BatchFinished event for batch lifecycle management
• JSON decoding flags support in HTTP Client responses
• skipWhen() functionality for HandleCors middleware
• Translation strings may now contain square brackets and curly braces
• Type improvements across HTTP, Queue, and Collection components
• Isolated compiled views per process during parallel testing
• Enhanced performance with native class instantiation

#What's New

#Query Builder Expression Aliases

Laravel 12.48.0 adds convenient helper methods for aliasing raw database expressions directly on query builders, making raw SQL more readable and maintainable.

// Before: select available_a - used_a from "users"
// v12.48.0: select (available_a - used_a) as "remaining_a" from "users"
User::select([
    'remaining_a' => new Expression('available_a - used_a'),
]);

Pull Request: #58436

#BatchFinished Event

This release introduces a new BatchFinished event that fires when a batch completes successfully (all jobs finished without failure). This complements the existing BatchFailed event and provides more granular control over batch lifecycle management.

use Illuminate\Bus\Events\BatchFinished;
 
Event::listen(function (BatchFinished $event) {
    $batch = $event->batch;
 
    // Perform cleanup or post-processing
    Log::info("Batch {$batch->id} completed successfully");
 
    // Trigger follow-up actions
    dispatch(new NotifyAdminOfCompletion($batch));
});

This is useful for:

• Triggering notifications when batch processing completes
• Running cleanup tasks after successful batch execution
• Recording metrics or analytics
• Chaining additional workflows

Pull Request: #58431

#JSON Decoding Flags for HTTP Client

The HTTP Client's Response class now accepts custom JSON decoding flags, giving you more control over how JSON responses are parsed.

$response = Http::get('https://api.example.com/data');
 
// Decode with custom flags
$data = $response->json(flags: JSON_BIGINT_AS_STRING);
 
// Combine multiple flags
$data = $response->json(
    flags: JSON_BIGINT_AS_STRING | JSON_THROW_ON_ERROR
);

This is particularly useful when:

• Handling large integers that exceed PHP's native integer limits
• Working with APIs that return numeric strings
• Enforcing strict JSON parsing with error handling

Pull Request: #58379

#HandleCors Middleware Skip Functionality

The HandleCors middleware now supports conditional execution through a new skipWhen() method, allowing you to bypass CORS handling for specific routes or conditions.

use Illuminate\Http\Middleware\HandleCors;
 
// In a service provider or middleware configuration
HandleCors::skipWhen(function ($request) {
    // Skip CORS for internal API calls
    return $request->is('internal-api/*');
});
 
// Or use a simpler condition
HandleCors::skipWhen(fn ($request) => $request->hasHeader('X-Internal-Request'));

This provides flexibility when you have routes that shouldn't be subject to CORS policies, such as internal endpoints or health checks.

Pull Request: #58361

#Translation Strings with Brackets and Braces

Translation lines may now contain square brackets ([]) and curly braces ({}), expanding the characters allowed in translation keys and values without breaking Laravel's translation system.

// translations/en/messages.php
return [
    'code_example' => 'Use the format: {user[name]}',
    'array_syntax' => 'Access with: $data[index]',
];

This change removes restrictions on translation content, making it easier to include code snippets, JSON examples, or technical documentation in your translations.

Pull Request: #58367

#Isolated View Compilation for Parallel Testing

When running tests in parallel, compiled Blade views are now isolated per process, preventing race conditions and cache conflicts between parallel test processes.

This improvement ensures that:

• Parallel tests don't interfere with each other's view cache
• View compilation is thread-safe across test workers
• Test isolation is maintained at the view layer

No configuration changes are needed—this works automatically when using Laravel's parallel testing features.

Pull Request: #58390

#Queue Event Enhancements

This release adds additional properties to queue events, providing more context for monitoring and debugging:

• JobPopping event now includes the queue name
• JobReleasedAfterException event includes the backoff duration

use Illuminate\Queue\Events\JobPopping;
use Illuminate\Queue\Events\JobReleasedAfterException;
 
Event::listen(function (JobPopping $event) {
    Log::debug("Popping job from queue: {$event->queue}");
});
 
Event::listen(function (JobReleasedAfterException $event) {
    Log::info("Job released with backoff: {$event->backoff} seconds");
});

Pull Requests:

• #58413 (JobPopping queue property)
• #58414 (JobReleasedAfterException backoff)

#Type Safety Improvements

Laravel 12.48.0 includes numerous type improvements for better IDE support and static analysis:

• Enhanced PendingRequest type hints for better autocomplete
• Fixed return type docblock for Number::abbreviate()
• Annotated tuple return type for Number::pairs()
• Improved collection merge() return types
• Widened PendingRequest::pool() return type to support promises

These changes improve the developer experience when using static analysis tools like PHPStan or Psalm.

Pull Requests:

• #58386, #58395, #58437 (PendingRequest types)
• #58408 (Number::abbreviate)
• #58409 (Number::pairs)
• #58405 (Collection merge)

#Additional Improvements

Performance Enhancements:

• Use new $class instead of reflection for better performance in class instantiation (#58391)

Bug Fixes:

• Fixed missing variable reassignment (#58376)
• Fixed backward compatibility with third-party guards (#58385, #58389)
• Fixed TypeError when validation rule has empty parameters (#58380)
• Fixed restoreLock for MemoizedStore (#58423)
• Fixed missing import statements (#58394, #58401)

Testing & Quality:

• Adjusted PendingBatchFake to support filtering (#58375)
• Resolved infinite loop when using deferred queue (#58373)
• Added type tests for Illuminate\Support\Str (#58365)

Other Changes:

• Case-insensitive header assertions in TestResponse (#58383)
• Bus::chain now filters out falsy items (#58369)
• Dropped indexes from failed_jobs table (#58362)
• Made PruneCommand::isPrunable() protected (#58430)
• Implemented Stringable in Enum rule (#58392)
• Bumped tar dependency from 7.4.3 to 7.5.3 (#58404)

#Upgrade Notes

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

When using third-party authentication guards, test your authentication flows to ensure compatibility with the guard-related fixes in this release.

#References

• Official Changelog
• Laravel 12.x Documentation