Las siguientes reglas de programación definen las prácticas de desarrollo que deben seguirse durante la implementación del proyecto. Estas reglas se basan en principios de código limpio y buenas prácticas de Laravel para mantener un sistema bien estructurado, mantenible y escalable.

Si un miembro del equipo sube código que no sigue estas reglas, el código debe corregirse de acuerdo con las directrices definidas en esta documentación.

Los controladores deben actuar como intermediarios entre la lógica de la aplicación y las vistas.

Reglas:

• Los controladores no deben contener lógica de presentación.
• Los controladores no deben generar salida HTML.
• Nunca usar echo, print ni funciones de salida similares dentro de los controladores.
• Los controladores deben recibir la solicitud, coordinar las operaciones necesarias y retornar una respuesta.
• Los controladores deben pasar datos a las vistas usando arreglos asociativos.

Ejemplo:

return view('products.index')->with('viewData', $viewData);

Los modelos representan las entidades del dominio y gestionan la interacción con la base de datos.

Reglas:

• Los modelos deben contener la lógica de datos relacionada con la entidad.
• El acceso a los atributos del modelo debe manejarse mediante métodos getter y setter cuando sea necesario.
• Las operaciones de base de datos deben realizarse a través de Eloquent.
• Los modelos no deben contener lógica de presentación.
• Los atributos del modelo deben documentarse en comentarios al inicio del modelo para describir claramente la estructura de la entidad y el tipo de cada atributo.

Ejemplo:

/**
 * ATRIBUTOS DE REVIEW
 * $this->attributes['id'] - int - contiene la llave primaria del review (id)
 * $this->attributes['description'] - string - contiene la descripción del review
 * $this->attributes['rating'] - int - contiene la calificación del review
 */

• Las validaciones de formularios y solicitudes deben implementarse usando las clases Form Request de Laravel ubicadas en:

app/Http/Requests

Ejemplo de reglas de validación dentro de un Form Request:

public function rules(): array
{
    return [
        'description' => 'required|string',
        'rating' => 'required|integer|min:0|max:5',
    ];
}

Las vistas son responsables únicamente de presentar información al usuario.

Reglas:

• Todas las vistas deben escribirse usando Laravel Blade.
• Todas las vistas deben extender el layout principal app.
• Las vistas no deben contener código PHP en bruto.
• Nunca abrir y cerrar etiquetas PHP (<?php ?>) dentro de las vistas.
• La lógica de negocio nunca debe colocarse en las vistas.
• Solo la lógica simple de visualización debe manejarse en Blade.

Ejemplo:

@extends('layouts.app')

@section('content')
<h1>Bienvenido a la aplicación</h1>
@endsection

Las rutas definen cómo se dirigen las solicitudes dentro de la aplicación.

Reglas:

• Cada ruta debe estar asociada a un controlador.
• Las rutas no deben contener lógica de negocio.
• Las rutas solo deben definir el endpoint y delegar la solicitud a un método del controlador.
• Las rutas siempre deben referenciar los controladores usando la ruta completa del controlador en el siguiente formato:

Ejemplo:

Route::get('/contact', 'App\Http\Controllers\HomeController@contact')->name('home.contact');

Este formato garantiza que todas las rutas definan explícitamente el controlador responsable de manejar la solicitud.

Al implementar operaciones CRUD, se deben usar controladores de recursos siempre que sea posible. Laravel provee una estructura estandarizada para estos controladores.

La siguiente tabla describe las acciones típicas manejadas por un controlador de recursos:

La estructura de la base de datos debe gestionarse usando las herramientas de Laravel.

Reglas:

• La base de datos nunca debe modificarse manualmente.
• Todos los cambios estructurales deben implementarse usando migraciones.
• Las migraciones deben estar versionadas dentro del repositorio.
• Cada cambio en el esquema de la base de datos debe tener un archivo de migración correspondiente.

Para crear una migración, usar el siguiente comando de Artisan:

php artisan make:migration create_reviews_table

Este comando generará un archivo de migración dentro de:

database/migrations

Dentro del archivo de migración, la estructura de la tabla se define usando el Schema Builder de Laravel.

Ejemplo:

Schema::create('reviews', function (Blueprint $table) {
    $table->id();
    $table->text('description');
    $table->integer('rating');
    $table->timestamps();
});

Para aplicar las migraciones y actualizar la estructura de la base de datos, ejecutar:

php artisan migrate

Este comando ejecuta todas las migraciones pendientes y actualiza el esquema de la base de datos.

Para mantener consistencia en el código, se deben usar herramientas de formateo.

Reglas:

• El código debe seguir la guía de estilos del proyecto.
• Se debe usar Laravel Pint para aplicar los estándares de codificación.
• Los desarrolladores deben formatear su código antes de hacer commit.

El proyecto debe mantener documentación clara que describa la arquitectura y las reglas de desarrollo.

Reglas:

• El equipo debe mantener documentación actualizada en la Wiki del proyecto.
• Las reglas de programación y las guías de estilo deben ser seguidas por todos los miembros del equipo.
• Cualquier código que no siga las reglas documentadas debe corregirse antes de ser fusionado en las ramas principales.