PSR-12 es un estándard de codificación (coding standard) oficialmente aceptado por el PHP-FIG (Framework Interop Group). Su nombre completo es "Extended Coding Style Guide".

Proporciona un conjunto completo de reglas para formatear código PHP, incluyendo sangría, llaves, espaciado y más.

En esencia, es un conjunto de reglas muy específicas que dictan cómo debe formatearse el código PHP para que sea consistente, legible y mantenible. Es la evolución del popular PSR-2, incorporando características de las versiones modernas de PHP (como 7.x en adelante).

¿Por qué es importante? Las 3 razones clave:

1. Interoperabilidad: El objetivo principal del PHP-FIG es que el código de diferentes frameworks y librerías (Laravel, Symfony, Doctrine, etc.) "pueda hablar entre sí" y sea más fácil de integrar. Un estilo de código consistente es el primer paso.

2. Legibilidad y Mantenibilidad: Cuando todos los desarrolladores de un proyecto siguen las mismas reglas, el código parece que lo hubiera escrito una sola persona. Esto hace que sea mucho más fácil leer, entender y modificar el código, tanto para ti en el futuro como para cualquier otro desarrollador que se una al proyecto.

3. Adopción por la Comunidad: Se ha convertido en el estándard de facto para la comunidad PHP moderna. Herramientas modernas de análisis de código (como PHP CS Fixer, PHPCodeSniffer) lo tienen configurado por defecto.

Reglas más importantes y características de PSR-12 (con ejemplos)

Aquí hay algunas de las reglas más notables:

1. Límites de línea y sangría

• Límite de 120 caracteres por línea (una recomendación, no estricta como las 80 de PSR-2).

• Sangría de 4 espacios (nada de tabs).

2. Estructura de namespace y use

• Debe haber una línea en blanco después de la declaración de namespace.

• Debe haber una línea en blanco después del bloque de declaraciones use (importaciones).

<?php // La etiqueta de apertura debe estar sola en la línea

namespace App\Domains\Paciente\Models; // Declaración de namespace

use Illuminate\Database\Eloquent\Model; // Bloque de imports
use App\Domains\Paciente\ValueObjects\Direccion;

class Paciente extends Model // Línea en blanco después de los 'use'
{
    // ... código de la clase
}

3. Llaves y estructuras de control

• Las palabras clave de las estructuras de control (if, else, for, foreach, while, switch, try, catch) deben ir seguidas de un espacio.

• El cuerpo de la estructura debe estar entre llaves, incluso si es una sola línea (esto es clave y evita muchos errores).

// CORRECTO (según PSR-12)
if ($condition1) {
    // cuerpo del if
} elseif ($condition2) {
    // cuerpo del elseif
} else {
    // cuerpo del else
}

// INCORRECTO (sin llaves para cuerpo de una línea)
if ($condition)
    doSomething();

4. Operadores

• Operadores de comparación y asignación deben estar rodeados por espacios.

$result = $a + $b + $c; // Espacios alrededor del '=' y del '+'
if ($a === $b) {        // Espacios alrededor de '==='
    // ...
}

5. Métodos y funciones

• No debe haber espacio después del nombre de la función y antes del paréntesis de apertura.

• Los parámetros no deben tener espacio antes de la coma, pero sí después.

• La coma en el último parámetro ( trailing comma) está permitida y se recomienda para facilitar añadir nuevos parámetros.

// CORRECTO
public function foo($arg1, &$arg2, $arg3 = [], ...$arg4)
{
    // cuerpo del método
}

// Llamada a función con trailing comma (recomendado)
myFunction(
    $param1,
    $param2,
    $param3, // <- Esta coma al final es válida y recomendable
);

¿Cómo se relaciona con Laravel?

• Laravel y PSR-12: El framework Laravel en sí no sigue PSR-12 al 100%. Tiene su propia guía de estilo (por ejemplo, no pone llaves en la misma línea para los namespaces). Sin embargo, es completamente compatible y fomenta su uso en proyectos de aplicación.

PSR-12 es la gramática y la ortografía del PHP moderno. Aplicarlo a tu proyecto no es solo una "buena práctica", es una inversión en la calidad y profesionalismo de tu código, asegurando que sea claro y mantenible a largo plazo.