Lenguaje y Normas de Desarrollo

Volver al índice
Documentación desarrolladores

Page waiting for translation. To translate, create an account, go back and clic on "Modify". Page en attente de traduction. Pour traduire, créez un compte, revenez et cliquez sur "Modifier". Página a traducir. Para traducirla, cree una cuenta, vuelva a la página y haga clic en "editar". Pagina da tradurre. Per tradurla, crea un utente, torna indietro e clicca su "modifica". Página a aguardar por tradução. Para traduzir, crie uma conta, volte atrás e clique em "Modificar". Seite wartet auf Übersetzung. Um Übersetzung zu erstellen, richte einen Account ein, geh zurück und klicke auf "bearbeiten". 页面等待翻译。若要翻译本页，先创建一个帐户、登录并返回本页后单击“编辑”。

He aquí algunas normas sobre el lenguaje, la sintaxis y las norma de desarrollo en vigor para el proyecto Dolibarr:

Versiones

• Dolibarr debe funcionar con:

1. Todos los SO (Windows, Linux, MACOS...)
2. PHP 4.3 ó + (Debe funcionar sin ningún módulo PHP complementario, exceptuando los módulos de acceso a la base de datos).
3. Mysql 3.1 ó +

Normas PHP

• Dolibarr está escrito en PHP y soporta todas las versiones de PHP superiores a la 4.1. Todos los archivos deben de contener la extensión .php

• La llamada a las variables superglobales PHP deben pasar a través de los operadores dedicados $_GET, $_POST, $_COOKIES, $_SERVER, $_ENV.

Los otros operadores ($HTTP_SERVER_GET, ...) están siendo depreciados en el seno de PHP, no deben de ser ya utilizados. Por lo tanto, el código debe funcionar incluso cuando la opción register_long_arrays esté en off. Además de que el código debe funcionar cuando la opción de PHP register_globals esté en off (recomendado por PHP), también lo deberá hacer cuando la opción register_globals esté en on (por defecto en muchas instalaciones).

• Los smart tags PHP no són utilizados. Las secciones de código deben de empezar por <?php

• No se permite el uso de la variable PHP_SELF. Utilice en su lugar $_SERVER["PHP_SELF"]

• Cuando varias variables deben ser inicializadas con el mismo valor, utilize múltiples líneas

$var1=1;$var2=1;$var3=1;

en lugar de

$var1=$var2=$var3=1;

que es menos eficiente.

• las cadenas deben de ser encuadradas con comillas simples y las variables sacadas de la cadena.

print 'Mi texo muestra mi '.$variable.' !';

• Los comentarios deben seguir la sintaxis de C, es decir, una doble barra invertida para una línea de comentario y el uso de una barra con arterisco para abrir un bloque de varias líneas

/* Bloque de comentarios
 *
 * Fin el bloque
 */

$monobjet = new MonObjet($db);
$result=$monobjet->fetch($idobject);

for ($i = 1 , $i < 2 ; $i++)
{
  // comentario de una línea
  print $i;
}

• Los ficheros deben ser guardados en formato Unix (LF) y no en formato Windows (CR/LF). El formato Unix es compatible con los SO Unix, Windows, Mac, mientras que el formato de archivo de texto de Windows es problemático en algunos PHP en Unix.

Las funciones deben devolver 0 en caso de éxito, y un número <0 en caso de error. A día de hoy, muy pocas funciones cumplen este standard, pero es necesario.

Normas SQL

• ¡Los SELECT * están prohibidos! Cada Select deberá especificar la lista completa de los campos para recuperar. Esto permitirá evitar confusiones. Ejemplo:

SELECT field_a, field_b, field_c FROM table_1 WHERE field_d = '$id'

• En las consultas SQL, entrecomillaremos los campos, pero no los numéricos que contengan cantidades que se almacenen en los campos de tipo double o real. Los entrecomillados en los numéricos de tipo float se almacenan con un valor diferente. Por ejemplo 412.62 dentro del insert se guardara con el valor 412.61999512 en base si el campo es de tipo double(24,8). Y PHP sólo ve 412.61999512. Otras herramientas verán 412.62 dando la impresión de que no hay problemas. Y PHP tiene razón, hay un problema en base. Mediante la eliminación de las comillas en los numéricos, esto irá mejor.

Ejemplo:

Bien:INSERT INTO table_1 (field_txt, field_num) VALUES ('txt', 412.62)
Mal: INSERT INTO table_1 (field_txt, field_num) VALUES ('txt', '412.62')

Nota, el problema de los float es general y no sólamete en el acceso a la base de datos, está presente en todos los lenguajes cuando trabajamos sobre números reales, por lo que deberán ser limpiados por la función price2num con el segundo parámetro rellenado con: 'MU', 'MT' ó 'MS' según sea necesario. (véase la doc de la función)

• Dolibarr debe trabajar incluso con la opción strict de Mysql activa.

• las funciones NOW ó SYSDATE están prohibidas en las órdenes de SQL. Si se necesita indicar la fecha del momento en un campo, el valor debe provenir de PHP y no del motor de la base de datos. Esto además de ofrecer una mejor portabilidad del código, también permite una gestión correcta de la zona horaria.

Normas HTML

• Todos los atributos de las etiquetas HTML deben de estar *en minúscula* y entrecomillados con *doble comilla* (Norma xhtml)

• Los enlaces href deben de ser absolutos. para las páginas, basarse en la constante DOL_URL_ROOT que apunta a htdocs, para las imágenes basarse en la llamada de la función img_picto.

Por ejemplo:

print '<a href="'.DOL_URL_ROOT.'/monrep/mapage.php">'.img_picto('Texte alt','nompictopng','').'</a>';

• Javascript y la llamada a scripts java en las páginas php está fuera de las normas. Si de todas maneras se incluye código javascript, debe estar condicionado mediante el test "$conf->use_javascript"

if ($conf->use_javascript)
{
...  // El código PHP que genera el javascript va aquí
}

• Las ventanas emergentes no deben de ser utilizadas, exceptuando los tooltips (y quedan condicionados por el punto anterior).

• Los scripts externos son escritos en Perl si no pueden serlo en php, la utilización de otro lenguaje no está prohibido, pero debe de ser discutido priero en la lista de correo de desarrollo. El lenguaje debe de ser dominado al menos por 2 desarrolladores para asegurar el mantenimiento

Normas Dolibarr y plantillas de código

Plantillas de código

Para estandarizar el código y acelerar el desarrollo de nuevos componentes en Dolibarr, en la carpeta dev/skeletons encontraremos 4 plantillas de código preparadas.

• 1 que sirve de ejemplo de descriptor de módulo: myModule.class.php
• 1 que sirve de ejemplo de código para crear una nueva clase: skeleton_class.class.php
• 1 que sirve de ejemplo de código para crear una nueva página: skeleton_page.php
• 1 que sirve de ejemplo de código para crear una nuevo script a ejecutar en línea de comandos: skeleton_script.php

Úsenlas como ejemplo. Tenga en cuenta que estas plantillas también son utilizadas por el generador de código PHP que se describe en el capítulo de Desarrollo de módulos Dolibarr módulo para acelerar su desarrollo.

Las fechas y la Zona Horaria

Dolibarr es una aplicación multi-usuario y multi-ubicación. Por lo tanto, es necesario almacenar las fechas en el formato correcto. Para evitar problemas de conversión, deben aplicarse las siguientes reglas:

• Una fecha en memoria debe de estar en formato Timestamp GMT.
• Una fecha guardada en la base de datos contiene el Timestamp GMT en relación con la fecha que figura en la consulta en hora local del servidor PHP. No se trata de las fechas de actualización de la base de datos (campo tms en la base de datos).

Por lo tanto, el 1 de enero de 1970, a las 2 en Paris (TZ=+1) será almacenado en memora y será enviado a la base de datos con la cadena '19700101020000' (PHP convierte en hra de su TZ y la base de datos la deconvierte con su TZ que es la misma que la de PHP).

Los métodos select deben traducir los campos fecha al formato de cadenta TZ de la base ('19700101020000') mediante la llamada del método db->jdate para recuperar la información en memoria en formato Timestamp GMT. Y los métodos insert deben deben generar la petición convirtiendo la fecha en memoria conocida en variable, mediante el método db->idate (Ver ejemplos generados por la plantilla).

• Las actualizaciones automáticas de la base de datos (campo tms en la base) contienen el Timestamp GMT del momento en que se ha realizado la modificación. Los métodos select recuperan directamente este dato en memoria en formato Timestamp GMT.

Codificación UTF8/ISO

Dolibarr guarda la información de la manera siguiente:

• En la base de datos, los datos en UTF8 ó ISO. Esto depende del pagecode de la base de datos, y por lo tanto, de las opciones en la creación de esta base de datos. En todos los casos, el controlador de base de datos Dolibarr (dentro de /lib/database) lee e inserta por conversión desde y hacia UTF8.
• Los datos en memoria se guardan en UTF8 (instancias de objetos PHP).
• las páginas web mostradas en pantalla se encuentran en formato UTF8 (con versiones < 2.5.1, es el antiguo parámetro $character_set del fichero conf.php quien define el formato de salida).

Los números reales, las cantidades y los cálculos

Tanto en PHP como en otros lenguajes (Java, por ejemplo), los datos no enteros (float, real, double) no son fialbes. Pruebe a realizar por ejemplo

print 239.2 - 229.3 - 9.9;

No obtendrá 0, sino un número muy pequeño en potencia 10 negativo . Si obtiene cero, puede encontrar otros ejemplos que no funcionan. El problema de los float es general, una variable resultante del cálculo de números reales debe SISTEMATICAMENTE ser limpiada mediante la función price2num con el segundo parámetro rellenado con: 'MU', 'MT' ó 'MS' según el caso (ver doc de la función).

print price2num(239.2 - 229.3 - 9.9, 'MT');

Si no es un precio que se ajuste a los parámetros de MU, MT, MS debe utilizar la función round().

Création de tables

Ne pas créer de table à l'utilisation, c'est-à-dire à la première utilisation du module. Si vous créez un module qui utilise des tables qui ne sont pas intégrées en standard dans le code de Dolibarr, veillez à suivre le didacticiel Créer un module qui explique comment joindre des tables qui se créent à l'activation du module et non à son utilisation (voir plus haut).

Logs

Ajouter des traces dans votre code avec la fonction dolibarr_syslog($yourmessage, LOG_INFO|LOG_DEBUG|LOG_WARNING|LOG_ERR);

Répertoires de travail

Si vous avez besoin de créer un répertoire de travail, dans votre code, faites référence à ce répertoire par DOL_DATA_ROOT.'/monmodule'. Le répertoire peut être créé dans votre code à l'exécution par le code suivant:

$mymoduledir=DOL_DATA_ROOT.'/monmodule';
if (! is_dir($mymoduledir)) create_exdir($mymoduledir);

Si vous avez besoin d'un répertoire qui contiendra des données temporaires, ce répertoire doit être DOL_DATA_ROOT.'/monmodule/temp'

Programmation Objet

Motifs d'organisation du code

Martin Fowler a identifié 3 méthodes d'organisation du code appelées motifs:

• Le Transaction Script (Le code est linéraire en fonction d'une action utilisateur).

C'est le motif à l'ancienne utilisé dans les langages procéduraux. Inconvénient: Redondance du code. Nécessité de connaitre le modèle physique pour développer.

• Le Domain Model

C'est un concept possible depuis les langages objets. Ce sont les procédures métiers (qui doivent être identifiés avant) qui servent de bases pour les classes objets. Inconvénient: Motif complexe à maintenir.

• Le Table Module

Un intermédiaire entre les 2 précédents où l'on a une instance unique de classe par table de la base de données.

Comme le montre les squelettes de code (voir point précédent), Dolibarr se base sur le principe du Table Module.

Communication Logique métier - Données (ORM):

Il existe 3 modes de liaisons:

• Le Table And Row Data Gateway

C'est le plus simple. On crée une table par classe et chaque classe est un pont avec la table correspondante, voir une classe par ligne de table. Une instance de classe étant alors un enregistrement de la table. La classe ne contient que du code d'accès aux lignes ou colonnes de tables.

Exemple: C'est le mode mis en oeuvre quand on utilise certains Frameworks d'ORM comme iBatis (http://ibatis.apache.org/).

• Le Active Record

Identique au précédent, mais on se permet d'ajouter quelques fonctions métiers sur la classe, à conditions que ces fonctions soient propres à la table ou à l'enregistrement.

Exemple: C'est le mode choisi pour les développements Dolibarr et de nombreuses autres applications PHP qui ont leur propre framework et pratiques de développements.

• Le Data Mapper

Les classes représentent les entités du problème et non les données. Il faut donc doubler, tripler... ces classes avec des classes Mapper pour accéder aux données. Plus "puriste" sur le papier car plus proche du métier, ce mode a aussi l'inconvénient d'être plus complexe sur le plan pratique. Exemple: C'est le choix si on utilise le Framework d'ORM Propel (http://propel.phpdb.org/trac/). On le trouve donc sur des applications plus lourdes basées sur cet ORM entre autres.

Pour les développements Dolibarr, il est recommandé d'utiliser le mode de liaison Active Record qui offre les avantages d'un modèle proche du métier sans en avoir la complexité et sans trop masquer non plus la technique. C'est dans ce mode que le développement, la compréhension du code et la maintenance technique et/ou fonctionnelle semble la plus productive (ceci est toutefois un éternel débat entre les puristes et les pragmatiques, débat dans lequel personne ne peut vraiment avoir raison, car tout dépend des objectifs à atteindre).