Buenas prácticas en Laravel: Convenciones de nombrado cover image

Buenas prácticas en Laravel: Convenciones de nombrado

Kenny Horna Lectura de 5 minutos

laravel php tips

Casi todo aspecto en Laravel es configurable para que puedas adaptarlo a tus costumbres. Sin embargo, Laravel de por sí tiene un modo de nombrar distintos elementos que te pueden ahorrar estos ajustes adicionales en caso decidas mantener sus prácticas. Estas convenciones siguen el estilo definido por las PSR-2.

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. Algunas de las más utilizadas son las 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. Ejemplos:

EstoEstaBien
estoYaNo
esto_menos

snake_case

En este estilo, se reemplazan los espacios por sub-guiones (_), 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) teniendo como única diferencia la utilización de guiones (-) en lugar de los 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 los que nos interesa.

Convenciones Laravel

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

Controladores

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

UserController
OrderDetailController
customerController
DetalleDeFacturaController
borrowed-book-controller

Funciones

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

getUser()
setIsAdminAttribute()
orderDetails()
ThisIsABadExample()
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:

User
OrderDetail
customer
DetalleDeFactura
borrowed-book

Propiedades de modelos

Los nombres de 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, los nombres de estos deben de ir en singular o plural dependiendo de la naturaleza de la relación.

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

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

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

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

Métodos de los modelos

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

Pruebas

Para nombras los métodos de prueba antepondremos test, el resto del nombre debe ser una descripción del tipo de prueba que se realice, siguiendo lo ya mencionado en la sección funciones. Para el estilo de nombrado se emplea camelCase. Ejemplos:

testGetUserOrderHistory()
testCreateAndAssignRolesToAUser()
getUserOderHistory()
test_create_and_assign_roles_to_a_user()

Rutas

Los sustantivos en las rutas deben ser indicadas en plural, aplicando durante todo esto kebab-case. Ejemplos:

/customers/23
/orders
/user/15

Tablas

Tablas entidad

Las tablas toman el nombre inglés 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 del de los nombres en singular en orden alfabético de las entidades relacionadas, empleando snake_case. Veamos algunos ejemplos:

user_permission
category_post
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 pero añadiendo el sufijo _id. Ejemplos:

post_id
user_id
mobile_phone_id
userId
PostId

Variables

Las variables deben de ser descriptivas. 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. Ejemplo:

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 emplea Laravel y el resto de su comunidad para nombrar los elementos. Puedes estar de acuerdo como no, es normal pues al final de cuenta son recomendaciones. Por ejemplo, personalmente prefiero utilizar snake_case para nombrar las funciones de mis pruebas pues siento que facilita la lectura, pero hey! todos tienen sus manías.

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

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