Compreendendo os ganchos de atualização e pós-atualização para atualizações bem-sucedidas do site

Durante as atualizações do núcleo ou atualizações do módulo, é crucial garantir a estabilidade e a integridade do seu site Drupal. Felizmente, o módulo API de atualização e os ganchos de atualização/pós-atualização estão aqui para ajudar.

O módulo Update API fornece os ganchos necessários para atualizar o código e os módulos em seu site Drupal. Esses ganchos nada mais são do que ganchos de atualização e pós-atualização que permitem aos desenvolvedores personalizar as atualizações de acordo com suas necessidades.

Neste artigo, discutiremos a API de atualização, o que são ganchos de atualização e pós-atualização e quando e como eles devem ser usados. Compreendendo os dois tipos de ganchos, você pode atualizar com sucesso seu site Drupal com o mínimo de esforço. Vamos começar!

A API de atualização

Ao trabalhar em um site existente, quando você atualiza o código em um módulo, pode ser necessário atualizar os dados armazenados para que sejam compatíveis com o novo código. Você deve ter notado erros como 'O site encontrou um erro inesperado' piscando na sua frente. Assustador né!? Eu sei! É aqui que a API de atualização do Drupal vem em nosso socorro.

Se a atualização estiver entre duas versões secundárias de seu módulo dentro da mesma versão principal do núcleo do Drupal, você poderá usar a API de atualização para atualizar os dados. A API de atualização permite fornecer código que executa uma atualização nos dados armazenados sempre que seu módulo faz uma alteração em seu modelo de dados. A alteração do modelo de dados refere-se a qualquer alteração que torne os dados armazenados em um site existente incompatível com a base de código atualizada desse site. Essas mudanças no modelo de dados envolvem:

Atualizando o esquema de configuração

• Adicionar/remover/renomear uma chave de configuração.
• Alterar o tipo de dados da chave de configuração.
• Alterar o valor padrão esperado de uma chave de configuração, etc.

Atualizando o esquema do banco de dados

• Adicionar/alterar/remover uma tabela ou campo do banco de dados.
• Mover os dados armazenados para um campo ou tabela diferente.
• Alterar o formato dos dados armazenados, etc.

Atualizando as Entidades e Campos

• Adicionar um novo campo base a um tipo de entidade existente.
• Atualizar um campo de um tipo obsoleto para um novo tipo, etc.

Atualizando os dados

• Manipule os dados armazenados em um site existente.

Trabalhando com ganchos de atualização

Hook hook_update_N() é usado para introduzir uma atualização entre as versões secundárias de um módulo. Esses ganchos são colocados em seu módulo no arquivo *.install .

O hook_update_N() é escrito na forma de (nome do módulo)_update_(número). Aqui N é composto por:

• 1 ou 2 dígitos referem-se à compatibilidade do núcleo do Drupal (Drupal 8, 9, 10, etc.)
• O próximo 1 dígito é para a versão principal do seu módulo
• Os últimos 2 dígitos para contagem sequencial, começando com 01

Exemplo:

example_update_9201(): A primeira atualização para as versões 9.x-2.x.
Onde 'exemplo' é o nome do módulo, o primeiro dígito refere-se à versão principal '9' do Drupal, o número '2' refere-se à versão principal do módulo e os dois últimos dígitos '01' indicam a primeira função de atualização escrita para módulo 'exemplo'.

A parte numérica da função de implementação do gancho (ou seja, 9201 no exemplo acima) é armazenada no banco de dados para acompanhar quais atualizações já foram executadas. Portanto, você nunca deve renumerar as funções de atualização.
Para saber a versão atual do esquema de um módulo 'exemplo armazenado no banco de dados', use:

drush php-eval "echo drupal_get_installed_schema_version('example');"

Para definir manualmente a versão atual do esquema de um módulo 'exemplo' de volta para '9201', use:

drush php-eval "echo drupal_set_installed_schema_version('example', '9201');"

Observação: tente evitar o uso da função drupal_set_installed_schema_version() em sites de produção, pois ela atualiza diretamente seu banco de dados. Você pode usá-lo em seus ambientes de teste locais ou inferiores durante o desenvolvimento para redefinir a versão do esquema.

Adicione uma descrição adequada no comentário do bloco de documento antes da função de gancho de atualização, pois ela será impressa para os usuários durante a execução.

 Structure of hook_update_N(): /** * A aimple hook_update_N() hook. */ function example_update_9201() { // Code goes here. }

Esses ganchos são executados em ordem de classificação, ou seja, o gancho example_update_9201() é executado antes de example_update_9202(), o próximo é 9203, 9204 e assim por diante.

Você também pode alterar a ordem de classificação desses ganchos, introduzindo dependências entre os ganchos. Use o gancho hook_update_dependencies() para executar atualizações entre dois ganchos de atualização.

Todos os ganchos de atualização são executados em lote e também suportam processamento em lote de itens. Todos os ganchos de atualização têm acesso a um parâmetro $sandbox que pode ser usado para criar processos em lote nos ganchos de atualização para processar grandes quantidades de dados de uma só vez sem causar o tempo limite do PHP.

Um exemplo simples de um gancho de atualização para adicionar uma nova chave de configuração:

Atualmente, o arquivo example_module.settings.yml contém:

Para adicionar uma nova 'descrição' de chave à configuração:

• Adicione a chave 'descrição' ao arquivo de configurações

• Adicione o update_hook no arquivo example_module.install:

• Use drush updb para executar o gancho.

• Verifique a configuração atualizada, a nova chave 'descrição' está atualizada.

Trabalhando com ganchos de pós-atualização

Hook hook_post_update_NAME(), semelhante ao gancho de atualização, é usado para introduzir uma atualização. Mas esse gancho destina-se principalmente a atualizar dados, como entidades. Esses ganchos são executados depois que todos os ganchos hook_update_N() são executados. Nesta fase, o Drupal já está totalmente reparado para que você possa usar qualquer API dentro do site.

Esses ganchos são colocados em um arquivo *.post_update.php em seu módulo.

O hook_post_update_NAME() é escrito na forma de (nome do módulo)_post_update_(qualquer nome). Aqui NAME pode ser qualquer nome de máquina arbitrário. Essa nomenclatura alfanumérica das funções no arquivo é a única coisa que garante a ordem de execução desse hook.

Semelhante aos ganchos de atualização, adicione uma descrição adequada no comentário do docblock antes do gancho post_update. Além disso, não reutilize o mesmo nome de gancho.

Estrutura de hook_post_update_NAME():

 /** * A aimple hook_post_update_NAME() hook. */ function example_post_update_test() { // Code goes here. }

Assim como com ganchos de atualização, use o parâmetro $sandbox para indicar que a API de lote deve ser usada para seus ganchos post_update.

Um exemplo simples sobre o uso do gancho pós-atualização para atualizar os dados do termo:

• Atualmente, todos os termos no vocabulário Tags têm um campo 'Exemplo de teste' desativado.

• Adicione um gancho post_update no arquivo example_module.post_update.php para habilitar o campo 'Exemplo de teste' para todos os termos existentes.

• Use drush updb para executar o gancho.

• Verifique os dados atualizados do termo, a caixa de seleção 'Exemplo de teste' deve ser habilitada.

Como executar esses ganchos!

Você pode usar o comando Drush para executar esses ganchos, drush updb. Ele constrói o lote nas seguintes etapas:

• Todos os ganchos de atualização são descobertos.
• Resolve a dependência e classifica sua ordem.
• Ganchos são colocados para processamento em lote.
• Em seguida, todos os ganchos Post são descobertos.
• Se houver ganchos post_update e se update_hook tiver sido executado anteriormente, os caches serão limpos.
• Em seguida, insira cada gancho post_update no lote.
• Execute o lote.

Uma grande vantagem do gancho pós-atualização sobre o gancho de atualização é que o Drupal está totalmente funcional no momento em que a pós-atualização é executada. Isso permite que os desenvolvedores usem qualquer serviço Drupal enquanto usam o gancho pós-atualização. Com o gancho de atualização, não se deve presumir que o Drupal está totalmente reparado e evitar invocar outros ganchos, APIs de entidade, etc.

Pensamentos finais

Ao tentar consertar seu site atualizando o esquema de configuração/banco de dados, tente usar ganchos de atualização. Quando se trata de manipular dados armazenados, salvar novamente configurações, atualizar entidades de conteúdo, limpar o cache etc., os ganchos de pós-atualização são mais apropriados para usar.

Para ser honesto, não há documentação clara no Drupal.org sobre quando usar qual gancho! Há um problema em aberto solicitando a melhoria da documentação sobre o uso desses dois ganchos para os quais você pode contribuir, se quiser.

Mas com base na experiência dos desenvolvedores e observando os módulos principais do Drupal 9 e 10 como exemplo, use ganchos de atualização para executar operações CRUD em configurações ou bancos de dados (ou seja, reparar o site) e usar ganchos de pós-atualização para entidades de conteúdo CRUD ( em seguida, corrija os dados no site atualizado), pois os ganchos pós-atualização são executados após os ganchos de atualização.

Gostou de ler este artigo? Mostre-nos um pouco de amor e assine nossa newsletter semanal hoje!