Comprensión de los ganchos de actualización y publicación de actualizaciones para actualizaciones exitosas del sitio

Durante las actualizaciones del núcleo o de los módulos, es fundamental garantizar la estabilidad y la integridad de su sitio web de Drupal. Afortunadamente, el módulo API de actualización y los ganchos de actualización/publicación de actualización están aquí para ayudar.

El módulo Actualizar API proporciona los enlaces necesarios para actualizar el código y los módulos en su sitio de Drupal. Estos ganchos no son más que ganchos de actualización y posteriores a la actualización que permiten a los desarrolladores personalizar las actualizaciones de acuerdo con sus necesidades.

En este artículo, analizaremos la API de actualización, qué son los ganchos de actualización y posteriores a la actualización y cuándo y cómo deben usarse. Al comprender ambos tipos de ganchos, puede actualizar con éxito su sitio Drupal con un mínimo esfuerzo. ¡Empecemos!

La API de actualización

Mientras trabaja en un sitio existente, cuando actualiza el código en un módulo, es posible que deba actualizar los datos almacenados para que sean compatibles con el nuevo código. Es posible que haya notado errores como "El sitio web encontró un error inesperado" parpadeando frente a usted. ¿¡Aterrador verdad!? ¡Lo sé! Aquí es donde la API de actualización de Drupal viene a nuestro rescate.

Si la actualización se encuentra entre dos versiones secundarias de su módulo dentro de la misma versión principal del núcleo de Drupal, puede usar la API de actualización para actualizar los datos. La API de actualización le permite proporcionar un código que realiza una actualización de los datos almacenados cada vez que su módulo realiza un cambio en su modelo de datos. El cambio del modelo de datos se refiere a cualquier cambio que haga que los datos almacenados en un sitio existente sean incompatibles con el código base actualizado de ese sitio. Estos cambios en el modelo de datos implican:

Actualización del esquema de configuración

• Agregar/eliminar/renombrar una clave de configuración.
• Cambiar el tipo de datos de la clave de configuración.
• Cambiar el valor predeterminado esperado de una clave de configuración, etc.

Actualización del esquema de la base de datos

• Agregar/cambiar/eliminar una tabla o campo de la base de datos.
• Mover los datos almacenados a un campo o tabla diferente.
• Cambiar el formato de los datos almacenados, etc.

Actualización de entidades y campos

• Agregar un nuevo campo base a un tipo de entidad existente.
• Actualizar un campo de un tipo obsoleto a un nuevo tipo, etc.

Actualización de los datos

• Manipular los datos almacenados en un sitio existente.

Trabajar con ganchos de actualización

Hook hook_update_N() se usa para introducir una actualización entre versiones menores de un módulo. Estos ganchos se colocan dentro de su módulo en el archivo *.install .

hook_update_N() está escrito en forma de (nombre del módulo)_update_(número). Aquí N se compone de:

• 1 o 2 dígitos se refieren a la compatibilidad del núcleo de Drupal (Drupal 8, 9, 10, etc.)
• El siguiente dígito es para la versión de lanzamiento principal de su módulo
• Los últimos 2 dígitos para conteo secuencial, comenzando con 01

Ejemplo:

example_update_9201(): La primera actualización para las versiones 9.x-2.x.
Donde 'ejemplo' es el nombre del módulo, el primer dígito se refiere a la versión principal de Drupal '9', el número '2' se refiere a la versión de lanzamiento principal del módulo y los dos últimos dígitos '01' indican la primera función de actualización escrita para módulo 'ejemplo'.

La parte numérica de la función de implementación de enlace (es decir, 9201 en el ejemplo anterior) se almacena en la base de datos para realizar un seguimiento de las actualizaciones que ya se han ejecutado. Por lo tanto, nunca debe volver a numerar las funciones de actualización.
Para conocer la versión de esquema actual de un módulo 'ejemplo almacenado en la base de datos', use:

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

Para configurar manualmente la versión de esquema actual de un módulo 'ejemplo' de nuevo a '9201', use:

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

Nota: Intente evitar el uso de la función drupal_set_installed_schema_version() en sitios de producción, ya que actualiza directamente su base de datos. Puede usarlo en sus entornos de prueba locales o inferiores durante el desarrollo para restablecer la versión del esquema.

Agregue una descripción adecuada en el comentario del bloque de documentos antes de la función de gancho de actualización, ya que se imprimirá para los usuarios mientras la ejecutan.

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

Estos ganchos se ejecutan en orden ordenado, es decir, el gancho ejemplo_actualización_9201() se ejecuta antes que ejemplo_actualización_9202(), el siguiente es 9203, 9204 y así sucesivamente.

También puede cambiar el orden de clasificación de estos enlaces introduciendo dependencias entre los enlaces. Usa el enlace hook_update_dependencies() para ejecutar actualizaciones entre dos enlaces de actualización.

Todos los ganchos de actualización se ejecutan por lotes y también admiten el procesamiento por lotes de artículos. Todos los ganchos de actualización tienen acceso a un parámetro $sandbox que se puede usar para crear procesos por lotes en los ganchos de actualización para procesar grandes datos a la vez sin causar que se agote el tiempo de espera de PHP.

Un ejemplo simple de un enlace de actualización para agregar una nueva clave de configuración:

Actualmente, el archivo example_module.settings.yml contiene:

Para agregar una nueva clave 'descripción' a la configuración:

• Agregue la clave de 'descripción' al archivo de configuración

• Agregue update_hook en el archivo example_module.install:

• Use drush updb para ejecutar el gancho.

• Verifique la configuración actualizada, la nueva clave 'descripción' está actualizada.

Trabajar con ganchos posteriores a la actualización

El gancho hook_post_update_NAME(), similar al gancho de actualización, se usa para introducir una actualización. Pero este gancho está destinado principalmente a actualizar datos, como entidades. Estos ganchos se ejecutan después de ejecutar todos los ganchos hook_update_N(). En esta etapa, Drupal ya está completamente reparado para que pueda usar cualquier API dentro del sitio.

Estos ganchos se colocan en un archivo *.post_update.php en su módulo.

El hook_post_update_NAME() está escrito en forma de (nombre del módulo)_post_update_(cualquier nombre). Aquí NOMBRE puede ser cualquier nombre de máquina arbitrario. Esta denominación alfanumérica de funciones en el archivo es lo único que asegura el orden de ejecución de este hook.

De forma similar a los ganchos de actualización, agregue una descripción adecuada en el comentario de docblock antes del gancho post_update. Además, no reutilices el mismo nombre de gancho.

Estructura de hook_post_update_NAME():

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

Al igual que con los ganchos de actualización, use el parámetro $sandbox para indicar que la API de Batch debe usarse para sus ganchos posteriores a la actualización.

Un ejemplo simple sobre el uso del gancho posterior a la actualización para actualizar los datos del término:

• Actualmente, todos los términos en Vocabulario de etiquetas tienen un campo de 'Ejemplo de prueba' deshabilitado.

• Agregue un enlace post_update en el archivo example_module.post_update.php para habilitar el campo 'Ejemplo de prueba' para todos los términos existentes.

• Use drush updb para ejecutar el gancho.

• Verifique los datos del término actualizado, la casilla de verificación 'Ejemplo de prueba' debe estar habilitada.

¡Cómo ejecutar estos ganchos!

Puede usar el comando Drush para ejecutar estos ganchos, drush updb. Construye el lote en los siguientes pasos:

• Se descubren todos los ganchos de actualización.
• Resuelve la dependencia y ordena su orden.
• Los ganchos se colocan para el procesamiento por lotes.
• A continuación, se descubren todos los ganchos de Post.
• Si hay ganchos posteriores a la actualización, y si update_hook se ejecutó anteriormente, se borran los cachés.
• Luego, inserte cada enlace post_update en el lote.
• Ejecutar el lote.

Una de las principales ventajas que tiene el enlace posterior a la actualización sobre el enlace de actualización es que Drupal es completamente funcional en el momento en que se ejecuta la actualización posterior. Esto permite a los desarrolladores usar cualquier servicio de Drupal mientras usan el gancho posterior a la actualización. Con el gancho de actualización, no se debe asumir que Drupal está completamente reparado y evitar invocar otros ganchos, API de entidades, etc.

Pensamientos finales

Cuando intente arreglar su sitio actualizando el esquema de configuración/base de datos, intente usar ganchos de actualización. Cuando se trata de manipular datos almacenados, volver a guardar configuraciones, actualizar entidades de contenido, borrar el caché, etc., entonces los ganchos posteriores a la actualización son más apropiados para usar.

Para ser honesto, no hay una documentación clara en Drupal.org con respecto a cuándo usar qué enlace. Hay un problema abierto que solicita mejorar la documentación sobre el uso de estos dos ganchos a los que puede contribuir si lo desea.

Pero según la experiencia de los desarrolladores y al observar los módulos principales de Drupal 9 y 10 como ejemplo, use ganchos de actualización para realizar operaciones CRUD en configuraciones o bases de datos (es decir, reparar el sitio) y use ganchos posteriores a la actualización para entidades de contenido CRUD ( luego corrija los datos en el sitio actualizado), ya que los ganchos posteriores a la actualización se ejecutan después de los ganchos de actualización.

¿Te gustó leer este artículo? ¡Muéstranos un poco de amor y suscríbete a nuestro boletín semanal hoy!