Laravel 12.48 : BatchFinished, flags JSON HTTP et améliorations des queues

Laravel 12.48.0, sorti le 20 janvier 2026, enrichit la gestion des batches de jobs avec un nouvel événement BatchFinished, améliore le décodage JSON du HTTP Client et offre plus de contrôle sur le middleware CORS.

Cette release apporte des fonctionnalités pratiques pour le monitoring des jobs en batch, la manipulation de grands nombres JSON et l’optimisation des tests parallèles.

Présentation de Laravel 12.48

Cette version se concentre sur quatre axes :

• Cycle de vie des batches : nouvel événement pour détecter la fin réussie d’un batch
• HTTP Client : contrôle fin du décodage JSON avec des flags personnalisés
• Middleware CORS : possibilité de contourner le middleware conditionnellement
• Tests parallèles : isolation des vues compilées par processus

La version 12.48.1, publiée quelques heures après, a retiré la fonctionnalité d’alias pour les expressions du Query Builder suite à un problème de compatibilité MySQL.

Le nouvel événement BatchFinished

Jusqu’à présent, Laravel ne proposait que l’événement BatchFailed pour détecter l’échec d’un batch. La v12.48 comble ce manque avec BatchFinished, déclenché quand tous les jobs d’un batch se terminent sans erreur.

<?php

use Illuminate\Bus\Events\BatchFinished;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\Facades\Log;

// Écouter la fin réussie d'un batch
Event::listen(function (BatchFinished $event) {
    $batch = $event->batch;

    // Journaliser la complétion
    Log::info("Batch {$batch->id} terminé avec succès");

    // Déclencher des actions de suivi
    dispatch(new NotifierAdministrateur($batch));
});

Cet événement s’avère particulièrement utile pour :

• Envoyer des notifications quand un traitement lourd se termine
• Lancer des tâches de nettoyage post-traitement
• Enregistrer des métriques de performance
• Chaîner automatiquement d’autres workflows

Cas d’usage concret : export de données

<?php

namespace App\Listeners;

use App\Jobs\EnvoyerRapportParEmail;
use Illuminate\Bus\Events\BatchFinished;

class GererFinExport
{
    public function handle(BatchFinished $event): void
    {
        $batch = $event->batch;

        // Récupérer les métadonnées du batch
        $metadata = $batch->options['metadata'] ?? [];

        if (isset($metadata['type']) && $metadata['type'] === 'export') {
            // L'export est terminé, envoyer le rapport
            dispatch(new EnvoyerRapportParEmail(
                destinataire: $metadata['user_email'],
                fichier: $metadata['output_path'],
                duree: now()->diffInSeconds($batch->createdAt)
            ));
        }
    }
}

Flags JSON pour le HTTP Client

Le HTTP Client accepte désormais des flags de décodage JSON, offrant un contrôle précis sur le parsing des réponses API.

<?php

use Illuminate\Support\Facades\Http;

$response = Http::get('https://api.exemple.com/donnees');

// Décoder les grands entiers en chaînes (évite la perte de précision)
$data = $response->json(flags: JSON_BIGINT_AS_STRING);

// Combiner plusieurs flags
$data = $response->json(
    flags: JSON_BIGINT_AS_STRING | JSON_THROW_ON_ERROR
);

Cette fonctionnalité résout un problème courant : les identifiants numériques dépassant PHP_INT_MAX (9223372036854775807) perdaient leur précision. Avec JSON_BIGINT_AS_STRING, ils restent intacts sous forme de chaînes.

Exemple pratique avec une API externe

<?php

namespace App\Services;

use Illuminate\Support\Facades\Http;

class ServicePaiement
{
    public function recupererTransaction(string $id): array
    {
        $response = Http::withToken($this->apiKey)
            ->get("https://api.paiement.com/transactions/{$id}");

        // Les IDs de transaction peuvent dépasser PHP_INT_MAX
        return $response->json(flags: JSON_BIGINT_AS_STRING);
    }

    public function traiterWebhook(string $payload): array
    {
        // Forcer une exception en cas de JSON invalide
        return json_decode(
            $payload, 
            associative: true, 
            flags: JSON_THROW_ON_ERROR
        );
    }
}

Méthode skipWhen pour le middleware CORS

Le middleware HandleCors gagne une méthode skipWhen() permettant de contourner conditionnellement la gestion CORS.

<?php

use Illuminate\Http\Middleware\HandleCors;

// Dans un service provider
HandleCors::skipWhen(function ($request) {
    // Ignorer CORS pour les appels internes
    return $request->is('internal-api/*');
});

// Version concise avec une arrow function
HandleCors::skipWhen(
    fn ($request) => $request->hasHeader('X-Internal-Request')
);

Cette méthode trouve son utilité pour :

• Les endpoints de health check appelés par l’infrastructure
• Les communications inter-services dans une architecture microservices
• Les routes internes qui n’ont pas besoin de CORS

Isolation des vues pour les tests parallèles

Les tests parallèles bénéficient maintenant d’une isolation des vues compilées par processus. Chaque worker de test dispose de son propre cache de vues Blade, éliminant les conflits de compilation.

Aucune configuration n’est requise. Cette amélioration s’active automatiquement lors de l’exécution de :

php artisan test --parallel

Les bénéfices sont immédiats :

• Plus de race conditions sur le cache de vues
• Tests parallèles plus stables
• Isolation complète entre les workers

Améliorations des événements de queue

Deux événements de queue reçoivent des informations supplémentaires :

<?php

use Illuminate\Queue\Events\JobPopping;
use Illuminate\Queue\Events\JobReleasedAfterException;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\Facades\Log;

// JobPopping inclut maintenant le nom de la queue
Event::listen(function (JobPopping $event) {
    Log::debug("Récupération d'un job depuis la queue : {$event->queue}");
});

// JobReleasedAfterException inclut le délai de backoff
Event::listen(function (JobReleasedAfterException $event) {
    Log::warning(
        "Job relâché après exception, backoff : {$event->backoff} secondes"
    );
});

Ces ajouts facilitent le monitoring et le debugging des queues en production.

Point d’attention : fonctionnalité retirée

La v12.48.0 introduisait des alias pour les expressions du Query Builder. Cette fonctionnalité a été retirée dans la v12.48.1 car elle provoquait un double aliasing avec MySQL dans certains cas.

Si vous avez mis à jour vers la 12.48.0, passez à la 12.48.1 pour éviter ce problème.

Mise à jour

Pour bénéficier de ces nouveautés :

composer update laravel/framework

Vérifiez que vous utilisez bien la version 12.48.1 (et non 12.48.0) pour éviter le bug des alias d’expressions.

Bonnes pratiques

• Utilisez BatchFinished plutôt que de poll le statut du batch
• Privilégiez JSON_BIGINT_AS_STRING pour les APIs retournant de grands identifiants
• Documentez les routes exclues de CORS avec skipWhen()
• Mettez à jour vers la 12.48.1 si vous êtes sur la 12.48.0

Conclusion

Laravel 12.48 apporte des améliorations ciblées mais bienvenues. L’événement BatchFinished comble un manque évident dans la gestion des batches, les flags JSON résolvent un problème réel avec les grands nombres, et skipWhen() offre plus de flexibilité pour CORS.

L’équipe Laravel a également montré sa réactivité en retirant rapidement une fonctionnalité problématique, préservant ainsi la stabilité du framework.

Ressources

• Release Notes v12.48.0 sur GitHub
• Release Notes v12.48.1 sur GitHub
• Article Laravel News
• PR BatchFinished #58431
• PR JSON flags #58379
• PR skipWhen CORS #58361