Passer de la version 1.x à la version 2.x
Suivez ces étapes pour passer une application existante de Laravel Feeds 1.x à 2.x. Si votre version installée de 1.x inclut déjà les slugs des flux ou les nouveaux titres générés, conservez ces modifications et ignorez les étapes déjà effectuées.
Exigences d’exécution
| Composant | 1.x | 2.x |
|---|---|---|
| PHP | ^8.2 | ^8.4 |
| Composants Laravel | ^11.0 || ^12.0 || ^13.0 | ^13.0 |
Avant d’installer 2.x, mettez à jour les dépendances Laravel de l’application et les environnements PHP utilisés par l’application web, la CLI, le planificateur et les workers de file d’attente. Les applications utilisant PHP 8.2 ou 8.3, ou Laravel 11.x ou 12.x, doivent rester sur 1.x. Consultez la compatibilité pour connaître l’environnement pris en charge.
Avant la mise à niveau
- Sauvegardez le code actuel de l’application,
composer.json,composer.locket le fichierconfig/feeds.phppublié. Sauvegardez la table d’enregistrement des flux et les fichiers générés nécessaires à un retour en arrière. - Notez les identifiants des enregistrements, les titres, les slugs existants, les planifications et les destinations des sorties.
- Recherchez les appels à
feed:generatedans les scripts de déploiement, les tâches cron, les planifications manuelles, les tests et le code de l’application. - Générez des flux représentatifs et conservez leurs sorties pour les comparer.
- Pendant le déploiement, suspendez les planifications des flux et laissez se terminer les tâches de flux en cours ou en file d’attente avant de remplacer le paquet et de modifier le schéma.
Appliquer la mise à jour
composer require dragon-code/laravel-feeds:^2.0 --with-all-dependencies
composer check-platform-reqs
Comparez le fichier config/feeds.php du paquet installé à la copie publiée dans l’application et conservez les paramètres propres à l’application. Ne republiez pas avec --force : cela écrase cette copie.
Ajouter les slugs des flux
La PR #287 remplace la sélection d’un flux par son identifiant en base de données par une sélection par slug, dérivé avec Str::slug(title).
Si la migration des slugs du paquet n’a pas encore été exécutée, publiez les migrations :
php artisan vendor:publish --tag=feeds-migrations
La commande publie tous les fichiers de migration. Validez les fichiers publiés et supprimez ceux qui sont inutiles.
Définissez l’horodatage du nom de fichier de la nouvelle migration add_slug_to_feeds_table après celui de la migration create_feeds_table réellement présente dans l’application et avant toute migration d’enregistrement de flux. Cet ordre garantit que migrate:fresh ajoute la colonne slug avant que les enregistrements y écrivent. Exécutez ensuite les migrations :
php artisan migrate
La migration ajoute une colonne slug qui accepte les valeurs NULL et la remplit à partir des titres existants, y compris ceux des enregistrements supprimés temporairement. Les titres et identifiants existants sont conservés.
Si l’application possède déjà sa propre colonne slug et que la migration du paquet n’a pas été exécutée, la migration échoue avant de remplir les données. Résolvez ce conflit de schéma avant le déploiement ; ne supprimez pas une colonne propre à l’application sans conserver ses données et mettre à jour le code qui l’utilise.
Examinez les valeurs enregistrées dans php artisan tinker :
app(\DragonCode\LaravelFeed\Queries\FeedQuery::class)
->all()
->get(['id', 'title', 'slug']);
Les slugs utilisés pour la sélection doivent être non vides et distincts parmi les enregistrements non supprimés, y compris les inactifs. Des titres différents peuvent produire le même slug après normalisation. Les recherches ambiguës lèvent MultipleRecordsFoundException ; les slugs inconnus lèvent FeedNotFoundException. Résolvez les collisions ou les slugs vides en modifiant les titres via le modèle de flux.
Dans 2.3.0, la PR #334 remplace la redéfinition de fireModelEvent() par FeedObserver::saving(). Auparavant, le slug utilisait les attributs bruts après saving, creating et updating, y compris lors des enregistrements silencieux. Il utilise maintenant le titre exposé par l’accesseur au moment de l’observateur saving ; les enregistrements silencieux l’ignorent et les écouteurs tardifs ne déclenchent aucun nouveau calcul.
La PR #335 ajoute une vérification de $feed->isDirty('slug') : un slug explicitement modifié est normalisé avec Str::slug() et conservé pour l’enregistrement en cours, même si title change aussi. FeedQuery::create() l’accepte via extra: ['slug' => 'Custom Catalog']. Un slug inchangé reste dérivé de title ; un enregistrement normal ultérieur peut donc remplacer un slug personnalisé fourni auparavant. Affecter une valeur dont la normalisation donne le slug actuel n’empêche pas le recalcul.
Lors d’une mise à niveau depuis une version 1.x ou 2.x antérieure, vérifiez les affectations explicites de slug, les enregistrements silencieux, les accesseurs de titre, les écouteurs, les sélections partielles, les casts personnalisés et les écritures en masse. Testez le titre et le slug stockés, un enregistrement normal ultérieur, la recherche par slug et la génération planifiée. L’installation de la mise à jour seule ne modifie pas les lignes ; le prochain enregistrement normal peut toutefois changer un slug personnalisé ou dérivé d’un accesseur, même sans changement de titre. Adaptez les slugs des commandes et planifications si nécessaire. Consultez Eloquent pour la gestion explicite des slugs, des enregistrements silencieux et des écouteurs.
Remplacer les identifiants dans les appels de génération
Pour l’enregistrement d’identifiant 42 dont le titre stocké est Products, le slug après migration est products.
Avant :
php artisan feed:generate 42
Après :
php artisan feed:generate products
Dans 2.x, l’argument est toujours un slug ; une chaîne numérique ne sélectionne plus un identifiant en base de données. L’appel à php artisan feed:generate sans argument traite toujours tous les enregistrements actifs. Avec --target, remplacez uniquement l’argument d’enregistrement ; les clés des cibles restent identiques :
php artisan feed:generate products --target=42
Mettez à jour les planifications manuelles et les appels de commandes dans le code de la même manière. Avant :
use DragonCode\LaravelFeed\Commands\FeedGenerateCommand;
use Illuminate\Support\Facades\Schedule;
Schedule::command(FeedGenerateCommand::class, [42])->daily();
Après :
use DragonCode\LaravelFeed\Commands\FeedGenerateCommand;
use Illuminate\Support\Facades\Schedule;
Schedule::command(FeedGenerateCommand::class, ['products'])->daily();
Conservez les paramètres existants des planifications manuelles pour les chevauchements, l’exécution en arrière-plan et la fréquence. Mettez à jour les slugs écrits en dur lorsque vous renommez des enregistrements. ScheduleFeedHelper::register() utilise automatiquement les slugs stockés et maintient les verrous de chevauchement liés à l’enregistrement lorsque son titre ou son expression cron change.
FeedQuery::find(int $id), delete(int $id) et restore(int $id) utilisent toujours des identifiants. Utilisez FeedQuery::findBySlug(string $slug) pour sélectionner par slug. Consultez la génération et la planification.
Vérifier les titres générés
La PR #293 supprime le suffixe Feed des titres écrits par make:feed dans les nouvelles migrations d’enregistrement ou opérations de déploiement.
Pour php artisan make:feed ProductsFeed :
| Valeur | Avant | Après |
|---|---|---|
| Titre d’enregistrement généré | Products Feed | Products |
| Slug dérivé de ce titre | products-feed | products |
Les titres existants en base de données et les fichiers d’enregistrement générés auparavant ne sont pas réécrits. Continuez à utiliser le slug réellement stocké pour chaque enregistrement. Le nom de la classe du flux et le nom du fichier de sortie ne sont pas modifiés par ce changement de titre.
Documentation et développement du paquet
La PR #294 renomme la page de documentation Apprentissage automatique en Agents IA. La page est désormais disponible à l’adresse /ai-agents/ ; les redirections maintiennent les liens vers son ancienne URL.
La PR #297 définit les nouvelles exigences d’exécution et conserve la documentation de 1.x. Sélectionnez la version de documentation correspondant au paquet installé ; les résultats de recherche et le contexte des LLM sont limités à cette version.
L’environnement de développement du paquet passe à Pest ^5.0 et Testbench ^11.0. Ses commandes Pest utilisent --tia, avec --fresh pour les réexécutions complètes en CI, les benchmarks et les mises à jour des instantanés. Ce sont des dépendances de développement du paquet, pas des exigences pour la suite de tests d’une application.
Vérifier
- Reconstruisez le cache de configuration de l’application s’il est utilisé et redémarrez les workers de file d’attente et les processus persistants du planificateur avec le nouveau code.
- Vérifiez que chaque enregistrement sélectionné possède un slug non vide et distinct, et que les commandes et planifications manuelles l’utilisent.
- Générez un flux pour chaque format utilisé ; vérifiez le nombre et les noms des fichiers fractionnés, ainsi que des sorties représentatives, par rapport aux sorties sauvegardées de
1.x. - Vérifiez la sélection des cibles, les planifications automatiques et manuelles et la génération en file d’attente, lorsqu’elles sont utilisées.
- Exécutez les tests de l’application couvrant les modèles de flux personnalisés, les transformateurs, les macros et les sous-classes de préréglage.
- Reprenez les planifications des flux et le traitement des files d’attente une fois les vérifications du schéma et de la génération réussies.
Revenir en arrière
Suspendez à nouveau la génération des flux et laissez se terminer les tâches en cours. Restaurez le code précédent de l’application, composer.json, composer.lock, la configuration et les commandes de génération, puis exécutez composer install dans un environnement d’exécution compatible.
N’appliquez la politique d’annulation des migrations de l’application qu’après avoir vérifié si le paquet 1.x restauré utilise déjà des slugs. La méthode down() de la migration des slugs supprime uniquement cette colonne ; elle ne restaure ni les titres renommés ni les fichiers générés. Restaurez les données d’enregistrement modifiées et les fichiers de sortie depuis les sauvegardes, si nécessaire. Reconstruisez les caches de configuration et redémarrez les workers et les processus du planificateur avant de reprendre la génération.