Una guía de estilo de un lenguaje de programación es un conjunto de recomendaciones sobre la forma de dar formato a los programas. El interés de utilizar un estilo específico es facilitar la reutilización de código y la detección de errores. Existen muchos estilos de programación y no se puede decir que uno sea mejor que otro, pero sí que es conveniente adoptar algún estilo determinado y utilizarlo de forma consistente.
El estilo utilizado en estos apuntes y que se recomienda sigan los alumnos se basa:
PHP-FIG es un grupo creado en 2009 para crear guías de estilo para programadores de PHP. El objetivo inicial era crear guías para los aspectos más elementales y contaron con la participación de los autores de los frameworks PHP más populares, pero con el paso del tiempo se creó una estructura más formal y se han publicado guías para temas más complejos. Eso ha ido produciendo el abandono de algunos participantes significativos (Doctrine y Laravel en 2016, Symfony en 2018, Drupal en 2022, etc.).
La guía de estilo PER Coding Style sustituyó en junio de 2022 a la guía PSR-12, que a su vez había sustituido en agosto de 2019 a la guía PSR-2, publicada en mayo de 2012. La guía de estilo PER Coding Style pretende ser un documento en actualización continua (como la norma HTML del WHATWG). La primera versión es una copia de PSR-12 y la intención del PHP-FIG es por un lado mejorar la redacción de las reglas ya existentes y por otro añadir reglas para las novedades introducidas en el lenguaje PHP desde 2019.
PSR significa PHP Standard Recommendation y PER significa PHP Evolving Recommendation.
PEAR es el antiguo repositorio de bibliotecas para PHP que desde alrededor de 2015 se puede considerar obsoleto, ya que ha sido sustituido por Composer como herramienta de distribución de paquetes más popular.
Nota: En diciembre de 2018, PEAR sufrió una brecha de seguridad que no fue descubierta hasta enero de 2019 [referencia], lo que llevó al cierre inmediato del servidor de PEAR, aunque se volvió a abrir en febrero de 2019.
Nota: Existe una guía de estilo oficial de PHP, pero esta guía se refiere al código fuente de PHP, que está escrito en C, y está dirigida a los programadores que desarrollan el lenguaje, no se refiere a programas escritos en PHP.
En esta lección se comentan las recomendaciones de estilo más importantes. Cuando las reglas de estilo ...
En la lección Configuración recomendada para Visual Studio Code se explica cómo configurar y utilizar la extensión PHP CS Fixer, para formatear automáticamente de acuerdo con PER Coding Style (y con otros criterios adicionales que se comentan en la lección Configuración PHP CS Fixer).
En cursos anteriores, cuando en estos apuntes se recomendaba utilizar el editor Eclipse for PHP developers, en la lección de configuración de Eclipse se explicaba cómo configurar Eclipse PHP para formatear un programa de acuerdo con las recomendaciones de estilo PSR-2.
[PSR-1] Los archivos deben guardarse en formato UTF-8 sin BOM.
[PER Coding style] Los archivos deben utilizar el formato Unix (carácter LF como final de línea y al final de la última línea del archivo).
[PEAR] El código no debe generar errores o avisos cuando la directiva error_reporting tiene el valor E_STRICT.
[PSR-1] Los fragmentos PHP deben delimitarse con <?php ... ?> y no con <? ... ?>.
<?php
print "<p>Hola</p>";
?>
[PSR-1] También puede utilizarse <?= ... ?>.
<?= "<p>Hola</p>" ?>
Se aconseja utilizar // en los comentarios de una sola línea.
Los comentarios de varias líneas pueden delimitarse con /* ... */ o con varios //.
No se debe utilizar #.
Para facilitar la legibilidad, se aconseja colocar el cierre del comentario de varias líneas (*/) al principio de la línea (aunque puede ir precedido por espacios en blanco).
<?php
$nombre = "Fulano" // Nombre del individuo
?>
<?php
/* Datos personales:
Nombre, apellidos
*/
$nombre = "Fulano"
$apellidos = "Mengánez Zutánez";
?>
<?php
// Datos personales:
// Nombre, apellidos
$nombre = "Fulano"
$apellidos = "Mengánez Zutánez";
?>
[PEAR] Los programas deben incluir al principio del documento bloques de comentarios (docblocks).
<?php
/**
* Descripción breve
*
* Descripción extensa (opcional)
*
* @author Fulanito de Tal <fulanito@example.com>
* @copyright 2007 Fulanito de Tal
* @license http://www.fsf.org/licensing/licenses/gpl.txt GPL 2 or later
* @version 2007-02-06
* @link http://www.example.org
*/
?>
Por completar: mencionar JavaDoc y phpDocumentor.
No se deben superar los 85 caracteres por línea.
Al partir una línea, la segunda y siguientes líneas deben sangrarse 4 espacios. Si es posible, estas líneas deben empezar por un operador.
<?php
print "<p>Este texto es muy largo y no cabe en una sola línea, así que he "
. "partido el texto en dos líneas escribiendo el operador de concatenación "
. "(.) al principio de cada línea.</p>";
?>
Se aconseja no incluir más de una instrucción por línea.
[PEAR] Después de una coma, debe haber un espacio en blanco.
<?php
$var = foo($bar, $cel, $ona);
?>
[PEAR] Cualquier operador binario (por ejemplo: + - * / = . == && || ? : ) debe estar rodeado de espacios en blanco.
<?php
$cmTotal = 100000 * $km + 100 * $m + $cm;
?>
[PEAR] Los operadores unarios (por ejemplo: ! ++ --) deben unirse a su argumento sin espacios en blanco
<?php
$correcto = !$error;
?>
Se aconseja separar con líneas en blanco las diferentes partes de un programa (recogida de datos, mensajes de error, respuesta del programa, etc.).
Se aconseja delimitar las cadenas con comillas dobles (") en vez de con comillas simples ('). Se aconseja también que el código html generado por PHP incluya comillas dobles:
<?php
print "<p style=\"text-align: center\">Hola</p>";
?>
[PEAR] Los nombres de variables deben escribirse con el estilo camelCase, es decir empezar en minúscula y, si el nombre de la variable está formada por varias palabras, la primera letra de las palabras (menos la primera) debe escribirse en mayúscula
$nombre = "Fulano";
$nombreAlumno = "Mengano";
$nombreProfesor = "Zutano";
[PEAR] Si se definen varias variables, se deben alinear las igualdades con espacios en blanco para facilitar la legibilidad.
$nombre = "Fulano";
$nombreAlumno = "Mengano";
$nombreProfesor = "Zutano";
Nota: Este estilo está recomendado en la guía de estilo de PEAR y desaconsejado en la guía de estilo de Python.
Las constantes deben escribirse en mayúsculas y separando las palabras con guiones bajos (_).
Las constantes true, false y null debe escribirse en minúsculas.
Se debe utilizar un sangrado de 4 espacios y no utilizar tabuladores. En estructuras anidadas, se acumularán los sangrados.
<?php
if (condicion1) {
accion1;
} else {
accion2;
if (condicion3) {
accion3;
} else {
accion4;
}
}
?>
Las estructuras de control deben tener un espacio entre la palabra reservada y el paréntesis inicial, para distinguirlas de las funciones.
En los bloques de sentencias deben utilizarse siempre llaves, incluso cuando podrían omitirse (por ejemplo, cuando el bloque está formado por una única sentencia). La llave de apertura debe situarse al final de la línea y la llave de cierre debe situarse al principio de la línea.
Ejemplos de estructuras de control:
<?php
if (condicion1 || condicion2) {
accion1;
} elseif (condicion3 && condicion4) {
accion2;
} else {
accionpredeterminada;
}
?>
for (expresión_inicial; expresión_final; expresión_paso) {
bloque_de_sentencias
}
foreach ($matriz as $valor) {
bloque_de_sentencias
}
while (expresión) {
bloque_de_sentencias
}
do {
bloque_de_sentencias
} while (expresión)
<?php
switch (condicion) {
case 1:
accion1;
break;
case 2:
accion2;
break;
default:
accionpredeterminada;
break;
}
?>
No es necesario comparar las variables booleanas con los valores true o false, se aconseja utilizar directamente la variable o su negación.
En vez de:
if ($correcto == true) {
print "<p>Es correcto</p>";
}
if ($correcto == false) {
print "<p>No es correcto</p>";
}
se aconseja escribir:
if ($correcto) {
print "<p>Es correcto</p>";
}
if (!$correcto) {
print "<p>No es correcto</p>";
}
Al concatenar expresiones lógicas sencillas, no es necesario escribir cada expresión entre paréntesis.
if ($numero < 0 || $numero > 100) {
print "<p>El número no está en el intervalo [0, 100]</p>";
}
[PEAR] Las funciones deben declararse de acuerdo con el estilo "BSD/Allman":
<?php
function fooFuncion($arg1, $arg2 = "")
{
if (condicion) {
sentencia;
}
return $val;
}
?>
Los argumentos con valores predeterminados se deben colocar al final de la lista de argumentos.
Las funciones deben devolver algún valor.
No debe haber espacios entre el nombre de la función, el paréntesis inicial y el primer argumento. Debe haber espacios tras las comas que separen argumentos. No debe haber espacios entre el último argumento, el paréntesis final y el punto y coma.
<?php
$var = foo($bar, $cel, $ona);
?>
[PEAR] Para incluir bibliotecas cuya inclusión no depende de ninguna condición, debe utilizarse require_once y no deben utilizarse paréntesis alrededor del nombre de la biblioteca.
require_once "biblioteca.php";
...
Existen varias herramientas capaces de formatear código PHP de acuerdo con diferentes guías de estilo.
En estos apuntes se recomienda utilizar PHP CS Fixer en Visual Studio Code, como se comenta en la lección sobre la Configuración recomendada para Visual Studio Code.
Artículo que comenta y razona varias reglas de estilo: About Programming Style [copia en archive.org]