En bref : migrer le stockage objet avec Laravel sans couper le service

• Laravel 13 introduit un système de fichiers read-through qui associe un stockage principal à un stockage de secours.
• Les nouveaux fichiers sont écrits sur la destination ; les anciens restent lisibles depuis la source et peuvent être copiés lors de leur première lecture.
• La promotion à la demande ne transfère pas forcément les fichiers rarement consultés : une copie en arrière-plan reste nécessaire pour achever la migration.
• Les URL directes, les suppressions, les métadonnées et les clés modifiables demandent une attention particulière.

Changer de fournisseur de stockage ne consiste pas seulement à déplacer des fichiers : l’application doit continuer à les trouver pendant le transfert. C’est précisément le problème que vise à résoudre le nouveau système de fichiers read-through de Laravel 13. Il permet de faire cohabiter, derrière une même interface, une destination — par exemple Cloudflare R2 — et une source historique comme Amazon S3, sans imposer une synchronisation massive avant la bascule.

Le principe est simple à suivre : les écritures partent immédiatement vers le nouveau stockage objet, tandis qu’une lecture d’un ancien fichier peut encore le récupérer depuis l’origine et le promouvoir vers la destination. Pour une plateforme fictive de gestion de documents, cela signifie que les nouveaux dépôts sont enregistrés sur R2 dès le changement de configuration, alors que les pièces archivées demeurent accessibles sur S3. La migration des usages et le transfert de tous les objets peuvent ainsi avancer à des rythmes différents.

Cette approche s’appuie sur l’abstraction des disques de stockage déjà proposée par Laravel et Flysystem. Elle réduit le risque de coupure, mais ne remplace ni la supervision ni un plan de transfert complet : les URL publiques, les suppressions et les fichiers rarement consultés suivent des règles particulières. La présentation des nouveautés de Laravel 13 et de son filesystem read-through donne le contexte de cette évolution ; l’enjeu concret reste de préparer soigneusement chaque étape du basculement.

Un disque read-through pour relier deux stockages dans Laravel

Le pilote read-through présente deux stockages ordinaires comme un seul disque logique à l’application. Le disque principal reçoit les écritures ; le disque de secours n’est consulté que lorsque le fichier demandé est absent du principal. Les deux références peuvent désigner des disques déjà définis dans la configuration Laravel ou des configurations intégrées.

Dans l’exemple d’une migration de S3 vers R2, l’application pointe son disque par défaut sur cette composition. Un nouvel avatar est donc enregistré sur R2, tandis qu’une demande visant un ancien chemin peut encore aboutir sur S3. Le développeur continue d’utiliser l’API habituelle de Laravel plutôt que de disperser des conditions liées au fournisseur dans les contrôleurs.

Ce modèle n’est pas limité à un transfert entre deux services cloud : il peut associer un disque local à un stockage objet, ou relier d’autres fournisseurs compatibles avec les opérations nécessaires. Des disques avec préfixes permettent aussi de transférer des fichiers d’un répertoire logique à un autre, même si les deux préfixes résident dans le même compartiment. Pour mieux comprendre cette abstraction, le guide sur le stockage de fichiers et le cloud dans Laravel complète utilement la documentation du pilote.

Lecture, promotion et gestion des erreurs

Quand un fichier est absent du disque principal, Laravel le recherche sur le disque de secours. Si l’objet s’y trouve, le pilote peut le copier vers la destination au cours de la même requête : cette copie à la première lecture est appelée promotion. Les lectures suivantes utilisent alors la copie principale.

Avant de promouvoir l’objet, Laravel vérifie de nouveau le disque principal. Si une requête concurrente y a déjà écrit le fichier, il écarte le contenu de secours et lit la version principale. Cette précaution limite les doublons et la restitution d’une version ancienne, mais la vérification et l’écriture ne sont pas atomiques : des clés immuables ou versionnées sont plus sûres lorsque plusieurs requêtes peuvent modifier le même chemin.

Par défaut, la promotion est une opération de meilleure intention. Si la lecture depuis la source réussit mais que l’écriture vers la destination échoue, Laravel peut tout de même renvoyer le contenu récupéré ; le fichier pourra être promu lors d’une autre lecture. Le réglage throw_on_promotion_failure permet de rendre cet échec bloquant, mais l’option standard de propagation des erreurs du disque doit également être activée pour que le code applicatif reçoive l’exception.

Écritures, suppressions et URL : les comportements à anticiper

Le pilote ne traite pas toutes les opérations de la même façon. Les lectures de contenu tentent le disque principal puis le secours ; les écritures, créations de répertoires et changements de visibilité ciblent le principal. Les vérifications d’existence, de taille ou de type de fichier consultent les deux emplacements, tandis que les listes de répertoires ne reflètent que l’état de la destination.

Les opérations de copie et de déplacement cherchent d’abord la source sur le principal, puis sur le secours. Si elle n’existe que sur ce dernier, Laravel peut transférer son contenu vers la destination sans promouvoir son chemin d’origine. Un déplacement supprime aussi la source de secours après l’écriture réussie ; une copie, elle, la conserve.

Une suppression effectuée par le disque composite vise les deux stockages, en commençant par le secours. Cette règle évite qu’un ancien objet réapparaisse lors d’une lecture ultérieure, mais elle implique que les identifiants d’accès à la source disposent du droit de suppression. Si le compartiment historique doit rester immuable, il faut conserver les suppressions dans un registre applicatif — par exemple des tombstones — ou différer leur exécution jusqu’à la fin de la migration.

Les URL publiques et temporaires de téléchargement sont générées à partir du disque qui contient déjà l’objet ; produire une URL ne déclenche donc pas sa promotion. À l’inverse, une URL temporaire d’envoi est créée pour le disque principal, afin que les nouveaux téléversements arrivent directement à destination. Une application qui sert la plupart de ses fichiers par URL directe peut ainsi déplacer peu d’objets via ses lectures Laravel.

Flux volumineux, mise en cache et métadonnées

La méthode get() charge le fichier entier dans une chaîne PHP avant la promotion. Pour un gros objet, cela peut augmenter fortement la consommation mémoire ; readStream() évite de matérialiser l’ensemble du contenu sous cette forme et utilise un flux temporaire pour copier les données vers le disque principal.

Par défaut, le flux temporaire de PHP conserve jusqu’à environ 2 Mio en mémoire avant de basculer vers un fichier temporaire. Il faut donc prévoir assez d’espace disque temporaire et des délais de requête adaptés : lors de la première lecture, l’application attend le transfert depuis la source puis l’envoi vers la destination. Pour des fichiers très volumineux, une copie en arrière-plan peut être préférable.

La promotion transporte le chemin et le contenu selon le contrat générique de l’adaptateur de fichiers. Les réglages du disque principal s’appliquent à l’objet créé, mais les métadonnées propres à un fournisseur — en-têtes de cache, disposition du contenu, classe de stockage ou métadonnées personnalisées — ne sont pas automatiquement garanties. Une équipe qui sert des fichiers directement depuis le stockage doit vérifier ces paramètres avant de retirer la source : la mise en cache côté navigateur ou CDN dépend souvent de ces en-têtes.

Les comportements essentiels de l’API Storage et la configuration des disques sont également présentés dans ce guide de configuration des disques Laravel. L’idée à retenir est que la compatibilité des données ne se limite pas aux octets : les règles de livraison et les métadonnées font partie de la migration.

Réussir la migration vers Amazon S3, R2 ou un autre stockage objet

La promotion pilotée par le trafic déplace d’abord les objets les plus consultés. Elle ne garantit pas que chaque fichier de la source sera transféré : les objets rarement sollicités peuvent y rester indéfiniment. Une migration complète combine donc le disque read-through avec une copie en arrière-plan, qui doit préserver les fichiers déjà présents sur la destination.

Pour une plateforme qui bascule d’Amazon S3 vers R2, la première lecture d’un objet encore sur S3 implique une récupération à la source puis une écriture sur R2. Selon les tarifs applicables, le transfert sortant d’AWS peut représenter un coût ; R2 facture aussi ses opérations de lecture et d’écriture selon ses propres classes tarifaires. Le read-through étale le déplacement des objets actifs, mais ne supprime pas le coût associé au transfert du contenu.

Une procédure opérationnelle fiable peut suivre ces étapes :

• Configurer la destination comme disque principal et l’ancien stockage comme solution de secours, puis diriger les opérations de l’application vers le disque composite.
• Copier les objets restants en arrière-plan, en ignorant ceux déjà présents sur la destination afin de préserver les nouveaux envois et les mises à jour.
• Suivre les clés, les volumes, les reprises et les échecs, puis vérifier la destination avec des comparaisons de noms, de tailles et, lorsque c’est possible, de sommes de contrôle.
• Basculer directement sur le nouveau disque après la copie et une période d’observation, puis révoquer les accès à l’ancien stockage selon les règles de conservation.

Pour un compartiment contenant des millions d’objets, une énumération complète chargée en mémoire n’est pas adaptée : les traitements doivent s’appuyer sur des listes paginées ou un service de transfert dédié. La source n’étant pas supprimée par une promotion, elle peut rester disponible pour la vérification et le retour arrière jusqu’à sa mise hors service explicite.

Le pilote read-through convient quand la migration doit suivre le trafic de l’application ; d’autres outils répondent à des besoins différents. Cloudflare Sippy peut déclencher une copie au niveau du service R2, tandis que Super Slurper, rclone, MinIO mc mirror ou AWS DataSync sont des options pour transférer les objets en masse. Une combinaison est souvent efficace : promotion des fichiers actifs, puis copie planifiée du reliquat.

Les enjeux de déploiement dépassent le seul système de fichiers : la stratégie doit s’intégrer à l’architecture cloud, aux autorisations et au plan de retour arrière. Les retours d’expérience sur la migration d’une architecture hybride vers Laravel Cloud éclairent cette préparation ; pour le stockage objet, le point décisif reste de distinguer la bascule des écritures du transfert complet des données.