El blog de Javier Aranda

¿Qué es mongoDB?

Es una base de datos orientada a documentos de código abierto escrita en C++. A diferencia de otros sistemas de gestión de bases de datos, mongoDB no sigue el modelo relacional. La base de datos gestiona colecciones de documentos en objetos JSON. Está orientada a la web 2.0, la nube y las configuraciones de varios servidores de bases de datos. En la entrada Más allá de las bases de datos relacionales hablamos de la utilidad de este tipo de bases de datos.

Más información:

• http://en.wikipedia.org/wiki/MongoDB
• http://en.wikipedia.org/wiki/Document-oriented_database
• http://www.mongodb.org

Descargando e instalando mongoDB

Existen dos formas de realizar este proceso: podemos descargar el código fuente y compilarlo o bajar directamente los binarios. En este artículo optaremos por lo segundo por la facilidad y comodidad.

En la sección de descargas de la web de mongodb tenemos varias opciones, aunque las que nos interesa es la correspondiente a la versión 1.0.0 para Linux 32 bits (el que use 64 bits deberá escoger su opción). Tras la descarga, tendremos un archivo tar.gz que descomprimiremos con los comandos habituales:

cd Escritorio
tar -zxvf mongodb-linux-i686-1.0.0.tgz
cd mongodb-linux-i686-1.0.0

Si observamos el contenido del directorio vemos que se organiza en los subdirectorios bin, include y lib. En principio ya podríamos ejecutar mongodb desde ese directorio, pero por cuestiones de orden y claridad, copiaremos el contenido de esas subcarpetas en los directorios de igual nombre bajo /usr/local, operación para la que necesitamos adquirir permisos de root.

sudo -s
mv bin/* /usr/local/bin
mv include/* /usr/local/include
mv lib/* /usr/local/lib

De aquí en adelante asumiremos que estamos logueados en la terminal como root. Como ya tenemos los archivos donde nos interesan, podemos eliminar la carpeta descomprimida y el archivo descargado:

cd ../
rm -fr mongodb-linux-i686-1.0.0 mongodb-linux-i686-1.0.0.tgz

Configuración inicial

Antes de iniciar el demonio de mongodb es necesario crear una serie de directorios de trabajo, ya que al no instalarse, estos directorios no se crean. El más fundamental será el directorio donde el gestor almacenará las estructuras necesarias para almacenar en el disco duro los datos. Por defecto la carpeta es /data/db pero en este tutorial guardaremos los datos bajo /var/lib/mongodb (mysql por ejemplo también guarda los datos bajo /var/lib). Para ello creamos el directorio:

mkdir /var/lib/mongodb

Este directorio es propiedad de root. En este tutorial el demonio mongod se ejecutará bajo el usuario root. Podríamos ejecutarlo bajo otro usuario existente o crear uno específico para ello, tras lo que podríamos cambiar la propiedad del directorio de los datos por la del usuario usado por mongod.

El demonio puede configurarse mediante una serie de parámetros (ejecutar mongod –help para una lista) pasados al ejecutable del demonio, pero esta forma es un poco sucia y puede exponer ciertas configuraciones a la vista de cualquier usuario del sistema que explore la lista de procesos. Por ello, mongodb permite ser llamado especificándole la ruta a un archivo de configuración (de tipo conf). Ya que existe esa posibilidad, nosotros la vamos a hacer de esa forma. Para ello creamos un directorio bajo /etc llamado mongodb:

mkdir /etc/mongodb

Y con cualquier editor creamos el archivo mongodb.conf y le asignamos el contenido:

nano /etc/mongodb/mongodb.conf

# Config file for MongoDB

dbpath = /var/lib/mongodb

Como puede observarse, la directiva de configuración dbpath (que podía fijarse como parámetro del demonio) se usa de forma análoga en el archivo de configuración, especificándole a la aplicación dónde se encuentra el directorio con los datos. Existen directivas que no reciben argumentos, por ejemplo –auth no requiere nada a continuación. En estos casos, en el archivo de configuración deberemos igualarlo a true. Continuando con el ejemplo, –auth quedaría como auth = true. Por el momento no usaremos más directivas. En la web oficial existe un apartado dedicado a cada parámetro que podemos usar para configurar mongodb.

Iniciando el demonio

Para ejecutar el demonio escribiremos (le indicamos la ruta al archivo de configuración con -f):

mongod -f /etc/mongodb/mongodb.conf

Y si todo va bien, obtendremos algo como esto:

Tue Oct 13 21:47:02 Mongo DB : starting : pid = 16139 port = 27017 dbpath = /var/lib/mongodb master = 0 slave = 0  32-bit 

** NOTE: when using MongoDB 32 bit, you are limited to about 2 gigabytes of data
**       see http://blog.mongodb.org/post/137788967/32-bit-limitations for more

Tue Oct 13 21:47:02 db version v1.0.0, pdfile version 4.4
Tue Oct 13 21:47:02 git version: afe21e02c11f9a923ab1c95edf6fdd95b9a4a51e
Tue Oct 13 21:47:02 sys info: Linux domU-12-31-39-01-70-B4 2.6.21.7-2.fc8xen #1 SMP Fri Feb 15 12:39:36 EST 2008 i686
Tue Oct 13 21:47:02 waiting for connections on port 27017
Tue Oct 13 21:47:02 web admin interface listening on port 28017

Tras esta operación ya tenemos al demonio listo para atender nuestras peticiones.

Instalar el driver para PHP

Para poder instalar el driver de mongodb para php debemos tener instalado el paquete PEAR y la versión de desarrollo de php. Si no lo tenemos instalado, sólo tenemos que ejecutar:

apt-get install php-pear php5-dev

Y para instalar el driver:

pecl install mongo

Configurar PHP

El siguiente paso y último de la instalación y configuración consiste en indicarle a php que debe cargar la nueva extensión que contiene el driver en sí. Para ello creamos el siguiente archivo:

nano /etc/php5/conf.d/mongodb.ini

Y le asignamos la carga del módulo y sus directivas de configuración:

extension=mongo.so

[mongo]
; If the driver should reconnect to mongo
mongo.auto_reconnect = true

; Whether to allow persistent connections
mongo.allow_persistent = On

; Maximum number of persistent connections (-1 means unlimited)
mongo.max_persistent = -1

; Maximum number of links (persistent and non-persistent, -1 means unlimited)
mongo.max_connections = -1

; Default host for mongo connection
mongo.default_host = www.example.com

; Default port for mongo database
mongo.default_port = 42

; When saving files to the database, size of chunks to split them into
mongo.chunk_size = 1024

; Specify an alternate character to $ to use for special db functions ($set, $push, $exists, etc.)
mongo.cmd = "$"

Tras esta operación debemos reiniciar Apache para que PHP cargue de nuevo la configuración y los módulos (sólo si trabajamos con mod_php).

/etc/init.d/apache2 restart

Si ejecutamos un phpinfo() observamos que la extensión se ha cargado perfectamente.

Para completar los archivos necesarios dentro del directorio db, en esta entrada aprenderemos a especificar las capacidades del módulo y el archivo de actualización por si el módulo que instalamos fuese una versión superior a una que ya existiese.

Definiendo las capacidades

Moodle posee un sistema de capacidades, una especie de sistema de permisos que nos permitirán definir acciones y decidir qué usuarios pueden ejecutarlas. Esto nos resultará especialmente útil para definir acciones de administración o que sólo deban ser ejecutadas por un role de usuario (alumno, profesor, administrador, etc). Estas accionen deben definirse en un archivo llamado access.php que se encuentra bajo el directorio db. Cuando instalamos el módulo, moodle lee este archivo y copia su información en la base de datos, por lo que si lo modificamos, tendremos que aumentar el valor de la versión del módulo (esto lo veremos más adelante) para que moodle vuelva a leerlo y almacenar sus nuevos valores. Veamos su estructura:

access.php

$mod_modsms_capabilities = array(

    //capacidad de enviar mensajes en el tablon
    'mod/modsms:participate' => array(

        'riskbitmask' => RISK_SPAM,

        'captype' => 'write',
        'contextlevel' => CONTEXT_MODULE,
        'legacy' => array(
            'student' => CAP_ALLOW
        )
    ),

    //capacidad de administrar el tablón
    'mod/modsms:manage' => array(

        'riskbitmask' => RISK_SPAM,

        'captype' => 'write',
        'contextlevel' => CONTEXT_MODULE,
        'legacy' => array(
            'teacher' => CAP_ALLOW,
            'editingteacher' => CAP_ALLOW,
            'admin' => CAP_ALLOW
        )
    )
);

Como podemos observar en el código anterior, la variable ($mod_modsms_capabilities) incluye el nombre del módulo para diferenciarla de la que pueda existir en otros módulos. Internamente, está formada por un array de tantos elementos como capacidades queramos definir, en la forma nombre_de_la_capacidad => array_de_configuración_de_esa_capacidad. Entre esas configuraciones, caben destacar:

captype: tipo de la capacidad. El valor write indica que la capacidad será usada para la entrada de datos o el cambio de cosas. El valor read por contra se usa para la salida de datos, para mostrar cosas.

legacy: este elemento es a su vez un array que permite indicar que tipo de role posee autorización para realizar la acción indicada en la capacidad.

Para más información sobre las capacidades se puede consultar la documentación oficial en inglés:

• http://docs.moodle.org/en/Development:NEWMODULE_Adding_capabilities
• http://docs.moodle.org/en/Development:Roles
• http://docs.moodle.org/en/Development:Hardening_new_Roles_system

Viendo el código podemos observar que se han definido dos capacidades: la de enviar mensajes al tablón y la de administrarlo. Para la primera, que es de tipo escritura (ya que el usuario envía datos), sólo autorizamos a que sea el usuario cuyo rol es estudiante a que pueda escribir mensajes. En la segunda, de tipo escritura, los roles que pueden hacer uso de esta capacidad son los de profesor (ambos tipos) y administrador. Se podría haber definido un tercer rol de tipo lectura con la capacidad de leer los mensajes, pero como los mensajes pueden ser vistos por cualquier tipo de usuario, no se ha considerado.

Actualizando versiones anteriores del módulo

Si nuestro módulo no es de nueva creación sino que se trata de una versión posterior, es posible que necesitemos realizar actualizaciones en la base de datos existente (ya que al existir una en el sistema no se sobreescriben los datos con el contenido del archivo install.xml visto en entradas anteriores) al necesitar esta nueva versión de campos adicionales por ejemplo. La forma de realizar esto es mediante el archivo upgrade.php que se encuentra también bajo el directorio db. Este archivo contiene en su interior una función llamada xmldb_nombremodulo_upgrade, la cual será invocada por moodle en la instalación del módulo y pasándole como parámetro la versión del módulo instalado actualmente.

upgrade.php

function xmldb_modsms_upgrade($oldversion=0)
{
    global $CFG, $THEME, $db;

    $result = true;

    /*
    And upgrade begins here. For each one, you'll need one
    block of code similar to the next one. Please, delete
    this comment lines once this file start handling proper
    upgrade code.

    if ($result && $oldversion < YYYYMMDD00) { //New version in version.php
        $result = result of "/lib/ddllib.php" function calls
    }
    */

    return $result;
}

Es en esta función donde deberemos implementar las diferentes consultas a la base de datos para transformar los datos antiguos al nuevo formato. En nuestro caso, al ser la primera versión del módulo, no la necesitamos, por lo que devolvemos true indicando que todo ha salido correctamente.

La versión del módulo y otros datos de interés

En los apartados anteriores vimos que resulta necesario para ciertas operaciones conocer el número de versión del módulo instalado actualmente. La forma que tiene moodle de saberlo es mediante el contenido del archivo version.php situado en la raíz del módulo. El contenido del archivo es el siguiente:

version.php

//versión del módulo
$module->version  = 2009101200;

//versión de moodle mínima para instalarse
$module->requires = 2007101509;

//tiempo cada cual debe ser llamada la función de cron del módulo
$module->cron     = 0;

La primera de ellas le indica a moodle la versión de este módulo. La segunda indica la versión mínima de moodle sobre la que corre este módulo. Las versiones siguen la forma AAAAMMDDXY.YY siendo YYYYMMDD la fecha de lanzamiento de la rama (1.9 en el caso de la versión de moodle), X número de release 1.9.[0,1,2,3...] e Y.YY pequeños incrementos de las versiones entre releases. El último parámetro nos permite establecer cada cuanto tiempo moodle debe llamar a la función de cron que se encuentra dentro de lib.php como veremos en futuras entregas de este tutorial. Si se pone a cero nunca se llamará a la función (por que no nos haga falta en nuestro módulo).

Tras un periodo de exámenes, continúo escribiendo este tutorial.

Descripción de modsms

Como ya se ha comentado en entradas anteriores, vamos a realizar un módulo de actividad muy sencillo llamado modsms que nos permitirá tratar todos los aspectos básicos a tener en cuenta a la hora de desarrollar nuestro módulo. Este módulo hará uso de una base de datos para almacenar una serie de mensajes breves escritos por los alumnos (como un chat aunque sin una actualización en tiempo real) que responden a una pregunta del profesor. El diseño relacional de la base de datos queda de la siguiente forma:

Esquema Entidad-Relación modSMS

De color azul tenemos las tablas creadas por este módulo, y de color rosa las ya existentes en moodle pero que son referenciadas desde las nuestras.

Definición de las tablas: db/install.xml

El primer archivo que vamos a crear en nuestro módulo es el archivo de definición de las tablas que se usarán en nuestro módulo y que se crearán cuando lo activemos/instalemos. Este archivo es necesario crearlo aunque no usemos en nuestro módulo nada de las bases de datos, pero, como veremos más adelante, siempre resulta necesario crear una tabla con el nombre de nuestro módulo donde se almacenarán las distintas instancias de nuestro módulo en los cursos.

Este archivo contiene una definición de las tablas en un formato XMLDB modificado por moodle a su manera, por lo que si usamos algún editor existente que soporte ese xml deberemos prestar atención a los cambios. Para facilitarnos esa tarea, el propio moodle lleva incorporado un editor web que es el que usaremos para crear el esquema. Para ello, crearemos la estructura inicial del módulo creando la carpeta modsms bajo raiz-de-moodle/mood, dentro de ella la carpeta db y dentro de esta un archivo de texto llamado install.xml.

El primer paso es dotar de contenido a este archivo con una estructura básica para que el editor de moodle pueda reconocerlo y editarlo:

Como puede observarse, el xml consta de dos partes: la definición de tablas (tables) y la definición de consultas (statements). Por ahora nos olvidaremos de esta última parte y nos centraremos en la primera, la cual define la tabla principal del módulo (modsms) con un único campo (id) que identifica cada instancia de nuestro módulo de forma única.

Ahora entramos como administrador en moodle y en el menú de administración seleccionamos Miscelánea > XMLDB Editor. Una vez estemos en la página, buscamos la línea mod/modsms/db y pulsamos sobre Load, lo cual cargará nuestro archivo xml para su edición. Una vez cargado, en la misma línea tendremos activada la opción de editar (Edit), y pulsando sobre ella accederemos a la interfaz de edición del xmldb.

Vista de la interfaz de edición de XMLDB

Creando la estructura de las tablas

Como puede apreciarse en la página de edición, disponemos ya de una tabla creada, llamada modsms, que se corresponde con la única tabla obligatoria para un módulo de actividad en moodle. En esta tabla se creará un registro/fila/tupla por cada una de las instancias de nuestra actividad en cualquier curso de todo moodle. Y… ¿qué es una instancia? Pues es simplemente una actividad que insertamos en algún curso, que se diferencia de otras instancias de la misma actividad por un número de identificación único que se guarda en la tabla como el campo id. Esta tabla debe contener obligatoriamente tres campos: id, course y name, que identifican de forma unica cada instancia, hace referencia al curso donde está y el nombre que tiene, respectivamente. Para editar la tabla solamente pulsaremos sobre el enlace [Edit] que se encuentra junto al nombre de la tabla bajo la sección Tables.

Como se observa, la tabla ya contiene el campo id mencionado anteriormente. Ahora es el turno de añadir los demás campos que necesitamos en base al diseño realizado arriba. Para añadir un nuevo campo, sólo hay que pulsar sobre [New Field] y rellenar los datos del campo en la siguiente página. En el caso del campo course, el formulario lucirá el siguiente aspecto:

Editando el campo course

Repetiremos este proceso hasta completar todos los campos de la tabla. Es importante que todos los campos tengan la restricción de no nulo (NOT NULL), ya que ninguno debe ser nulo para el correcto funcionamiento del módulo. Una vez creados todos los campos, el siguiente paso es aplicar las restricciones y las relaciones a los campos que lo requieran. En esta tabla, deberemos reflejar que el campo course es una clave foránea (hace referencia a) del campo id en la tabla course. Para informar de esto a la base de datos, pulsamos sobre [New Key] y rellenamos los datos:

Editando las restricciones de clave foranea

Usando el enlace [Back] volvemos hacia atrás hasta llegar a la página que muestra la lista de tablas creadas (solo hay una por el momento). Si pulsamos sobre el enlace [New Table] nos mostrará la interfaz de creación de tablas dónde sólo hay que darle un nombre y el comentario es opcional, y la aplicación se encargará de crear el campo identificativo por defecto (id). En este paso creamos la tabla de nombre modsms_messages donde guardar los mensajes escritos por los alumnos. Y repetimos los pasos anteriores para dotar de contenido a esta nueva tabla.

Guardando el nuevo archivo

Por razones que desconozco, pese a contar el archivo con permisos 777 en linux, resulta imposible guardarlo desde moodle con la opción [Save] que aparece junto a la ruta en la lista de archivos editables de la interfaz de edición de xmldb. Por ello, la única manera de guardar los cambios es, estando en la interfaz de edición, pulsar sobre [View Edited] con el botón derecho del ratón y darle a Guardar como…, sustituyendo el antiguo archivo por este nuevo.

Cuando todo esté terminado, el contenido del archivo install.xml debe ser muy parecido a este:

Nota sobre los nombres de tablas y campos

En moodle, el nombre de la tabla principal de un módulo debe llamarse igual que este, y las demás tablas que necesitemos deben empezar por el nombre del módulo. En nuestro caso, el módulo se llama modsms, su tabla principal modsms y la otra que necesitamos modsms_messages.

Si en una tabla hacemos referencia al campo de otra tabla, este campo deberá llamarse de la forma nombredelatablanombredelcampo. Así, para hacer referencia al campo id de la tabla user, en nuestra tabla modsms_messages hemos creado un campo llamado userid.

Todos estos requerimientos pueden consultarse en la documentación en inglés sobre las bases de datos en moodle.

Estructura de archivos de un módulo

Para que moodle reconozca nuestro módulo de actividad este debe seguir una estructura de archivos (algunos necesarios y otros opcionales). Para ello, a partir de este momento vamos a considerar que nuestro módulo de prueba va a llamarse “modsms“. Por tanto la estructura sería:

• / – raíz de moodle.
• /mod – carpeta de módulos.
  • /modsms – carpeta raíz de nuestro módulo. Aquí dentro irán todos nuestros archivos y carpetas.
    • /db – carpeta con datos a introducir en la base de datos durante la instalación/actualización del módulo.
      • /access.php – contiene las capacidades/permisos del módulo.
      • /install.xml – esquema de la base de datos en xmldb para la instalación del módulo.
      • /upgrade.php – procedimientos de actualización del módulo.
    • /icon.gif – icono de la actividad que se muestra en el curso (entre otros sitios).
    • /index.php – muestra la lista de instancias de actividades de nuestro módulo que hay en el curso.
    • /lib.php – funciones requeridas por moodle para comunicarse con nuestro módulo.
    • /locallib.php – funciones propias que necesitemos para nuestro módulo.
    • /mod_form.php – formulario de configuración de la actividad al ser creada o editada.
    • /version.php – información sobre versiones relacionadas con el módulo.
    • /view.php – página de inicio de la actividad (cuando entra en la actividad un alumno por ejemplo).
    • /styles.php – definición de estilos css para nuestro módulo.
    • /backuplib.php – funciones para realizar la copia de seguridad del módulo.
    • /restorelib.php – funciones para realizar el restablecimiento de una copia de seguridad del módulo.
    • /lang – directorio de idiomas
      • /es_es_utf8 – directorio de idioma correspondiente al español de España versión UTF8.
        • /modsms.php – archivo con las cadenas usadas en el módulo en el idioma de arriba.
          • /help – carpeta con los archivos de ayuda.
            • /modsms – ayuda de este módulo.
              • index.html – índice con enlaces a los demás archivos de ayuda de este módulo.
              • mods.html – información general de nuestro módulo.
              • miayuda5.html – archivo de ayuda propio con ayuda sobre algo de nuestro módulo.
    • /miarchivo.php – también podemos crear tantos archivos (páginas) como necesitemos.

Los archivos en negrita son los archivos “obligatorios” que deberemos tener en nuestro módulo, siendo el resto opcionales.

Referencias básicas a la hora de desarrollar un módulo

Dado que como comentábamos en la anterior entrega de este tutorial la documentación de moodle es bastante escasa, cuando estemos desarrollando nuestro módulo o mirando cómo están hechos los otros (algo muy recomendable por otra parte) nos encontraremos con funciones que no sabemos qué hacen o que parámetros se le pueden pasar. Para ello moodle posee dos webs donde tiene subido la documentación generada por phpDocumentor y PHPXref que nos van a ser muy útiles para lo anterior:

• Moodle phpDocs
• Moodle PHPXref

Una vez conocida la estructura de archivos de los módulos, en la siguiente entrega comenzaremos de lleno a programar nuestro módulo modsms.