Guía de estilo para PHP

Introducción

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:

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.

Guía de estilo recomendada a los alumnos

Formatos de archivo

[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).

Configuración de php

[PEAR] El código no debe generar errores o avisos cuando la directiva error_reporting tiene el valor E_STRICT.

Delimitadores de bloque PHP

[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>" ?>

Comentarios

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";
?>

Bloques de comentario iniciales

[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.

Longitud de línea

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>";
?>

Instrucciones por línea

Se aconseja no incluir más de una instrucción por línea.

Espacios en blanco

[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;
?>

Líneas en blanco

Se aconseja separar con líneas en blanco las diferentes partes de un programa (recogida de datos, mensajes de error, respuesta del programa, etc.).

Comillas dobles y simples

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>";
?>

Nombres de variables

[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";

Alineación de definiciones de variables

[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.

Constantes

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.

Sangrado

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;
    }
}
?>

Estructuras de control

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;
}
?>

Expresiones lógicas

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>";
}

Definición de funciones

[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.

Llamadas a funciones

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);
?>

Bibliotecas

[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";
 ...
 

Herramientas

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.

Para saber más

Artículo que comenta y razona varias reglas de estilo: About Programming Style [copia en archive.org]