Saltar al contenido
KHEN / ES
Menú
Todos los posts

Publicado 22 feb. 2020

Buenas prácticas en Laravel: convenciones de nombrado

Casi todo en Laravel es configurable, pero el framework ya tiene su forma de nombrar cada cosa y seguirla te ahorra un montón de ajustes.

Estas convenciones siguen el estilo definido por PSR-12, la sucesora de PSR-2 (y que hoy sigue evolucionando como PER Coding Style).

Espero que este artículo sirva de guía recurrente ante cualquier duda.

Base

Antes de comenzar, vamos a refrescar algunos estilos para nombrar ciertos elementos.

Estilos de nombrado

En el mundo de la programación hay muchos estilos que se emplean para reemplazar los espacios ( ) de las palabras a la hora de definir elementos tales como nombres de variables, funciones, clases, codificar URLs, y un largo etc. Algunos de los más utilizados son los siguientes:

camelCase

Este estilo elimina los espacios aplicando una mayúscula para juntar la palabra siguiente. Notar que la primera letra va siempre en minúscula. El nombre viene por la forma de la joroba de un camello /\/\ (camel). Ejemplos:

estoEstaBien
EstoNoEsCorrecto
esto_tampoco

PascalCase

Muy similar al anterior, solo que en este caso la primera letra va en mayúscula. El nombre proviene del lenguaje de programación Pascal. Ejemplos:

EstoEstaBien
estoYaNo
esto_menos

snake_case

En este estilo se reemplazan los espacios por sub-guiones (_) y todo el texto se escribe en minúsculas. Tal como indica su nombre, se le llama así por la similitud con el movimiento de las serpientes. Ejemplos:

esto_esta_bien
estoNo
EstoMuchoMenos
ni-hablar-de-este-otro

kebab-case

Este estilo es similar al anterior (snake_case), con la única diferencia de que utiliza guiones (-) en lugar de sub-guiones. De este modo el texto toma la forma de una brocheta, de ahí el origen del nombre (kebab). Ejemplos:

ahora-si-me-toco-a-mi
EstoNoEstaBien
estoMuchoMenos
este_se_parece_pero_noup

Entonces, a modo de resumen:

  • PascalCase
  • camelCase
  • snake_case
  • kebab-case

Estos no son los únicos estilos, de seguro que hay varios más, sin embargo son los que ocuparemos el día de hoy. Ahora sí, pasemos a lo que nos interesa.

Convenciones Laravel

Vamos a agrupar las reglas de nombrado según el tipo de elemento. Como nota general: dado que todo el framework está escrito en inglés, este es el idioma que debes emplear para nombrar tus elementos.

Controladores

Los nombres de los controladores se derivan del nombre del modelo (en singular), añadiendo el sufijo Controller. Se aplica el estilo PascalCase. Veamos algunos ejemplos:

class UserController
class OrderDetailController
class UsersController
class customerController
class DetalleDeFacturaController
class borrowed-book-controller

Funciones

Las funciones deben ser nombradas aplicando camelCase. Veamos algunos ejemplos:

public function getUser()
public function isAdmin()
public function orderDetails()
public function ThisIsABadExample()
public function this_is_also_incorrect()

Modelos

Para nombrar a los modelos tomaremos el nombre de la entidad en singular y siempre aplicando PascalCase. Veamos algunos ejemplos:

class User
class OrderDetail
class Users
class customer
class DetalleDeFactura
class borrowed-book

Propiedades de modelos

Los atributos, tanto los recibidos de la base de datos como los computados, deben ser nombrados siguiendo snake_case:

$user->name
$order->created_at
$invoice->createdAt
$book->LaunchDate

Relaciones

Las relaciones deben seguir el modo de nombrado de las funciones. Además, sus nombres deben ir en singular o plural dependiendo de la naturaleza de la relación.

Las relaciones de tipo hasMany, belongsToMany y morphMany deben indicarse en plural, pues es lógico que estas tratarán con una colección de elementos:

$continent->countries()
$book->authors()
$spider->leg()
$continent->country()

Las relaciones de tipo hasOne, belongsTo y morphTo deben indicarse en singular, pues estas tratan con una única instancia del modelo relacionado:

$phone->owner()
$room->house()
$house->districts()
$line->files()

Métodos de los modelos

El resto de métodos del modelo siguen las mismas reglas que una función común: camelCase. Esto se aplica para los accesores y mutadores, los query scopes, etc.

Desde Laravel 9, un accesor o mutador es un solo método que devuelve Attribute y se llama como el atributo, pero en camelCase. El atributo en sí sigue en snake_case:

protected function firstName(): Attribute
{
    return Attribute::make(
        get: fn (string $value) => ucfirst($value),
    );
}


$user->first_name;

Con los scopes pasa lo mismo: el clásico scopeActive() o, desde Laravel 12, active() con el atributo #[Scope]. En ambos casos se usa como User::active().

Pruebas

Para nombrar los métodos de prueba antepondremos test, y el resto del nombre debe ser una descripción de lo que se prueba. Cuando escribí esto, lo común era usar camelCase (testGetUserOrderHistory()), pero desde Laravel 8 los propios stubs del framework usan snake_case, así que esa es la convención actual. PHPUnit ejecuta ambos siempre que el método empiece con test. Ejemplos:

public function test_get_user_order_history()
public function test_create_and_assign_roles_to_a_user()
public function getUserOrderHistory()

Y si usas Pest, el problema desaparece: el nombre es un string, como en it('returns the user order history').

Rutas

Los sustantivos en las rutas deben indicarse en plural, aplicando kebab-case. Ejemplos:

/customers/23
/orders
/order-details/7
/user/15
/orderDetails/7

Tablas

Tablas entidad

Las tablas toman el nombre en inglés y en plural de la entidad, aplicando en este caso snake_case. Veamos algunos ejemplos:

users
order_details
Payment
invoice
libros

Tablas pivot/pivote

El nombre de las tablas pivote (empleadas en relaciones de muchos a muchos) se deriva de los nombres en singular de las entidades relacionadas, en orden alfabético y empleando snake_case. Ojo con el orden: es permission_user y no user_permission, porque la p va antes que la u. Veamos algunos ejemplos:

permission_user
category_post
user_permission
UserPermission
post_category

Columnas

Las columnas deben ser nombradas aplicando snake_case. Ejemplos:

id
created_at
phone_number
createdAt
PhoneNumber

Llaves primarias y foráneas

Si no se especifica ninguna, Laravel asume por defecto que la llave primaria de la tabla es id.

Las llaves foráneas se nombran como la entidad en singular, añadiendo el sufijo _id. Ejemplos:

post_id
user_id
mobile_phone_id
userId
PostId

Variables

Las variables deben ser descriptivas: en plural si guardan una colección y en singular si guardan un solo elemento. Estas deben aplicar el estilo camelCase. Veamos algunos ejemplos:

$admins = User::isAdmin()->get();
$activeUser = User::active()->first();
$room = Room::all();
$invoices = Order::find(1)->invoice;

Vistas

Para nombrar a las vistas en Blade se aplica kebab-case. Estas vistas deben terminar en .blade.php. Ejemplos:

footer.blade.php
active-user.blade.php
create-admin.blade.php
active_user.blade.php
createAdmin.blade.php

Cierre

Estas son las recomendaciones y los estilos que emplean Laravel y el resto de su comunidad para nombrar los elementos. Puedes estar de acuerdo o no, es normal, pues al final de cuentas son recomendaciones. Por ejemplo, yo siempre preferí snake_case para nombrar las funciones de mis pruebas porque siento que facilita la lectura (y con el tiempo Laravel terminó pensando lo mismo), pero hey, todos tienen sus manías.

En fin, de todos modos siempre es bueno tener esto presente para saber cómo es que se estila. Espero te sirva.

PD: Iré añadiendo más elementos a medida que los note en mi código. Si conoces algún elemento que no aparece en la lista, por favor házmelo saber.