Laravel 12.45 : JsonApiResource, AsBinary et support des enums pour le cache et les sessions

Laravel 12.45 marque une étape significative pour les développeurs d’APIs avec l’arrivée de JsonApiResource. Cette version améliore aussi l’expérience développeur avec le support des enums pour les clés de session et de cache, un nouveau cast binaire, et des outils de sécurité renforcés.

Présentation de Laravel 12.45

Pubilée le 6 janvier 2026, la version 12.45 de Laravel introduit plusieurs fonctionnalités attendues par la communauté. L’équipe Laravel a mergé plus de 45 pull requests pour cette release, avec des contributions de 27 développeurs différents.

Cette version cible particulièrement les développeurs construisant des APIs conformes au standard JSON:API, tout en apportant des améliorations de qualité de vie pour le travail quotidien avec les sessions, le cache et les modèles Eloquent.

JSON:API Resource : le standard enfin natif

La fonctionnalité phare de cette version est sans doute JsonApiResource. Contribuée par Mior Muhammad Zaki, elle permet de formater vos ressources API selon la spécification JSON:API directement depuis Laravel.

Création d’une ressource JSON:API

Vous pouvez créer une ressource JSON:API avec la commande artisan :

# Génération d'une ressource JSON:API
php artisan make:resource PostResource --json-api

Utilisation de JsonApiResource

<?php

namespace App\Http\Resources;

use Illuminate\Http\Resources\JsonApi\JsonApiResource;

// La classe étend JsonApiResource au lieu de JsonResource
class PostResource extends JsonApiResource
{
    // La structure JSON:API est générée automatiquement
}

La sortie respecte automatiquement la spécification JSON:API avec les attributs type, id, attributes et relationships correctement formatés.

Cast AsBinary : gestion native des données binaires

Kacper Pruszyński a contribué un nouveau cast AsBinary qui facilite le stockage et la manipulation des données binaires dans vos modèles Eloquent. Ce cast est particulièrement utile pour les UUID et ULID stockés en binaire dans la base de données.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Casts\AsBinary;

class Order extends Model
{
    // Définition des casts pour les colonnes binaires
    protected function casts(): array
    {
        return [
            // UUID obligatoire stocké en binaire
            'id' => AsBinary::uuid(isRequired: true),
            // ULID optionnel
            'public_id' => AsBinary::ulid(),
            // Cast binaire personnalisé
            'checksum' => AsBinary::of('md5', false),
        ];
    }
}

Les valeurs sont automatiquement converties en chaînes lisibles en PHP et stockées efficacement en binaire dans la base.

Support Enum pour sessions et cache

Deux contributions majeures améliorent l’ergonomie du travail avec les enums PHP 8.1+. Andy Hinkle et Jack Bayliss ont ajouté le support des Enum pour les clés de session et de cache.

Enums pour les clés de session

<?php

namespace App\Enums;

// Définition d'un enum pour les clés de session
enum CheckoutSession: string
{
    case Cart = 'checkout.cart';
    case ShippingAddress = 'checkout.shipping_address';
    case PaymentMethod = 'checkout.payment_method';
}

// Utilisation dans un contrôleur
class CheckoutController extends Controller
{
    public function store(Request $request)
    {
        // Avant : passage de la valeur de l'enum
        session()->put(CheckoutSession::Cart->value, $request->items);

        // Après (>= 12.45) : passage direct de l'enum
        session()->put(CheckoutSession::Cart, $request->items);

        return redirect()->route('checkout.shipping');
    }
}

Enums pour les clés de cache

<?php

namespace App\Enums;

enum AnalyticsCache: string
{
    case DailyVisitors = 'analytics.daily_visitors';
    case TopPages = 'analytics.top_pages';
    case ConversionRate = 'analytics.conversion_rate';
}

// Utilisation simplifiée avec le cache
class AnalyticsService
{
    public function getDailyVisitors(): int
    {
        // L'enum est passé directement comme clé
        return Cache::remember(AnalyticsCache::DailyVisitors, 3600, function () {
            return $this->calculateDailyVisitors();
        });
    }
}

Cette approche rend le code plus maintenable et évite les erreurs de frappe sur les clés.

Attachements depuis le cloud storage

Philo Hermans a simplifié l’ajout de pièces jointes stockées sur le cloud dans vos emails avec la méthode fromCloudStorage().

<?php

namespace App\Mail;

use Illuminate\Mail\Mailable;
use Illuminate\Mail\Attachment;

class InvoiceMail extends Mailable
{
    public function __construct(
        private string $invoicePath
    ) {}

    public function attachments(): array
    {
        // Avant : syntaxe verbeuse
        return [
                    Attachment::fromStorageDisk(Storage::getDefaultCloudDriver(), $this->invoicePath)
              ];

        // Après : syntaxe simplifiée
        return [
            Attachment::fromCloudStorage($this->invoicePath),
        ];
    }
}

Méthode markEmailAsUnverified()

Ali Khosrojerdi a ajouté la méthode markEmailAsUnverified() pour compléter markEmailAsVerified(). Cette méthode est utile pour réinitialiser la vérification d’email après un changement d’adresse.

<?php

class UserController extends Controller
{
    public function updateEmail(Request $request)
    {
        $user = $request->user();

        // Mise à jour de l'email
        $user->email = $request->validated('email');
        $user->save();

        // Réinitialisation de la vérification
        $user->markEmailAsUnverified();

        // Envoi d'un nouveau lien de vérification
        $user->sendEmailVerificationNotification();

        return back()->with('status', 'email-updated');
    }
}

Option –readable pour env:encrypt

Mathias Grimm a ajouté un flag --readable à la commande env:encrypt. Cette option garde les noms de variables visibles tout en chiffrant leurs valeurs, facilitant ainsi la revue de code.

# Chiffrement avec noms de variables visibles
php artisan env:encrypt --readable

Le fichier .env.encrypted résultant montre les clés en clair, permettant de voir quelles variables ont été ajoutées ou modifiées dans une pull request.

Points d’attention et bonnes pratiques

• JsonApiResource nécessite une réflexion sur la structure de vos API existantes avant migration
• AsBinary améliore les performances pour les UUID stockés en binaire mais requiert une migration de vos colonnes existantes
• Le support des enums pour cache et session est rétrocompatible : vos chaînes actuelles continuent de fonctionner
• L’option --readable de env:encrypt ne doit pas être utilisée si les noms de variables sont eux-mêmes sensibles
• La sécurité du cookie remember a été renforcée avec un MAC au lieu du hash brut du mot de passe

Autres améliorations notables

Cette version inclut également :

• Événements QueuePaused et QueueResumed pour un meilleur monitoring des queues
• Correction du timeout queue:listen après mise en veille système
• Ajout de détails de connexion dans les messages QueryException
• Support des sous-requêtes dans les clauses whereBetween
• Capture du type de requête PDO (lecture/écriture) dans les événements de query

Mise à jour vers Laravel 12.45

Pour mettre à jour votre projet :

composer update laravel/framework

Cette version ne contient pas de breaking changes. La mise à jour depuis n’importe quelle version 12.x devrait être transparente.

Ressources

• Release Notes v12.45.0 sur GitHub
• Diff complet v12.44.0…v12.45.0
• Pull Request JsonApiResource #57571
• Pull Request AsBinary #58254