Atualizar de 1.x para 2.x
Siga estas etapas ao migrar uma aplicação existente do Laravel Feeds 1.x para 2.x. Se a versão 1.x instalada já inclui slugs dos feeds ou os títulos gerados atualizados, mantenha essas alterações e ignore as etapas já concluídas.
Requisitos de execução
| Componente | 1.x | 2.x |
|---|---|---|
| PHP | ^8.2 | ^8.4 |
| Componentes Laravel | ^11.0 || ^12.0 || ^13.0 | ^13.0 |
Antes de instalar 2.x, atualize as dependências Laravel da aplicação e os ambientes PHP usados pela aplicação web, CLI, agendador e workers de fila. Aplicações que usam PHP 8.2 ou 8.3, ou Laravel 11.x ou 12.x, devem permanecer na versão 1.x. Consulte a compatibilidade para verificar o ambiente suportado.
Antes de atualizar
- Salve o código atual da aplicação,
composer.json,composer.locke oconfig/feeds.phppublicado. Faça backup da tabela de registro de feeds e dos arquivos gerados necessários para reverter a atualização. - Registre os IDs dos registros, títulos, slugs existentes, agendamentos e destinos de saída.
- Localize chamadas a
feed:generateem scripts de implantação, tarefas cron, agendamentos manuais, testes e código da aplicação. - Gere feeds representativos e guarde a saída para comparação.
- Durante a implantação, pause os agendamentos dos feeds e aguarde a conclusão dos jobs de feeds em execução ou na fila antes de substituir o pacote e alterar o esquema.
Aplicar a atualização
composer require dragon-code/laravel-feeds:^2.0 --with-all-dependencies
composer check-platform-reqs
Compare o config/feeds.php do pacote instalado com a cópia publicada na aplicação e mantenha as configurações específicas da aplicação. Não publique novamente com --force: ele sobrescreve essa cópia.
Adicionar slugs aos feeds
O PR #287 altera a seleção de um feed específico de um ID do banco de dados para um slug derivado com Str::slug(title).
Se a migration de slugs do pacote ainda não foi executada, publique as migrations:
php artisan vendor:publish --tag=feeds-migrations
O comando publica todos os arquivos de migration. Valide os arquivos publicados e exclua os desnecessários.
Defina o timestamp no nome do arquivo da nova migration add_slug_to_feeds_table depois da migration create_feeds_table efetivamente presente na aplicação e antes de todas as migrations de registro de feeds. Essa ordem garante que migrate:fresh adicione a coluna slug antes que os registros gravem nela. Depois, execute as migrations:
php artisan migrate
A migration adiciona uma coluna slug que aceita valores NULL e a preenche a partir dos títulos existentes, incluindo registros excluídos logicamente. Os títulos e IDs existentes são preservados.
Se a aplicação já possui sua própria coluna slug e a migration do pacote ainda não foi executada, a migration falha antes de preencher qualquer dado. Resolva esse conflito de esquema antes da implantação; não exclua uma coluna da aplicação sem preservar seus dados e atualizar o código que a utiliza.
Inspecione os valores armazenados em php artisan tinker:
app(\DragonCode\LaravelFeed\Queries\FeedQuery::class)
->all()
->get(['id', 'title', 'slug']);
Os slugs usados na seleção devem ser distintos e não vazios entre os registros não excluídos, incluindo os inativos. Títulos diferentes podem resultar no mesmo slug após a normalização. Buscas ambíguas lançam MultipleRecordsFoundException; slugs desconhecidos lançam FeedNotFoundException. Resolva colisões ou slugs vazios atualizando os títulos pelo modelo do feed.
Em 2.3.0, o PR #334 substitui a sobrescrita de fireModelEvent() por FeedObserver::saving(). Antes, o slug era derivado dos atributos brutos após saving, creating e updating, inclusive em salvamentos silenciosos. Agora usa o título exposto pelo accessor no momento do observer saving; salvamentos silenciosos o ignoram e listeners posteriores não provocam novo cálculo.
O PR #335 adiciona uma verificação de $feed->isDirty('slug'): um slug alterado explicitamente é normalizado com Str::slug() e preservado no salvamento atual, mesmo quando title também muda. FeedQuery::create() o aceita por meio de extra: ['slug' => 'Custom Catalog']. Um slug não alterado continua sendo derivado de title; portanto, um salvamento normal posterior pode substituir um slug personalizado fornecido antes. Atribuir um valor cuja normalização resulte no slug atual não impede o recálculo.
Ao atualizar de uma versão 1.x ou 2.x anterior, revise atribuições explícitas de slug, salvamentos silenciosos, accessors de título, listeners de eventos, seleções parciais, casts personalizados e gravações em massa. Teste o título e o slug armazenados, um salvamento normal posterior, a busca por slug e a geração agendada. A instalação da atualização por si só não altera registros, mas o próximo salvamento normal pode alterar um slug personalizado ou derivado de um accessor mesmo sem mudar o título. Atualize os slugs fixos em comandos e agendamentos quando necessário. Veja Eloquent para o tratamento de slugs explícitos, salvamentos silenciosos e listeners.
Substituir IDs nas chamadas de geração
Para o registro de ID 42 com o título armazenado Products, o slug após a migration é products.
Antes:
php artisan feed:generate 42
Depois:
php artisan feed:generate products
Em 2.x, o argumento é sempre um slug; uma string numérica não seleciona mais um ID do banco de dados. Chamar php artisan feed:generate sem argumento continua processando todos os registros ativos. Com --target, substitua somente o argumento do registro; as chaves dos alvos permanecem iguais:
php artisan feed:generate products --target=42
Atualize os agendamentos manuais e as chamadas de comandos no código da mesma forma. Antes:
use DragonCode\LaravelFeed\Commands\FeedGenerateCommand;
use Illuminate\Support\Facades\Schedule;
Schedule::command(FeedGenerateCommand::class, [42])->daily();
Depois:
use DragonCode\LaravelFeed\Commands\FeedGenerateCommand;
use Illuminate\Support\Facades\Schedule;
Schedule::command(FeedGenerateCommand::class, ['products'])->daily();
Mantenha as configurações existentes de sobreposição, execução em segundo plano e frequência dos agendamentos manuais. Atualize os slugs escritos diretamente no código ao renomear registros. ScheduleFeedHelper::register() usa os slugs armazenados automaticamente e mantém os bloqueios de sobreposição vinculados ao registro quando seu título ou expressão cron muda.
FeedQuery::find(int $id), delete(int $id) e restore(int $id) continuam usando IDs. Use FeedQuery::findBySlug(string $slug) para selecionar pelo slug. Consulte geração e agendamento.
Verificar os títulos gerados
O PR #293 remove o sufixo Feed dos títulos gravados por make:feed em novas migrations de registro ou operações de implantação.
Para php artisan make:feed ProductsFeed:
| Valor | Antes | Depois |
|---|---|---|
| Título de registro gerado | Products Feed | Products |
| Slug derivado desse título | products-feed | products |
Os títulos existentes no banco de dados e os arquivos de registro gerados anteriormente não são reescritos. Continue usando o slug efetivamente armazenado de cada registro. O nome da classe do feed e o nome do arquivo de saída não mudam com essa atualização do título.
Documentação e desenvolvimento do pacote
O PR #294 renomeia a página de documentação de Aprendizado de máquina para Agentes de IA. A página agora está disponível em /ai-agents/; os redirecionamentos mantêm os links para a URL anterior.
O PR #297 estabelece os novos requisitos de execução e preserva a documentação de 1.x. Selecione a versão da documentação que corresponde ao pacote instalado; os resultados de busca e o contexto dos LLMs ficam limitados a essa versão.
O ambiente de desenvolvimento do próprio pacote passa a usar Pest ^5.0 e Testbench ^11.0. Seus comandos Pest usam --tia, com --fresh para execuções completas em CI, benchmarks e atualizações de snapshots. Essas são dependências de desenvolvimento do pacote, não requisitos para a suíte de testes de uma aplicação.
Verificar
- Reconstrua o cache de configuração da aplicação, se usado, e reinicie os workers de fila e os processos persistentes do agendador com o novo código.
- Confirme que cada registro selecionado tem um slug distinto e não vazio e que os comandos e agendamentos manuais o utilizam.
- Gere um feed para cada formato usado; verifique a quantidade e os nomes dos arquivos divididos e compare saídas representativas com a saída de
1.xsalva anteriormente. - Verifique a seleção dos alvos, os agendamentos automáticos e manuais e a geração em fila, quando usados.
- Execute os testes da aplicação que abrangem modelos de feed personalizados, transformadores, macros e subclasses de predefinições.
- Retome os agendamentos dos feeds e o processamento da fila depois que as verificações do esquema e da geração passarem.
Reverter
Pause novamente a geração dos feeds e aguarde a conclusão dos jobs em andamento. Restaure o código anterior da aplicação, composer.json, composer.lock, a configuração e os comandos de geração e execute composer install em um ambiente de execução compatível.
Aplique a política de rollback das migrations da aplicação somente depois de confirmar se o pacote 1.x restaurado já utiliza slugs. O método down() da migration de slugs exclui somente essa coluna; ele não restaura títulos renomeados nem arquivos gerados. Restaure os dados de registro alterados e os arquivos de saída a partir dos backups, quando necessário. Reconstrua os caches de configuração e reinicie os workers e os processos do agendador antes de retomar a geração.