Laravel 12.44 : Callbacks HTTP afterResponse et nouvelles règles de validation Date

Laravel 12.44 enrichit le client HTTP avec la possibilité d’exécuter des callbacks après réception de la réponse. Cette version apporte également des méthodes expressives pour la validation des dates et une nouvelle assertion pour vos tests fonctionnels.

Contexte de cette release

Publiée le 23 décembre 2025, la version 12.44 de Laravel répond à un besoin récurrent des développeurs : inspecter et transformer les réponses HTTP sans alourdir le code métier. Jusqu’à présent, manipuler une réponse après réception nécessitait d’intervenir au niveau du handler Guzzle ou de créer des pipelines personnalisés.

Cette version introduit également des helpers temporels pour la validation des dates, une demande fréquente de la communauté.

La méthode afterResponse() du client HTTP

La nouvelle méthode afterResponse() permet d’attacher des callbacks qui s’exécutent une fois la réponse HTTP construite. Vous pouvez inspecter les headers, déclencher des événements, ou même transformer la réponse en un objet personnalisé.

<?php

use Illuminate\Support\Facades\Http;
use Illuminate\Http\Client\Response;

// Inspection d'un header après réception de la réponse
$response = Http::acceptJson()
    ->baseUrl('https://api.example.com')
    ->afterResponse(function (Response $response) {
        // Enregistrer un avertissement si l'API est dépréciée
        $deprecation = $response->header('X-Deprecation-Notice');
        if ($deprecation) {
            logger()->warning('API dépréciée : ' . $deprecation);
        }
    })
    ->get('/users');

Le callback reçoit l’objet Response complet, ce qui vous donne accès à toutes ses méthodes : header(), body(), json(), status(), etc.

Chaînage de plusieurs callbacks

Vous pouvez chaîner plusieurs appels à afterResponse(). Chaque callback peut retourner une nouvelle instance de réponse, qui sera passée au callback suivant.

<?php

use Illuminate\Support\Facades\Http;
use Illuminate\Http\Client\Response;
use App\Http\Responses\ApiResponse;

$response = Http::acceptJson()
    ->afterResponse(function (Response $response) {
        // Premier callback : logging
        if ($response->failed()) {
            report(new \Exception('Échec API : ' . $response->status()));
        }
        return $response;
    })
    ->afterResponse(function (Response $response) {
        // Second callback : transformation en réponse personnalisée
        return new ApiResponse($response->toPsrResponse());
    })
    ->post('https://api.example.com/orders', [
        'product_id' => 123,
        'quantity' => 2,
    ]);

Cette approche fluide s’intègre parfaitement avec les macros HTTP pour créer des clients API réutilisables.

Création d’un client API avec macro

Voici un exemple concret d’utilisation avec une macro pour un client Shopify :

<?php

use Illuminate\Support\Facades\Http;
use Illuminate\Http\Client\Response;
use App\Events\ShopifyDeprecationNotice;
use App\Http\Responses\ShopifyResponse;

// Définition de la macro dans un ServiceProvider
Http::macro('shopify', function (string $shop, string $token) {
    return Http::acceptJson()
        ->withHeader('X-Shopify-Access-Token', $token)
        ->baseUrl("https://{$shop}.myshopify.com/admin/api/2025-10/")
        ->afterResponse(function (Response $response) use ($shop) {
            // Signaler les dépréciations détectées
            $header = $response->header('X-Shopify-API-Deprecated-Reason');
            if ($header) {
                event(new ShopifyDeprecationNotice($shop, $header));
            }
        })
        ->afterResponse(fn (Response $r) => new ShopifyResponse($r->toPsrResponse()));
});

// Utilisation simplifiée
$products = Http::shopify('ma-boutique', $accessToken)
    ->get('products.json');

Nouvelles méthodes temporelles pour la règle Date

La règle de validation Date s’enrichit de quatre nouvelles méthodes pour valider les dates par rapport au moment présent :

<?php

use Illuminate\Validation\Rule;

$rules = [
    // La date doit être dans le passé (avant maintenant)
    'date_naissance' => Rule::date()->andTime()->past(),

    // La date doit être dans le futur (après maintenant)
    'date_evenement' => Rule::date()->andTime()->future(),

    // La date doit être maintenant ou dans le passé
    'date_debut' => Rule::date()->andTime()->nowOrPast(),

    // La date doit être maintenant ou dans le futur
    'date_fin' => Rule::date()->andTime()->nowOrFuture(),
];

Ces méthodes évitent d’avoir à écrire des règles before:now ou after:now manuellement. Le code devient plus lisible et l’intention est immédiatement claire.

Nouvelle assertion assertHeaderContains()

Pour les tests HTTP, Laravel 12.44 ajoute la méthode assertHeaderContains() à la classe TestResponse :

<?php

namespace Tests\Feature;

use Tests\TestCase;

class ApiTest extends TestCase
{
    public function test_response_contains_cache_header(): void
    {
        $response = $this->get('/api/products');

        // Vérifie que le header contient une valeur spécifique
        $response->assertHeaderContains('Cache-Control', 'max-age');
        $response->assertHeaderContains('Content-Type', 'json');
    }
}

Cette assertion vérifie que la valeur du header contient la chaîne spécifiée, sans exiger une correspondance exacte. Pratique pour les headers composites comme Cache-Control ou Content-Type.

Accès à la locale précédente

L’événement LocaleUpdated expose maintenant la propriété previousLocale :

<?php

use Illuminate\Foundation\Events\LocaleUpdated;
use Illuminate\Support\Facades\Event;

Event::listen(LocaleUpdated::class, function (LocaleUpdated $event) {
    logger()->info(sprintf(
        'Langue changée de %s vers %s',
        $event->previousLocale,
        $event->locale
    ));
});

Cette information facilite le tracking des changements de langue et les audits de localisation.

Autres améliorations notables

• Désactivation du prune lottery pour DatabaseLock : vous pouvez maintenant désactiver le nettoyage aléatoire des locks expirés via la méthode withoutPruneLottery()
• Événement MigrationSkipped : un nouvel événement est déclenché quand une migration est ignorée, utile pour le monitoring
• Correction du typage Query Builder : les méthodes retournent maintenant explicitement des instances de stdClass
• Fix Password::required() : correction d’un bug de validation avec les valeurs nullables

Mise à jour

Pour mettre à jour votre projet vers Laravel 12.44 :

composer update laravel/framework

Aucun breaking change n’est introduit dans cette version mineure.

Ressources

• GitHub Release v12.44.0
• Pull Request #58088 – afterResponse()
• Pull Request #58059 – Date now methods
• Pull Request #58200 – assertHeaderContains