La API de Actualización es mediante la cual un módulo se instala y se actualiza por si mismo, sin perder de vista su propia versión.
Introducción
Mediante la implementación de esta API en su plugin, Moodle creará automáticamente las tablas de bases de datos por usted al visitar la página de notificaciones del administrador (.../admin/index.php).
Este proceso es controlado por tres archivos dentro de su plugin (hay otros archivos opcionales que puede utilizar para varias cosas. Éstos están cubiertos al final de este documento.):
- https://docs.moodle.org/dev/version.php
- Esto graba la versión del código del plugin (Tener en cuenta: En las instalaciones de Moodle debajo de la versión 2.0, esto no es necesario para los bloques, que utilizan el número de versión devuelto por el método init() del bloque - ver página sobre el desarrollo de los bloques). Debe aumentar versión en version.php después de cualquier cambio en la carpeta /db/, cualquier cambio en el código Javascript y después de cualquier cambio en el paquete de idioma porque nuevas versiones desencadenan el procedimiento de actualización y resetea todas las cachés.
- db/install.xml
- Esto se usa cuando alguien instala el plug-in por primera vez.
- db/upgrade.php
- Esto se usa cuando alguien que tenía instalada una versión anterior de su plugin actualiza a la última versión.
Además , Moodle también almacena en la base de datos de la versión actualmente instalada de cada plugin.
En Moodle 1.x, esta se almacena en la tabla mdl_config , en una fila con el nombre plugintype_pluginname_VERSION. Por ejemplo qtype_myqtype_version. La excepción a esta regla son los módulos y bloques. Los números de versión de los módulos instalados se almacenan en la tabla mdl_modules. Los números de versión de los bloques están en mdl_block.
En Moodle 2.x, los números de versión de los plug-ins se almacenan en la tabla mdl_config_plugins, con plugintype_pluginname en la columna plugin, y 'versión' en la columna de nombre - con la misma excepción para los módulos y bloques.
Ejemplo
Para el resto de este documento, se va a utilizar un ejemplo particular, ya que debe hacer la explicación más fácil. Usted debería ser capaz de ver cómo generalizarlo.
Vamos a suponer que usted está haciendo un nuevo tipo de pregunta myqtype. Este es el tipo de plugin qtype, y el código estará en la carpeta question/type/myqtype. El número de la versión instalada actualmente se almacenará en la fila ('qtype_myqtype', 'versión') de la tabla mdl_config_plugins.
Además, nos limitaremos a considerar las dos primeras versiones del plugin. La primera versión tendrá número de versión 2008080100, y sólo utilizará una tabla mdl_myqtype_options, con dos columnas col1 y col2. Luego vamos a suponer que la segunda versión es 2008080200, y que requiere una columna adicional, newcol, que se añade a la tabla mdl_myqtype_options.
Los ficheros que necesita para la primera versión
En lo que sigue, las partes de código que necesita para reemplazar están en negrita.
- version.php
$plugin->version = 2008080100 ; // Fecha de hoy en formato AAAAMMDD, además de dos dígitos adicionales $plugin->requires = XXXXXXXXXX; // Versión de Moodle - copiar desde $version en el archivo /moodle/version.php archivo.
- Los números de versión consisten normalmente en la fecha del día en formato AAAAMMDD, seguido de dos dígitos adicionales para permitir múltiples versiones en el mismo día, por ejemplo, 15 de septiembre 2010 podría tener versiones 2010091500, 2010091501, 2010091502, etc.
- db/install.xml
- Este archivo, que debería crear con el editor XMLDB, debe contener la definición de la tabla mdl_myqtype_options, con las dos columnas col1 y col2.
En esta etapa, usted no necesita un archivo db/upgrade.php
Los ficheros que necesita para la segunda versión
- version.php
$plugin->version = 2008080200 ; $plugin->requires = XXXXXXXXXX ; // Copiar el valor actual del archivo version.php
- db/install.xml
- Este archivo debe contener ahora la definición actualizada de su tabla mdl_myqtype_options, con tres columnas col1, col2 y Newcol. Este archivo se modifica usando el editor XMLDB.
- db/upgrade.php
- Este archivo debe contener el código necesario para ejecutar la actualización desde la versión 2008080100 del plugin. Es decir, el código para añadir una columna newcol a la tabla mdl_myqtype_options. Usted no tiene que escribir este código usted mismo ya que el editor XMLDB lo generará por usted. El archivo upgrade.php debe contener una sola función xmldb_qtype_myqtype_upgrade parecida a:
function xmldb_qtype_myqtype_upgrade($oldversion = 0) {
global $DB;
$dbman = $DB->get_manager();
$result = true;
/// Add a new column newcol to the mdl_myqtype_options
if ($result && $oldversion < 2008080200) {
// Code to add the column, generated by the 'View PHP Code' option of the XMLDB editor.
}
return $result;
}
Sugerencia: Si desea modificar o agregar un campo/tabla, use el editor XMLDB para generar el código por usted después de hacer los cambios en el editor. Si va a eliminar uno, usted necesita generar el código PHP antes de hacer el cambio - o no podrá de seleccionar el campo/tabla para el cual escribir el código, porque ya no existirá.
Qué sucede cuando un usuario instala o actualiza tu plugin
El proceso se inicia cuando el administrador va a la página de notificaciones admin (.../admin/index.php). El código que hace el trabajo es la función upgrade_plugins en lib/adminlib.php y la lectura de este código es la mejor manera de averiguar exactamente lo que sucede. En pseudo-código , lo que hace es :
Para cada plugin de este tipo (por ejemplo, todos los plugins qtype) {
// Para el cuerpo de este bucle , supongamos que el plugin que se está procesando es myqtype.
Compruebar que question/type/myqtype/version.php, .../db/upgrade.php y .../db/install.xml existan.
if (get_config('qtype_myqtype', 'version') existe , y es menor que el número en version.php ) {
Llame a la función de actualización xmldb_qtype_myqtype_upgrade de upgrade.php,
pasando el número de la versión antigua que dice lo que está instalado actualmente
set_config ('versión', número de version más reciente de version.php , 'qtype_myqtype')
para registrar lo que está instalado actualmente
} else if if (get_config('qtype_myqtype', 'version') no existe) {
Crear las tablas de las definiciones de install.xml
set_config('versión', número más reciente de version.php, 'qtype_myqtype')
para registrar lo que está instalado actualmente
}
}
Por supuesto, es un poco más complejo que esto. Sin embargo , el código en upgrade_plugins es bastante claro, y le animo a ir a echarle un vistazo para que pueda ver todos los detalles de cómo funciona.
Veamos ahora algunos ejemplos prácticos:
Usuario instala la versión 2008080100 de myqtype
Para empezar, no existe mdl_myqtype_options, y no habrá una fila ('qtype_myqtype', 'version') de la tabla mdl_config_plugins.
- El usuario descomprimirá myqtype.zip en la carpeta question/type.
- El usuario visitará la página de notificaciones de administrador.
- Esto hará que Moodle busque plugings para actualizar. Econtrará que el código para el plugin qtype_myqtype está presente, pero no hay rastro de este en la base de datos, por lo que instalar el plugin desde el archivo install.xml.
Al final de este proceso, la tabla mdl_myqtype_options existirá con las dos columnas col1 y col2; y la fila ('qtype_myqtype', 'version') de la tabla mdl_config_plugins contendrá 2008080100.
Usuario actualiza de la versión 2008080100 a la versión 2008080200
Para empezar, la tabla mdl_myqtype_options existirá con las dos columnas col1 y col2; y la fila ('qtype_myqtype', 'versión') de la tabla mdl_config_plugins contendrá 2008080100.
- El usuario eliminará la carpeta question/type/myqtype.
- El usuario descomprimirá el nuevo myqtype.zip en la carpeta question/type.
- El usuario visitará la página de notificaciones de administrador.
- Esto hará que Moodle busque plugings para actualizar. Se dará cuenta de que el código de la versión 2008080200 del plugin qtype_myqtype está presente, pero la versión instalada de las tabla ('qtype_myqtype', 'version') de bases de datos es 2008080100. Por lo tanto, se llamará a xmldb_qtype_myqtype_upgrade de upgrade.php, pasando 2008080100 como el argumento $oldversion.
Al final de este proceso, la tabla mdl_myqtype_options ahora tendrá tres columnas, col1, col2 y Newcol; y la fila ('qtype_myqtype', 'version') de la tabla mdl_config_plugins contendrán 2008080200.
Usuario instala la versión 2008080200 de myqtype en una instalación limpia Moodle
Para empezar, no existe mdl_myqtype_options , y no habrá una fila ('qtype_myqtype', 'version') en la tabla mdl_config_plugins.
- El usuario descomprimirá la versión 2008080200 de myqtype.zip en la carpeta question/type.
- El usuario visitará la página de notificaciones de administrador.
- Esto hará que Moodle busque plugings para actualizar. Se dará cuenta de que el código para el plugin qtype_myqtype está presente, pero no hay rastro de ella en la base de datos, por lo que instalará el plugin desde el archivo install.xml .
Al final de este proceso, la tabla mdl_myqtype_options existirá con tres columnas col1, col2 y newcol; y la fila ('qtype_myqtype', 'version') de la tabla mdl_config_plugins contendrá 2008080200 .
Restricciones de actualización de código
Dentro de una actualización, existen restricciones en las funciones que su código debe llamar, porque el sistema no se ha actualizado completamente .
- Todo el código de actualización puede utilizar la API de base de base de datos ($DB->... functions).
- En un plugin, la actualización no debería llamar funciones del plugin. ( Por ejemplo , si su plugin tiene una función que cambia la configuración de rana a 'verde', y necesita hacer esto durante la actualización, entonces usted no debe llamar a esta función; en su lugar, actualice manualmente las filas de base de datos para que la configuración de ranas se vuelven verdes.) Sin embargo, deberia llamar a funciones básicas en lugar de hacer cambios a bajo nivel en la base de datos.
- Al nivel del core, el código de actualización ni siquiera debería llamar funciones de bajo nivel. (Por ejemplo, si es necesario agregar un evento al calendario, esto se debe hacer mediante la inserción en una tabla de base de datos en lugar de llamar a una función para agregar el evento.)
La razón de esto es el estado del sistema durante la actualización.
Durante la actualización del núcleo el estado es el siguiente :
- Los datos del núcleo: Viejo.
- Los datos del Plugin : Viejo.
Las funciones del núcleo esperan que los datos esten en estado Actual, por lo que no es seguro llamarlos.
Durante la actualización de un plugin el estado es el siguiente:
- Los datos del núcleo. Actual. (Debido a que se ejecuta la actualización del núcleo antes que la del Plugin.)
- Los datos del Plugin : Viejo.
Las funciones del núcleo son ahora seguras para llamar porque los datos de la base están en el estado Actual . Pero las funciones del plugin, que esperan que los datos estén en el estado Actual , no son seguros.
Resumen
La primera vez que un usuario instala cualquier versión de su plugin, el archivo install.xml se utilizará para crear todas las tablas de base de datos necesarias. Por lo tanto install.xml siempre debe contener la definición de la estructura de base de datos actualizada. Moodle reconoce esta situación porque hay un archivo en el disco version.php, pero no hay ninguna entrada (plugintype_pluginname, version) en la tabla mdl_config_plugins.
Si el usuario ya tuviera una versión del plug-in instalado, y luego actualiza a una nueva versión, Moodle detectará esto porque el archivo version.php contendrá un número de versión más reciente que la entrada (plugintype_pluginname, version) en la tabla mdl_config_plugins. En este caso, Moodle ejecutará el código en el archivo upgrade.php, pasando el número de la versión antigua, así las partes correctas de la actualización pueden ejecutarse, controlada por el bloque de código if ($oldversion < XXXXXXXXXX).
El contenido de los archivos install.xml y upgrade.php deben ser generadas usando el editor de XMLDB .
Ver también
Este documento en Inglés está en https://docs.moodle.org/dev/Upgrade_API
