Estándares de desarrollo PrestaShop
Resumen
PHP
Nombres de variables
- Correspondiente a la información de las bases de datos: $my_var
- Correspondiente al algoritmo: $my_var
- La visibilidad de una variable miembro no afecta su nombre: private $my_var
Asignaciones
- Debe haber un espacio entre la variable y los operadores:
$my_var = 17; $a = $b;
Operadores
- "+", "-", "*", "/", "=" y cualquier combinación de ellos (ej. "/=") necesitan un espacio entre
miembros de la izquierda y la derecha$a + 17; $result = $b / 2; $i += 34;
- "." no llevan espacio entre los miembros de la izquierda y la derecha
echo $a.$b; $c = $d.$this->foo();
Recomendación
Por motivos de rendimiento, no exceda el uso de la concatenación.
- ".=" necesita un espacio entre los miembros de la izquierda y la derecha
$a .= 'Debug';
Declaraciones
- if, elseif, while, for: deben presentar un espacio entre la palabra clave if y el paréntesis
if (<condition>) while (<condition>)
- Cuando una combinación de if y else else es utilizada y si ambas deben ofrecer un valor, el else debe ser evitado.
if (<condition>) return false; return true;
Recomendación
Le recomendamos un resultado por método / función
- Cuando un método / función ofrece un valor booleano y el valor actual del método / función depende de ello, la declaración if debe ser evitada
public aFirstMethod() { return $this->aSecondMethod(); }
- Las pruebas deben ser agrupadas por "entidad"
if ($price AND !empty($price)) [...] if (!Validate::$myObject OR $myObject->id === NULL) [...]
Visibilidad
- La visibilidad debe definirse en cada momento, incluso cuando se trata de un método público.
- El orden de las propiedades del método debe ser: visibility static function name()
private static function foo()
Nombres de Método / Función
- Los nombres del método y la función comienzan siempre con un carácter en minúscula y cada una de las palabras siguientes deben comenzar con un carácter en mayúsculas (CamelCase)
public function myExempleMethodWithALotOfWordsInItsName()
- Los corchetes que se presentan en el código del método tienen que ser precedidos por un retorno
public function myMethod($arg1, $arg2) { [...] }
- Los nombres de los métodos y las funciones deben ser nombres explícitos, por lo tanto nombres de función como "b()" o "ef()" están completamente prohibidos.
Excepciones
Las únicas excepciones son la función de traducción llamada "l()" y las funciones de depuración "p()", "d()".
Enumeración
Las comas deben estar seguidas (y sólo seguidas) por un espacio.
protected function myProtectedMethod($arg1, $arg2, $arg3 = null)
Objetos / Clases
- El nombre del objeto debe colocarse en singular
class Customer
- El nombre de la clase debe seguir el modelo CamelCase, excepto que la primera letra sea mayúscula
class MyBeautifulClass
Definiciones
- Los nombres de las definiciones deben ser ingresados en mayúsculas
- Los nombres de las definiciones deben contar con el prefijo "PS_" dentro del núcleo y el módulo
define('PS_DEBUG', 1); define('PS_MODULE_NAME_DEBUG', 1);
- Los nombres de las definiciones no permiten caracteres alfabéticos. Excepto “_”.
Palabras claves
Todas las palabras clave deben colocarse en minúsculas
ej. as, case, if, echo, null
Constantes
Las constantes deben estar en mayúsculas, excepto "verdadero" y "falso" y "nulo", que debe estar en minúsculas
ej. "ENT_NOQUOTE", "true"
Variables de configuración
Las variables de configuración siguen las mismas reglas que las definiciones
Cadenas
Las Cadenas deben ir entre comillas simples, nunca dobles
echo 'Debug'; $myObj->name = 'Hello '.$name;
Comentarios
- Dentro de las funciones y métodos, sólo la etiqueta "//" de comentario es permitida
- Después de la etiqueta "//" de comentario, un espacio “// Comment“ es necesario
// My great comment
- La etiqueta "//" de comentario es permitida al final de una línea de código
$a = 17 + 23; // A comment inside my exemple function
- Funciones y métodos externos, sólo las etiquetas "/" y "/" de comentario son permitidas
/* This method is required for compatibility issues */ public function foo() { // Some code explanation right here [...] }
- Comentario PHP Doc Element es necesario antes de las declaraciones de método
/** * Return field value if possible (both classical and multilingual fields) * * Case 1 : Return value if present in $_POST / $_GET * Case 2 : Return object value * * @param object $obj Object * @param string $key Field name * @param integer $id_lang Language id (optional) * @return string */ protected function getFieldValue($obj, $key, $id_lang = NULL)
Para más información
Para más información acerca de la regla PHP Doc: vea este enlace útil
Devolución de valores
- Las declaraciones de devolución no necesitan paréntesis, excepto cuando se trata de una expresión compuesta
return $result; return ($a + $b); return (a() - b()); return true;
- Desarmar una función
return;
Llamada
La función de llamada precedida por una "@" está prohibida pero tenga cuidado con la llamada a la función / método con login / contraseña o ruta de argumentos.
myfunction() // En el siguiente ejemplo colocamos una @ por motivos de seguridad @mysql_connect([...]);
Etiquetas
- Una línea en blanco debe dejarse después de la etiqueta de apertura de PHP
<?php require_once('my_file.inc.php');
- La etiqueta final de PHP está prohibida
Indentación
- El carácter de tabulación ("\t") es el único caracter de indentación que se permite
- Cada nivel de indentación debe ser representado por un solo caracter de tabulación
function foo($a) { if ($a == null) return false; [...] }
Matriz
- La palabra clave de la matriz no debe ser seguida por un espacio
array(17, 23, 42);
- La indentación debe ser de la siguiente forma cuando muchos datos se encuentran dentro de una matriz:
$a = array( 36 => $b, $c => 'foo', $d => array(17, 23, 42), $e => array( 0 => 'zero', 1 => $one ) );
Bloque
Los corchetes están prohibidos cuando se define solamente una instrucción o una combinación de declaración
if (!$result) return false; for ($i = 0; $i < 17; $i++) if ($myArray[$i] == $value) $result[] = $myArray[$i]; else $failed++;
Seguridad
- Toda la información de los usuarios (ingresada por ellos) debe ser moldeada.
$data = Tools::getValue('name'); $myObject->street_number = (int)Tools::getValue('street_number');
- Todos los parámetros de método / función deben ser ingresados cuando son recibidos (con Array u Object).
public myMethod(Array $var1, $var2, Object $var3)
- Todos los demás parámetros, deben ser moldeados cada vez que se usen, pero no cuando
son enviados a otros métodos / funcionesprotected myProtectedMethod($id, $text, $price) { $this->id = (int)$id; $this->price = (float)$price; $this->callMethod($id, $price); }
Limitaciones
- Líneas de código fuente son limitadas a 120 caracteres
- Líneas de funciones y métodos están limitadas a 80 con buenas justificaciones.
Otros
- Está prohibido el uso de un ternario en otro ternario
- Recomendamos utilizar && y || en sus condiciones
- Por favor, no use los parámetros de referencia
SQL
Nombres de tablas
- Los nombres de tablas deben comenzar con el prefijo de PrestaShop "DB_PREFIX"
[...] FROM `'. _DB_PREFIX_.'customer` [...]
- Los nombres de tablas deben tener el mismo nombre que el objeto que reflejan
por ejemplo "ps_cart" - Los nombres de tablas deben permanecer en singular
por ejemplo "ps_order" - Información de idioma debe ser almacenada en una tabla denominada exactamente como uno de los objetos y con el sufijo "_lang" ej. "ps_product_lang"
Consulta SQL
- Las palabras clave deben ser escritas en mayúsculas.
SELECT `firstname` FROM `'. _DB_PREFIX_.'customer`
- Las comillas inversas ("`") deben ser utilizadas alrededor de nombres de campo y tabla
SELECT p.`foo`, c.`bar` FROM `'. _DB_PREFIX_.'product` p, `'. _DB_PREFIX_.'customer` c
- Los alias de tablas deben ser realizados utilizando la primera letra de cada palabra y deben estar en minúsculas
SELECT p.`id_product`, pl.`name` FROM `'. _DB_PREFIX_.'product` p NATURAL JOIN `'. _DB_PREFIX_.'product_lang` pl
- Cuando ocurran conflictos entre los alias de tablas, el segundo carácter también debe ser tomado.
SELECT ca.`id_product`, cu.`firstname` FROM `'.DB_PREFIX.'cart` ca, `'. _DB_PREFIX_.'customer` cu
- La indentación se debe realizar para cada cláusula
$query = 'SELECT pl.`name` FROM `'.PS_DBP.'product_lang` pl WHERE pl.`id_product` = 17';
- Está prohibido realizar una combinación en la cláusula WHERE
Instalación del validador de código
Este es un breve tutorial sobre cómo instalar un validador de código en su PC y utilizarlo para validar sus archivos. El validador de código utiliza PHP CodeSniffer, el cual es un paquete de PEAR. El código estándar de PrestaShop fue creado específicamente para CodeSniffer y utiliza muchas reglas tomadas de las reglas existentes, agregándole reglas personalizadas con el fin de adaptarse mejor a nuestro proyecto.
Puede acceder a la regla del código PrestaShop utilizando SVN: http://dev.prestashop.com/svn/v1/branches/norm (debe realizar este paso antes de continuar con este tutorial)
Integración eclipse
Enlaces rápidos:
Si utiliza Eclipse, puede integrar la validación de código en el editor de texto usando un plugin, que es muy fácil de instalar.
La configuración del plugin también es muy simple. En la lista de paquetes disponibles, sólo seleccione PHP CodeSniffer y PEAR si aún no cuenta con ellos.
A continuación, tendrá que agregar el código estándar PrestaShop a las preferencias de Eclipse, para lograr esto tiene que dirijirse a "PHP Tools" y elegir el estándar PS que ha descargado anteriormente (vea el enlace arriba).
Consejo: si el archivo no es validado automáticamente, como debe ser, puede configurarlo en el menú "Preferences", "Validation". De lo contrario, haga clic derecho en la carpeta / archivo en la lista de archivos y seleccione "PHP Tools" en el menú contextual (el cual puede establecer como un acceso directo).
Línea de Comandos (Linux)
Puede instalar PHP CodeSniffer sin tener que utilizar Eclipse, utilizando la línea de comandos.
apt-get install php-pear pear install PHP_CodeSniffer svn co http://dev.prestashop.com/svn/v1/branches/norm /usr/share/php/PHP/CodeSniffer/Standards/Prestashop phpcs --config-set default_standard Prestashop
Utilización del programa
Para instalar el validador como un programa que puede lanzar desde la línea de comandos, siga estos pasos:
- Instalar PEAR: http://pear.php.net/
- Instalar PHP CodeSniffer en PEAR: http://pear.php.net/package/PHP_CodeSniffer
- Añadir la regla PrestaShop que ha descargado desde SVN antes, y colocarla en la carpeta "Standards" de PHP CodeSniffer.
Las distintas opciones para este comando están bien explicadas en su documentación. Por ahora, aquí está la manera fácil de ponerla en marcha:
$> phpcs --standard=/chemin/vers/norme/Prestashop /fichier/ou/dossier/a/valider/
Para mostrar sólo errores, no advertencias:
$> phpcs --standard=/chemin/vers/norme/Prestashop --warning-severity=99 /fichier/ou/dossier/a/valider/
Si ya ha instalado manualmente PHP CodeSniffer, el programa debe estar en la carpeta "scripts" de PEAR.
Usuarios de Windows: si bien el archivo phpcs.bat debe esta localizado en la carpeta "scripts", tal vez tenga que editarlo para que funcione correctamente (reemplazar las rutas con la suya):
path/to/php.exe \-d auto_apprend_file="" \-d auto_prepend_file{color} {color:#339966}\-d include_path="path/to/PEAR/" path/to/pear/scripts/phpcs %\*
Integración del programa para la consola de Eclipse (opcional)
- Haga clic en el botón "External tools" en la barra de iconos (una flecha verde que apunta a una carpeta roja pequeña).
- Haga clic en la pestaña "External tools configuration".
- Haga doble clic en "Program" con el fin de crear una configuración:
- Ubicación: ruta de acceso al programa de phpcs (o phpcs.bat para usuarios de Windows).
- Argumentos: los argumentos de la línea de comandos, por ejemplo --standard=Prestashop ${selected_resource_loc}