Tabla de contenidos
Table of Contents | ||
---|---|---|
|
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:
Code Block borderStyle solid $my_var = 17; $a = $b;
Operadores
"+", "-", "*", "/", "=" y cualquier combinación de ellos (ej. "/=") necesitan un espacio entre
miembros de la izquierda y la derechaCode Block borderStyle solid $a + 17; $result = $b / 2; $i += 34;
"." no llevan espacio entre los miembros de la izquierda y la derecha
Code Block borderStyle solid echo $a.$b; $c = $d.$this->foo();
Note title 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
Code Block borderStyle solid $a .= 'Debug';
Declaraciones
if, elseif, while, for:deben presentar un espacio entre la palabra clave if y el paréntesis
Code Block borderStyle solid 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.
Code Block borderStyle solid if (<condition>) return false; return true;
Note title 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
Code Block borderStyle solid public aFirstMethod() { return $this->aSecondMethod(); }
Las pruebas deben ser agrupadas por "entidad"
Code Block borderStyle solid 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()
Code Block borderStyle solid 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)
Code Block borderStyle solid public function myExempleMethodWithALotOfWordsInItsName()
Los corchetes que se presentan en el código del método tienen que ser precedidos por un retorno
Code Block borderStyle solid 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.
Info title 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.
Code Block | ||
---|---|---|
| ||
protected function myProtectedMethod($arg1, $arg2, $arg3 = null) |
Objetos / Clases
El nombre del objeto debe colocarse en singular
Code Block borderStyle solid class Customer
El nombre de la clase debe seguir el modelo CamelCase, excepto que la primera letra sea mayúscula
Code Block borderStyle solid 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
Code Block borderStyle solid 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
Code Block | ||
---|---|---|
| ||
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
Code Block borderStyle solid // My great comment
La etiqueta "//" de comentario es permitida al final de una línea de código
Code Block $a = 17 + 23; // A comment inside my exemple function
Funciones y métodos externos, sólo las etiquetas "/" y "/" de comentario son permitidas
Code Block borderStyle solid /* 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
Code Block borderStyle solid /** * 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)
Info title 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
Code Block borderStyle solid return $result; return ($a + $b); return (a() - b()); return true;
Desarmar una función
Code Block borderStyle solid 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.
Code Block | ||
---|---|---|
| ||
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
Code Block borderStyle solid <?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
Code Block borderStyle solid function foo($a) { if ($a == null) return false; [...] }
Matriz
La palabra clave de la matriz no debe ser seguida por un espacio
Code Block borderStyle solid array(17, 23, 42);
La indentación debe ser de la siguiente forma cuando muchos datos se encuentran dentro de una matriz:
Code Block borderStyle solid $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
Code Block | ||
---|---|---|
| ||
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.
Code Block borderStyle solid $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).
Code Block borderStyle solid 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 / funcionesCode Block borderStyle solid protected 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"
Code Block borderStyle solid [...] 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.
Code Block borderStyle solid SELECT `firstname` FROM `'. _DB_PREFIX_.'customer`
Las comillas inversas ("`") deben ser utilizadas alrededor de nombres de campo y tabla
Code Block borderStyle solid 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
Code Block borderStyle solid 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.
Code Block borderStyle solid 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
Code Block borderStyle solid $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://svn.prestashop.com/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.
Code Block |
---|
apt-get install php-pear pear install PHP_CodeSniffer svn co http://svn.prestashop.com/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:
Code Block |
---|
$> phpcs --standard=/chemin/vers/norme/Prestashop /fichier/ou/dossier/a/valider/ |
Para mostrar sólo errores, no advertencias:
Code Block |
---|
$> 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.
Note | ||
---|---|---|
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):
|
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}