Skip to content

4. La vista y su modelo

Hasta ahora, las acciones generaban ellas mismas sus respuestas: texto, JSON y algunas etiquetas HTML escritas como una cadena de caracteres. En una aplicación MVC, este es el papel de una vista: un archivo que describe el HTML de la página, con marcadores de posición para los datos que le transmite la acción, el modelo de la vista.

[Laravel] incluye su propio motor de vistas, [Blade]. Una vista [Blade] es un archivo cuyo nombre termina en [.blade.php], almacenado en la carpeta [resources/views] de la aplicación. Es un archivo de texto, en este caso HTML, en el que se interpretan tres tipos de etiquetas en el servidor:

  • [{{ expression }}]: el valor de una expresión [PHP] insertado en la página;
  • [@instruction]: una directiva: condición ([@if]), bucle ([@foreach]), herencia de plantillas ([@extends], [@section]), inclusión ([@include])... Una directiva comienza con [@], seguido de su nombre;
  • [{{-- commentaire --}}]: un comentario, que no aparece en la página generada.

Todo lo demás se copia tal cual. Las expresiones se escriben en [PHP]: no hay un segundo lenguaje que aprender. [Blade] se parece así a [Razor], el motor de vistas de [ASP.NET Core MVC], que también mezcla HTML y código, y que también utiliza el carácter [@]; se diferencia de [Thymeleaf] ([Spring MVC]), cuyas vistas son archivos HTML válidos enriquecidos con atributos [th:]. Una vista [Blade] no se ejecuta tal cual: en su primer uso, [Blade] la compila en un archivo [PHP] estándar, almacenado en [storage/framework/views], que luego reutiliza mientras la vista no cambie. Veremos cómo es este archivo.

4.1. Ejemplo 13: una primera vista

13-first-view/
├── app/
│   ├── Http/
│   │   └── Controllers/
│   │       └── ViewsController.php
│   └── Models/
│       └── PageModel.php
├── resources/
│   └── views/
│       └── views/
│           ├── unknown.blade.php
│           └── index.blade.php
├── routes/
│   └── web.php
└── ...

4.1.1. La plantilla de la vista: app/Models/PageModel.php

<?php
// app/Models/PageModel.php: el modelo de la vista, los datos que la acción pasa a la vista

namespace App\Models;

readonly class PageModel
{
    public function __construct(
        public string $title,
        public string $message,
        public string $time,
    ) {
    }
}

El modelo de la vista es una clase inmutable simple (véase el ejemplo 03): las tres informaciones que la vista mostrará. No es obligatorio definir el modelo de una vista como una clase: se podrían pasar tres variables separadas a la vista. Sin embargo, una clase documenta lo que la vista espera y permite que el editor verifique el código de la acción. Este es el enfoque que seguirá el caso de estudio, donde cada vista tiene su propia clase de modelo.

4.1.2. El controlador: app/Http/Controllers/ViewsController.php

<?php
// app/Http/Controllers/ViewsController.php: acciones que devuelven una VISTA

namespace App\Http\Controllers;

use App\Models\PageModel;
use Illuminate\Http\Response;
use Illuminate\View\View;

class ViewsController
{
    // view: el motor Blade construye la página a partir de la vista
    // resources/views/views/index.blade.php y de las variables pasadas en el
    // arreglo (aquí una sola, [model]); la página producida es la respuesta de la acción
    public function index(): View
    {
        $model = new PageModel(
            'My first view',
            'This page was built by Blade, on the server.',
            date('H:i:s'));
        return view('views.index', ['model' => $model]);
    }

    // la misma vista con otro modelo; o otra vista, con el código 404
    public function hello(string $name): View|Response
    {
        if ($name === 'unknown') {
            // la página, enviada con el código 404
            return response()->view('views.unknown', ['name' => $name], 404);
        }
        $model = new PageModel(
            "Hello $name",
            'This time, the title of the page comes from the URL.',
            date('H:i:s'));
        return view('views.index', ['model' => $model]);
    }
}
  • Líneas 17–20: la acción construye el modelo de la vista. La función ***[date] de *[PHP] da formato a la hora actual: [H] para las horas, [i] para los minutos y [s]** para los segundos;
  • Línea 21: la función [view] hace que [Blade] genere la página. El primer parámetro es el nombre de la vista: la ruta del archivo, relativa a la carpeta [resources/views], donde las [/]s se reemplazan por puntos, y sin la extensión [.blade.php]: [views.index] remite al archivo [resources/views/views/index.blade.php]. El segundo parámetro es un arreglo asociativo, en el que cada clave se convierte en una variable de la vista; en este caso, una sola: [$model]. [view] devuelve un objeto [View], que [Laravel] transforma en una respuesta (de tipo [text/html]) al generar la página;
  • Línea 29: otra vista, con una variable distinta ([$name]). [response()->view(...)] genera una respuesta a partir de una vista, con el código especificado (en este caso, 404) para mostrar una página de error personalizada. El tipo de la acción [View|Response] significa: o bien una [View] o bien una [Response];
  • líneas 31–35: la misma vista que la acción [index], pero con una plantilla distinta. Este es el beneficio de separar las acciones de las vistas: una misma vista puede ser utilizada por varias acciones.

4.1.3. La vista: resources/views/views/index.blade.php

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  {{-- {{ ... }}: el valor de una expresión, insertado en la página --}}
  <title>{{ $model->title }}</title>
</head>
<body>
  <h1>{{ $model->title }}</h1>
  <p>{{ $model->message }}</p>
  <p>Page built at {{ $model->time }}.</p>
</body>
</html>
  • línea 5: un comentario [Blade];
  • línea 6: [{{ $model->title }}] inserta el valor de la propiedad [title] de la variable [$model]. Entre las llaves se puede escribir cualquier expresión [PHP].

Todo lo que inserta [{{ }}] se escapa: los caracteres [<], [>], [&], ["] y ['] se reemplazan por sus entidades HTML. Este es el papel que desempeñaba la función [e] en el ejemplo 09, pero esta vez de forma automática: una vista no puede, por lo tanto, insertar por descuido en la página el HTML proporcionado por un usuario.

4.1.4. La vista: resources/views/views/unknown.blade.php

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Unknown</title>
</head>
<body>
  <h1>Nobody is called [{{ $name }}] here.</h1>
</body>
</html>

Una vista no está obligada a recibir un objeto: la variable [$name] es una cadena.

4.1.5. Ejecución

Image

Image

La hora mostrada es la del Tiempo Universal Coordinado (UTC), la zona horaria predeterminada de [Laravel]; el caso de estudio mostrará cómo cambiarla. La salida sin procesar muestra el trabajo realizado por [Blade]: las etiquetas [{{ }}] se han reemplazado por sus valores, y el comentario se ha eliminado (queda una línea en blanco en su lugar).

curl -i http://localhost:8000/
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">

  <title>My first view</title>
</head>
<body>
  <h1>My first view</h1>
  <p>This page was built by Blade, on the server.</p>
  <p>Page built at 16:04:07.</p>
</body>
</html>

La página de error "home", seguida de un nombre que contiene HTML ([<b>martin], codificado en la URL):

curl -i http://localhost:8000/hello/unknown
curl http://localhost:8000/hello/%3Cb%3Emartin
HTTP/1.1 404 Not Found
Content-Type: text/html; charset=utf-8

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Unknown</title>
</head>
<body>
  <h1>Nobody is called [unknown] here.</h1>
</body>
</html>
...
  <title>Hello &lt;b&gt;martin</title>
...
  <h1>Hello &lt;b&gt;martin</h1>
...

La etiqueta [<b>] fue escapada, aunque ni la acción ni la vista tuvieron nada que ver. Aquí está, por fin, la vista compilada por [Blade], tal como se encuentra en la carpeta [storage/framework/views] (con un nombre calculado, como [bfadc851307fb914e48325630a6c9191.php]):

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">

  <title><?php echo e($model->title); ?></title>
</head>
<body>
  <h1><?php echo e($model->title); ?></h1>
  <p><?php echo e($model->message); ?></p>
  <p>Page built at <?php echo e($model->time); ?>.</p>
</body>
</html>
<?php /**PATH .../13-first-view/resources/views/views/index.blade.php ENDPATH**/ ?>

Cada [{{ expression }}] se ha convertido en [<?php echo e(expression); ?>]: la conversión la realiza la función [e] del ejemplo 09. Una vista [Blade] es, por lo tanto, solo una manera más elegante de escribir un archivo [PHP] que genera HTML. [PHP] fue concebido originalmente como un lenguaje de páginas, en el que el código se inserta en el archivo HTML entre [<?php] y [?>]; [Blade] conserva su eficacia y corrige sus defectos (en particular, la ausencia de escape).

4.2. Ejemplo 14: el lenguaje Blade

Este ejemplo reúne las principales construcciones de [Blade] en una sola vista.

4.2.1. El modelo y la acción

El modelo de la vista se describe mediante tres clases inmutables, cada una en su propio archivo ([PHP] no exige una clase por archivo, pero el cargador de clases de [Composer] busca la clase [App\Models\Product] en el archivo [app/Models/Product.php]):

<?php
// app/Models/Product.php: un producto

namespace App\Models;

readonly class Product
{
    public function __construct(
        public string $name,
        public float $price,
        public bool $inStock,
    ) {
    }
}
<?php
// app/Models/Address.php: una dirección

namespace App\Models;

readonly class Address
{
    public function __construct(
        public string $street,
        public string $city,
    ) {
    }
}
<?php
// app/Models/BasicsModel.php: el modelo de la vista del ejemplo 14

namespace App\Models;

readonly class BasicsModel
{
    /**
     * @param list<Product> $products
     * @param list<Product> $cart
     */
    public function __construct(
        public string $title,
        public string $name,
        public ?string $nickname,
        public string $html,
        public bool $loggedIn,
        public string $currency,
        public array $products,
        public array $cart,
        public Address $address,
    ) {
    }
}

El modelo contiene valores de diversos tipos: cadenas, [null], booleanos, arreglos de objetos, arreglos vacíos y objetos que contienen otros objetos. Los precios son aquí de tipo [float], para simplificar los cálculos en la vista (el ejemplo 06 mostró por qué se prefiere un decimal exacto).

<?php
// app/Http/Controllers/BasicsController.php: una vista que usa las principales construcciones de Blade

namespace App\Http\Controllers;

use App\Models\Address;
use App\Models\BasicsModel;
use App\Models\Product;
use Illuminate\View\View;

class BasicsController
{
    public function index(): View
    {
        $model = new BasicsModel(
            title: 'Blade basics',
            name: 'Martin',
            nickname: null,
            html: '<b>this is HTML</b>',
            loggedIn: true,
            currency: '€',
            products: [
                new Product('Keyboard', 25, true),
                new Product('Mouse', 12.5, false),
                new Product('Screen', 149, true),
            ],
            cart: [],
            address: new Address('12 rue des Lilas', 'Angers'));
        return view('basics.index', ['model' => $model]);
    }
}

La acción construye el modelo mediante parámetros con nombre (véase el ejemplo 01): cada valor va precedido del nombre del parámetro al que está destinado, lo que hace legible la llamada a pesar del número de parámetros.

4.2.2. La vista: resources/views/basics/index.blade.php

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>{{ $model->title }}</title>
</head>
<body>
  {{-- código PHP en la vista, entre las dos instrucciones siguientes; aquí, dos variables --}}
  @php
    $total = collect($model->products)->sum('price');
    $count = count($model->products);
  @endphp
  <h1>{{ $model->title }}</h1>
  {{-- 1. muestra un valor del modelo; null se muestra como una cadena vacía;
       el operador ?? reemplaza un valor null. Este comentario de Blade no aparece
       en la página producida --}}
  <p>1. Name: {{ $model->name }} - nickname: [{{ $model->nickname }}] [{{ $model->nickname ?? 'none' }}]</p>
  {{-- 2. {{ }} escapa el HTML; {!! !!} lo inserta tal cual --}}
  <p>2a. {{ $model->html }}</p>
  <p>2b. {!! $model->html !!}</p>
  {{-- 3. a condition --}}
  @if ($model->loggedIn)
    <p>3. You are logged in.</p>
  @else
    <p>3. You are not logged in.</p>
  @endif
  {{-- 4. un bucle: $loop describe el estado del bucle --}}
  <p>4. Our products:</p>
  <ul>
    @foreach ($model->products as $product)
      <li>no. {{ $loop->index }}: {{ $product->name }}, {{ $product->price }} {{ $model->currency }}
        {{ $product->inStock ? '(in stock)' : '(sold out)' }}
        @if ($loop->first) - the first one @endif
        @if ($loop->last) - the last one, seen by {{ $model->name }} @endif
      </li>
    @endforeach
  </ul>
  {{-- 5. the empty list: @forelse ... @empty --}}
  <p>5. Your cart:
    @forelse ($model->cart as $p)<span>{{ $p->name }}</span>@empty it is empty. @endforelse
  </p>
  {{-- 6. computed expressions, the @php variables, and number_format --}}
  <p>6. {{ $count }} products, for a total of {{ $total }} {{ $model->currency }};
    average price: {{ number_format($total / $count, 2, '.', ',') }} {{ $model->currency }}</p>
  {{-- 7. un objeto dentro de un objeto, y una función de PHP (mb_strtoupper) --}}
  <p>7. Address: {{ $model->address->street }}, {{ mb_strtoupper($model->address->city) }}</p>
  {{-- 8. @ es una instrucción de Blade solo al inicio de una palabra; @@ escribe una @ --}}
  <p>8. An email address: contact@example.com; a displayed instruction: @@if</p>
</body>
</html>
  • Líneas 9–12: las directivas [@php] y [@endphp] delimitan un bloque de código [PHP], que se ejecuta en este punto de la página. Allí se crean dos variables de la vista: el precio total, calculado por el método [sum] de una colección (ejemplo 03), que suma una propiedad de cada elemento, y el número de productos. El bloque [@php] debe reservarse para este tipo de preparación: el cálculo normalmente corresponde a la acción;
  • línea 17: un valor [null] se muestra como una cadena vacía. El operador [??] de [PHP] (ejemplo 08) reemplaza un valor [null] por un valor predeterminado;
  • Líneas 19–20: [{{ }}] escapa el HTML (2a); [{!! !!}], en cambio, inserta el valor tal cual, sin escaparlo (2b). [{!! !!}] se reserva para el HTML generado por la propia aplicación, nunca para lo que ingresa el usuario;
  • líneas 22–26: una condición: [@if], [@elseif], [@else], [@endif], con una condición [PHP] entre paréntesis. Cada bloque se cierra con una directiva [@end...];
  • líneas 30–36: un bucle [@foreach] ... [@endforeach], que se escribe como el bucle [foreach] de [PHP]. Dentro de él, la variable especial [$loop] describe el estado del bucle: [$loop->index] (el número de iteración, que comienza en 0), [$loop->iteration] (que comienza en 1), [$loop->first], [$loop->last] (verdadero en la primera y en la última iteración), [$loop->count] (el número de elementos). Las variables externas al bucle ([$model->name]) siguen siendo accesibles;
  • Línea 32: el operador ternario de [PHP], [condition ? a : b] (ejemplo 11);
  • línea 40: la directiva [@forelse] ... [@empty] ... [@endforelse] es un bucle en el que el bloque [@empty] se ejecuta si la lista está vacía. Es más simple que un [@if] que probara la longitud de la lista;
  • líneas 43–44: expresiones calculadas ([$total / $count]) y las variables del bloque [@php]. La función [number_format] de [PHP] da formato a un número: dos decimales, un punto como separador decimal y una coma como separador de miles. En el ejemplo 16 veremos una manera mucho mejor de dar formato a números e importes;
  • Línea 46: el operador [->] recorre los objetos ([$model->address->city]), y se puede llamar a cualquier función de [PHP]: [mb_strtoupper] pasa una cadena a mayúsculas (las funciones [mb_...], de *multi-byte*, manejan correctamente los caracteres acentuados codificados en UTF-8);
  • línea 48: el carácter [@] solo es interpretado por [Blade] al comienzo de una palabra; en una dirección de correo electrónico, se copia tal cual. Para escribir un [@] seguido del nombre de una directiva, se duplica: [@@if] produce [@if]. De igual manera, [@{{ ... }}] produce [{{ ... }}], lo que resulta útil cuando una página contiene llaves destinadas a un framework [JavaScript].

Una nota sobre los comentarios: [Blade] procesa [@php] los bloques antes que los comentarios. Un comentario que contuviera la palabra [@php] sería interpretado, por lo tanto, como el inicio de un bloque de código, con resultados inesperados: por eso el comentario de la línea 8 no la incluye.

4.2.3. Ejecución

Image

La página generada:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Blade basics</title>
</head>
<body>

    <h1>Blade basics</h1>

  <p>1. Name: Martin - nickname: [] [none]</p>

  <p>2a. &lt;b&gt;this is HTML&lt;/b&gt;</p>
  <p>2b. <b>this is HTML</b></p>

      <p>3. You are logged in.</p>

  <p>4. Our products:</p>
  <ul>
          <li>no. 0: Keyboard, 25 €
        (in stock)
         - the first one               </li>
          <li>no. 1: Mouse, 12.5 €
        (sold out)
                      </li>
          <li>no. 2: Screen, 149 €
        (in stock)
                 - the last one, seen by Martin       </li>
      </ul>

  <p>5. Your cart:
     it is empty.   </p>

  <p>6. 3 products, for a total of 186.5 €;
    average price: 62.17 €</p>

  <p>7. Address: 12 rue des Lilas, ANGERS</p>

  <p>8. An email address: contact@example.com; a displayed instruction: @if</p>
</body>
</html>

Los comentarios y las directivas han desaparecido, pero dejan tras de sí sus espacios y saltos de línea: [Blade] no intenta producir un HTML con formato ordenado. Esto no tiene consecuencias: el navegador ignora estos caracteres de espacio en blanco. Un número como [float] insertado en una cadena se escribe con punto decimal ([12.5]); [number_format] utiliza los separadores que se le pasan.

4.3. Ejemplo 15: plantillas, fragmentos, archivos estáticos

Las páginas de un sitio web suelen compartir la misma estructura: un encabezado, una barra de navegación, un pie de página y las mismas hojas de estilo. En lugar de repetir esta estructura en cada vista, se escribe una sola vez en una plantilla (*layout*), que las páginas extienden. Este ejemplo utiliza además [Bootstrap], el framework CSS más utilizado, para el diseño.

15-layout/
├── app/
│   ├── Http/
│   │   └── Controllers/
│   │       └── PagesController.php
│   └── Models/
│       └── Member.php
├── bootstrap/
│   └── app.php
├── public/
│   └── css/
│       └── styles.css
├── resources/
│   └── views/
│       ├── components/
│       │   └── card.blade.php
│       ├── fragments/
│       │   └── navbar.blade.php
│       ├── layout.blade.php
│       └── pages/
│           ├── home.blade.php
│           ├── raw.blade.php
│           └── team.blade.php
├── routes/
│   └── web.php
└── ...

4.3.1. Archivos estáticos

Una página HTML hace referencia a otros archivos: hojas de estilo, scripts [JavaScript] e imágenes. Estos archivos, que el servidor envía tal cual, se denominan archivos estáticos. Con [Laravel], se almacenan en la carpeta [public], que el servidor web sirve tal cual (ejemplo 01): el archivo [public/css/styles.css] está disponible en la URL [/css/styles.css], sin que [Laravel] intervenga.

/* algunos ajustes además de Bootstrap */
body {
  background-color: #f5f7fa;
}

/* el pie de página del diseño (layout) */
.footer {
  margin-top: 2rem;
  font-size: 0.85rem;
  color: #6c757d;
}

/* los mensajes de error, al final de la página, sobre un fondo rosa claro */
.error-area {
  margin-top: 1.5rem;
  padding: 0.75rem 1rem;
  background-color: #fdecef;
  border: 1px solid #f5c2c7;
  border-radius: 0.375rem;
  color: #842029;
}

Algunas reglas CSS adicionales además de [Bootstrap]: un fondo gris claro, el estilo del pie de página y el estilo de una zona de error que se utilizará en los ejemplos siguientes.

[Bootstrap] se utiliza en los ejemplos 15 a 28. En lugar de colocar una copia en la carpeta [public] de cada ejemplo, estos lo comparten: se encuentra en la carpeta [examples/common/bootstrap]. Esta carpeta no es servida por el servidor web: una ruta, común a todos estos ejemplos, sirve sus archivos. Está descrita por el archivo [examples/common/bootstrap.php]:

<?php
// common/bootstrap.php: una ruta que sirve los archivos de Bootstrap, compartida por
// los ejemplos 15 a 28 (la carpeta examples/common/bootstrap), bajo la URL /bootstrap/...

use Illuminate\Support\Facades\Route;

Route::get('bootstrap/{file}', function (string $file) {
    $folder = realpath(__DIR__.'/bootstrap');
    // realpath: la ruta absoluta del archivo solicitado, sin el . ni el .. ; false
    // si el archivo no existe
    $path = realpath($folder.'/'.$file);
    // un archivo que existe, y que está efectivamente DENTRO de la carpeta (sin ../ para salir de ella)
    abort_unless($path && str_starts_with($path, $folder.DIRECTORY_SEPARATOR)
        && is_file($path), 404);
    // el tipo del archivo, a partir de su extensión
    $types = ['css' => 'text/css', 'js' => 'text/javascript', 'map' => 'application/json'];
    $type = $types[pathinfo($path, PATHINFO_EXTENSION)] ?? 'application/octet-stream';
    return response()->file($path, ['Content-Type' => $type]);
})->where('file', '.*')->name('bootstrap');
  • línea 7: una ruta cuya acción es una función anónima (ejemplo 01). El parámetro de ruta [{file}] acepta cualquier final de ruta, incluidas las barras (restricción [.*], línea 19, véase el ejemplo 02): la URL [/bootstrap/css/bootstrap.min.css] designa el archivo [css/bootstrap.min.css] de la carpeta. La ruta se llama [bootstrap];
  • líneas 8–14: servir archivos designados por una URL exige una precaución: una URL como [/bootstrap/../../15-layout/.env] no debe dar acceso a un archivo situado fuera de la carpeta. La función [realpath] de [PHP] calcula la ruta absoluta de un archivo, sin sus componentes [.] y [..], o devuelve [false] si el archivo no existe. Se verifica que la ruta resultante comience efectivamente con la ruta de la carpeta ([str_starts_with]) y que designe un archivo ([is_file]); de lo contrario, [abort_unless] termina la solicitud con un error 404. [abort_unless(condition, code)] equivale a [if (! condition) abort(code)]; de manera similar, también existe [abort_if]. [DIRECTORY_SEPARATOR] es el separador de rutas del sistema: [\] en [Windows], [/] en los demás;
  • líneas 16–18: [response()->file] genera una respuesta que envía el contenido de un archivo. El tipo de contenido se elige según la extensión del archivo (obtenida con [pathinfo]), de modo que una hoja de estilo se declara correctamente como [text/css]: un navegador rechazará una hoja de estilo declarada con otro tipo.

La ruta se declara en el archivo [bootstrap/app.php] de cada ejemplo:

<?php
// bootstrap/app.php: la aplicación del ejemplo 15

use Illuminate\Foundation\Application;
use Illuminate\Support\Facades\View;

(require __DIR__.'/../../vendor/autoload.php')->addPsr4('App\\', __DIR__.'/../app/');

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        // then: rutas declaradas fuera del grupo web (sin sesión ni cookies):
        // la que sirve Bootstrap, compartida por los ejemplos 15 a 28
        then: fn () => require __DIR__.'/../../common/bootstrap.php')
    ->withMiddleware()
    ->withExceptions()
    // booted: código ejecutado una vez que la aplicación ha arrancado
    ->booted(function () {
        // un "view composer": se ejecuta antes de la construcción de CADA vista (*),
        // y agrega sus variables a todas las vistas
        View::composer('*', function ($view) {
            $view->with(['path' => request()->path(), 'year' => date('Y')]);
        });
    })
    ->create();
  • líneas 11–14: el parámetro [then] de [withRouting] es una función, llamada una vez declaradas las rutas de [routes/web.php], para declarar rutas adicionales. Estas no forman parte del grupo [web]: no tienen sesión ni cookies, lo cual es adecuado para archivos estáticos. La función flecha ejecuta el archivo [common/bootstrap.php];
  • líneas 18–24: el método [booted] registra una función que se ejecuta una vez que la aplicación ha arrancado;
  • líneas 21–23: la fachada [View] registra un view composer: una función que [Laravel] ejecuta antes de renderizar cada vista cuyo nombre coincide con el patrón indicado, en este caso [*] (todas). Recibe la vista y puede agregarle variables ([with]). Aquí, [$path] (la ruta de la URL solicitada, proporcionada por [request()], la solicitud actual) y [$year] (el año actual) quedan así disponibles en todas las vistas, sin que las acciones tengan que proporcionarlas. La plantilla las utiliza en su pie de página. El método [View::share('name', value)] compartiría de manera similar un valor fijo con todas las vistas.

4.3.2. La plantilla: resources/views/layout.blade.php

<!doctype html>
{{-- la plantilla base de las páginas: las páginas la EXTIENDEN y llenan sus secciones --}}
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {{-- @yield: un espacio que la página puede llenar; aquí con un contenido por defecto --}}
  <title>@yield('title', 'Home') - My site</title>
  {{-- route(): la URL de la ruta con nombre [bootstrap]; asset(): la URL de un archivo de public/ --}}
  <link rel="stylesheet" href="{{ route('bootstrap', 'css/bootstrap.min.css') }}">
  <link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
  <div class="container py-3">
    {{-- insertion of the fragments/navbar.blade.php file --}}
    @include('fragments.navbar')
    <main>
      {{-- el contenido de la página solicitada por la acción se inserta aquí --}}
      @yield('content')
    </main>
    {{-- $path, $year: agregados a todas las vistas (véase bootstrap/app.php) --}}
    <footer class="footer">Page [{{ $path }}] - © {{ $year }}</footer>
  </div>
</body>
</html>
  • línea 6: la etiqueta [viewport] indica a los navegadores móviles que muestren la página al ancho de la pantalla, que es lo que [Bootstrap] espera;
  • Línea 8: la directiva [@yield] marca un espacio con nombre (que las páginas que extienden la plantilla pueden rellenar) con una sección del mismo nombre. El segundo parámetro es el contenido predeterminado del espacio, utilizado por una página que no proporciona la sección;
  • Líneas 10–11: [route('bootstrap', 'css/bootstrap.min.css')] genera la URL de la ruta con nombre [bootstrap] (ejemplo 04), utilizando el valor de su parámetro [{file}]. La función [asset] crea la URL de un archivo de la carpeta [public]. Escribir la URL del archivo manualmente ([/css/styles.css]) también funcionaría, pero [asset] funciona incluso si la aplicación está instalada bajo un prefijo de URL;
  • línea 16: [@include] inserta el contenido de otra vista, en este caso la barra de navegación. La vista incluida tiene acceso a las variables de la vista que la incluye;
  • línea 19: la zona que cada página rellena con su propio contenido;
  • línea 22: el pie de página utiliza las dos variables del view composer.

La clase [container] de [Bootstrap] centra el contenido y limita su ancho; [py-3] agrega un relleno vertical: [Bootstrap] ofrece cientos de clases como estas, que se combinan en el atributo [class].

4.3.3. La barra de navegación: resources/views/fragments/navbar.blade.php

1
2
3
4
5
6
7
8
9
{{-- un fragmento: una pieza de página, insertada por @include --}}
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <span class="navbar-brand">My site</span>
  <div class="navbar-nav">
    <a class="nav-link" href="/">Home</a>
    <a class="nav-link" href="/team">Team</a>
    <a class="nav-link" href="/raw">Page without layout</a>
  </div>
</nav>

Un fragmento: una parte de una página que no tiene sentido por sí sola. Las clases [navbar], [navbar-brand] y [nav-link] son las de la barra de navegación de [Bootstrap].

4.3.4. Un componente: resources/views/components/card.blade.php

1
2
3
4
5
6
7
8
{{-- un COMPONENTE: un fragmento de página que tiene parámetros, como una función --}}
@props(['name', 'role'])
<div class="card">
  <div class="card-body">
    <h5 class="card-title">{{ $name }}</h5>
    <p class="card-text">{{ $role }}</p>
  </div>
</div>
  • Línea 2: un componente es una sección de una página que tiene parámetros; esta es la función de [Blade]. Un componente anónimo es una vista simple de la carpeta [resources/views/components]; la directiva [@props] declara sus parámetros, que se convierten en variables de la vista. Se utiliza como una etiqueta HTML cuyo nombre comienza con [x-]: [<x-card name="..." role="..." />] inserta el fragmento de página generado con estos valores. Los parámetros pueden tener un valor predeterminado: [@props(['name', 'role' => ''])]. La tarjeta ([card]) es un componente de [Bootstrap].

4.3.5. Las páginas

{{-- esta página EXTIENDE la plantilla base: solo proporciona el contenido de sus secciones --}}
@extends('layout')

@section('content')
  <h1>Welcome</h1>
  <p>This page only contains its own content: the header, the navigation
    bar and the footer come from the <code>layout.blade.php</code> layout.</p>
  {{-- el componente [card], con dos parámetros escritos en el lugar --}}
  <x-card name="A component" role="called with parameters written on the spot" />
@endsection
  • línea 2: la página extiende la plantilla: [Blade] genera la página de la plantilla, reemplazando sus marcadores [@yield] por las secciones definidas por la página. En una vista que extiende una plantilla, el texto escrito fuera de las secciones no aparece en la página generada;
  • Líneas 4–10: la sección [content], que rellena el marcador del mismo nombre. La página no define la sección [title]: el marcador conserva su contenido predeterminado, “Home”;
  • línea 9: el uso del componente [card]. Los parámetros se escriben como atributos HTML; sus valores son cadenas.
@extends('layout')

@section('title', 'Our team')

@section('content')
  <h1>Our team</h1>
  <div class="row g-3">
    @foreach ($members as $member)
      <div class="col-md-4">
        {{-- :name="...": el valor del parámetro es una EXPRESIÓN PHP --}}
        <x-card :name="$member->name" :role="$member->role" />
      </div>
    @endforeach
  </div>
@endsection
  • línea 3: una sección corta, cuyo contenido se proporciona como segundo parámetro;
  • líneas 8–13: una tarjeta por cada miembro del equipo, en una cuadrícula de [Bootstrap] ([row], [col-md-4]: tres columnas en una pantalla mediana o grande, una columna en una pantalla angosta);
  • línea 11: un parámetro cuyo nombre está precedido por [:] recibe el valor de una expresión [PHP], no de una cadena: [:name="$member->name"].

El controlador no introduce ninguna novedad:

<?php
// app/Http/Controllers/PagesController.php: tres páginas

namespace App\Http\Controllers;

use App\Models\Member;
use Illuminate\View\View;

class PagesController
{
    public function home(): View
    {
        return view('pages.home');
    }

    public function team(): View
    {
        $members = [
            new Member('Marie Pélissier', 'Director'),
            new Member('Jacques Bromard', 'Developer'),
            new Member('Philippe Jandot', 'Graphic designer'),
        ];
        return view('pages.team', ['members' => $members]);
    }

    public function raw(): View
    {
        return view('pages.raw');
    }
}

Por último, la tercera página no utiliza la plantilla:

<!doctype html>
{{-- esta vista no usa la plantilla base: es una página completa --}}
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Raw page</title>
</head>
<body>
  <p>This page does not use the layout: no Bootstrap, no navigation bar.</p>
  <p><a href="/">Back to home</a></p>
</body>
</html>

4.3.6. Ejecución

Image

Image

Image

La página del equipo, tal como la recibe el navegador (se han eliminado las líneas en blanco que dejan los comentarios y las directivas):

curl http://localhost:8000/team
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Our team - My site</title>
  <link rel="stylesheet" href="http://localhost:8000/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="http://localhost:8000/css/styles.css">
</head>
<body>
  <div class="container py-3">
    <nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <span class="navbar-brand">My site</span>
  <div class="navbar-nav">
    <a class="nav-link" href="/">Home</a>
    <a class="nav-link" href="/team">Team</a>
    <a class="nav-link" href="/raw">Page without layout</a>
  </div>
</nav>
    <main>
        <h1>Our team</h1>
  <div class="row g-3">
          <div class="col-md-4">
        <div class="card">
  <div class="card-body">
    <h5 class="card-title">Marie Pélissier</h5>
    <p class="card-text">Director</p>
  </div>
</div>
      </div>
...
      </div>
    </main>
    <footer class="footer">Page [team] - © 2026</footer>
  </div>
</body>
</html>

El navegador recibió una página completa: la plantilla, el fragmento, la página y los componentes se ensamblaron en el servidor. Los valores de URL de las hojas de estilo fueron calculados por [route] y [asset]: son URL absolutas. La ruta de la página de inicio es [/]; las rutas de las demás páginas se escriben sin barra inicial ([team]): esta es la convención de [request()->path()]. Se puede verificar que las hojas de estilo se aplican correctamente (la opción [-I] de [curl] muestra solo los encabezados de la respuesta):

curl -I http://localhost:8000/bootstrap/css/bootstrap.min.css
curl -I http://localhost:8000/css/styles.css
1
2
3
4
5
6
7
8
9
HTTP/1.1 200 OK
Content-Type: text/css; charset=utf-8
Last-Modified: Sat, 26 Sep 2026 16:04:06 GMT
Content-Length: 232111
Accept-Ranges: bytes
...
HTTP/1.1 200 OK
Content-Type: text/css; charset=UTF-8
Content-Length: 435

El primer archivo fue enviado por nuestra ruta; el segundo fue enviado directamente por el servidor de desarrollo, sin pasar por [Laravel].

4.4. Ejemplo 16: helpers

Una vista suele necesitar dar formato a valores: un importe con su moneda, una fecha escrita con todas sus letras o un texto en mayúsculas. Este código no pertenece a la acción (que no se ocupa de la presentación) y sería engorroso de escribir en la vista. En su lugar, se escribe en [PHP], en funciones que las vistas llaman: son los helpers de la vista. [Blade] ofrece varias maneras de ponerlos a disposición: llamar a una función o a un método estático, escribir sus propias directivas ([@money($price)]) y utilizar componentes, que ya hemos visto.

16-helpers/
├── app/
│   ├── Helpers/
│   │   └── Formats.php
│   ├── Http/
│   │   ├── Controllers/
│   │   │   └── PagesController.php
│   │   └── Middleware/
│   │       └── SetLanguage.php
│   └── Models/
│       └── Product.php
├── resources/
│   └── views/
│       ├── components/
│       │   ├── badge.blade.php
│       │   └── link.blade.php
│       ├── fragments/
│       │   └── navbar.blade.php
│       ├── layout.blade.php
│       └── pages/
│           ├── home.blade.php
│           └── products.blade.php
└── ...

4.4.1. Funciones: app/Helpers/Formats.php

<?php
// app/Helpers/Formats.php: funciones invocadas por las vistas

namespace App\Helpers;

use Brick\Math\BigDecimal;
use Carbon\CarbonInterface;
use Illuminate\Support\Facades\App;
use Illuminate\Support\Number;

class Formats
{
    // "keyboard" -> "KEYBOARD"
    public static function uppercase(?string $text): string
    {
        return $text === null ? '' : mb_strtoupper($text);
    }

    // un monto en una moneda, en el formato del idioma de la solicitud (véase el
    // middleware SetLanguage): 1149.9 -> "€1,149.90" en inglés, "1 149,90 €" en
    // francés. La extensión intl de PHP conoce las convenciones de cada país
    public static function money(BigDecimal $amount, string $currency = 'EUR'): string
    {
        return Number::currency($amount->toFloat(), in: $currency, locale: App::getLocale());
    }

    // una fecha con palabras completas, en el idioma de la solicitud: "Saturday 26 September 2026"
    public static function longDate(CarbonInterface $day): string
    {
        return $day->locale(App::getLocale())->isoFormat('dddd D MMMM YYYY');
    }
}
  • Líneas 14–17: un método estático ([static]): se llama sobre la clase, sin un objeto ([Formats::uppercase('keyboard')]). Acepta [null];
  • líneas 22–24: formato de un importe. Depende del idioma: en francés, [1 149,90 €] (espacio para separar los miles, coma decimal, símbolo después del importe); en inglés, [€1,149.90]. La clase [Number] de [Laravel] se basa en la extensión [intl] de [PHP], que admite las convenciones de todos los países (utiliza los datos del proyecto Unicode *CLDR*): [Number::currency] da formato a un importe, con la moneda designada por su código internacional ([EUR], [USD]). [intl] solo puede dar formato a números [float]: el decimal se convierte ([toFloat()]), lo cual es seguro aquí, ya que el número no se vuelve a utilizar para cálculos. El idioma ([fr], [en]) es el de la aplicación para la solicitud actual, devuelto por [App::getLocale()]; veremos quién lo establece;
  • Líneas 28–30: formato de una fecha [Carbon] (ejemplo 12). [locale(...)] devuelve una copia de la fecha configurada para un idioma específico; [isoFormat] le da formato de la siguiente manera: [dddd] escribe con letras el día de la semana, [D] el día del mes, [MMMM] escribe con letras el mes y [YYYY] el año. [Carbon] incluye traducciones de estos nombres en más de doscientos idiomas. El tipo [CarbonInterface] acepta todas las fechas [Carbon].

4.4.2. El idioma de cada solicitud: app/Http/Middleware/SetLanguage.php

<?php
// app/Http/Middleware/SetLanguage.php: el idioma de formato de cada solicitud

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\App;
use Symfony\Component\HttpFoundation\Response;

class SetLanguage
{
    // el parámetro ?lang=fr de la URL, inglés en caso contrario
    public function handle(Request $request, Closure $next): Response
    {
        App::setLocale($request->query('lang') === 'fr' ? 'fr' : 'en');
        return $next($request);
    }
}

El idioma de formato depende de la solicitud: el parámetro [?lang=fr] de la URL selecciona el francés; el inglés es el idioma predeterminado. Un middleware (ejemplo 03) lo establece antes de cada acción, mediante [App::setLocale]: la fachada [App] hace referencia a la propia aplicación. El idioma establecido de este modo se aplica solo a la solicitud actual: la siguiente solicitud volverá al idioma de [.env] ([APP_LOCALE], con el inglés como valor predeterminado). El capítulo sobre internacionalización utilizará este mismo idioma para traducir los textos.

4.4.3. Configuración: bootstrap/app.php

<?php
// bootstrap/app.php: la aplicación del ejemplo 16

use App\Http\Middleware\SetLanguage;
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Middleware;
use Illuminate\Support\Facades\Blade;

(require __DIR__.'/../../vendor/autoload.php')->addPsr4('App\\', __DIR__.'/../app/');

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        // then: rutas declaradas fuera del grupo web (sin sesión ni cookies):
        // la que sirve Bootstrap, compartida por los ejemplos 15 a 28
        then: fn () => require __DIR__.'/../../common/bootstrap.php')
    ->withMiddleware(function (Middleware $middleware): void {
        // el idioma de cada solicitud (véase app/Http/Middleware/SetLanguage.php)
        $middleware->web(append: SetLanguage::class);
    })
    ->withExceptions()
    ->booted(function () {
        // DIRECTIVAS "caseras": @money($price), @longDate($day). Una directiva
        // recibe el TEXTO de su parámetro, y devuelve el código PHP que la reemplazará
        Blade::directive('money', fn (string $expression) =>
            "<?php echo e(\\App\\Helpers\\Formats::money($expression)); ?>");
        Blade::directive('longDate', fn (string $expression) =>
            "<?php echo e(\\App\\Helpers\\Formats::longDate($expression)); ?>");
    })
    ->create();
  • Línea 19: el middleware se agrega al final del grupo [web]: se ejecuta para todas las rutas de [routes/web.php], después de los middleware del grupo (sesión, cookies, etc.). El ejemplo 03 utilizaba [append], que agrega un middleware global que se ejecuta para todas las solicitudes, incluidas las de rutas externas al grupo [web];
  • Líneas 25–28: la fachada [Blade] registra dos directivas “personalizadas”: [@money(...)] y [@longDate(...)]. Una directiva se procesa cuando la vista se compila (ejemplo 13): su función recibe el texto escrito entre los paréntesis (por ejemplo, [$product->price, 'USD']) y devuelve el código [PHP], que reemplazará a la directiva en la vista compilada. Aquí se llama al método correspondiente de ***[Formats]***, cuyo resultado se escapa ([e]***) y se escribe ([echo]***). En una cadena entre comillas, [\\] representa una sola [\];
  • las directivas se almacenan en una función [booted] (ejemplo 15) una vez que la aplicación ha arrancado: la fachada [Blade] solo se puede utilizar en ese momento.

Como generan código compilado, las directivas requieren una precaución: después de modificar una directiva, hay que borrar las vistas compiladas (comando [php artisan view:clear]) para que las vistas se recompilen con la nueva versión.

4.4.4. El controlador: app/Http/Controllers/PagesController.php

<?php
// app/Http/Controllers/PagesController.php: dos páginas

namespace App\Http\Controllers;

use App\Models\Product;
use Brick\Math\BigDecimal;
use Carbon\CarbonImmutable;
use Illuminate\View\View;

class PagesController
{
    public function home(): View
    {
        return view('pages.home', ['today' => CarbonImmutable::today()]);
    }

    public function products(): View
    {
        return view('pages.products', ['products' => [
            new Product('keyboard', BigDecimal::of('25'), 12),
            new Product('mouse', BigDecimal::of('12.5'), 0),
            new Product('screen', BigDecimal::of('1149.9'), 3),
        ]]);
    }
}

Las acciones pasan valores sin procesar a las vistas: una fecha ([CarbonImmutable::today()], la fecha de hoy a medianoche) y números decimales. El formato lo manejan las vistas. La clase [Product] combina un nombre, un precio (un [BigDecimal], véase el ejemplo 06) y un nivel de existencias. Las rutas se llaman [home] y [products].

4.4.5. Las vistas

1
2
3
4
5
6
{{-- un componente: un enlace de la barra de navegación, que recibe la clase [active]
     si la página actual está bajo la ruta [path]. request(): la
     solicitud actual, disponible en todas las vistas; $slot: el contenido colocado
     entre las etiquetas del componente --}}
@props(['href', 'path'])
<a @class(['nav-link', 'active' => request()->is($path)]) href="{{ $href }}">{{ $slot }}</a>
  • línea 5: un componente que crea un enlace en la barra de navegación. Al enlace de la página actual se le asigna la clase [active] de [Bootstrap], que lo resalta;
  • Línea 6: la directiva [@class] genera el atributo [class] de una etiqueta a partir de un arreglo: una clase escrita sola (['nav-link']) siempre está presente; una clase escrita como clave (['active' => condition]) está presente solo si la condición es verdadera. La función [request()] devuelve la solicitud actual; su método [is] compara la ruta de la URL con un patrón, donde [*] coincide con cualquier secuencia de caracteres. La variable [$slot] contiene el contenido entre las etiquetas de apertura y de cierre del componente ([<x-link ...>Products</x-link>]).
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <span class="navbar-brand">Helpers</span>
  <div class="navbar-nav">
    {{-- 1. una condición escrita en la vista --}}
    <a class="nav-link{{ request()->is('/') ? ' active' : '' }}" href="/">Home</a>
    {{-- 2. the [link] component --}}
    <x-link href="/products" path="products*">Products</x-link>
    {{-- 3. route() construye la URL de una ruta con nombre; un parámetro que no es
         parámetro de la ruta se agrega al final de la URL: /products?lang=fr --}}
    <a class="nav-link" href="{{ route('products', ['lang' => 'fr']) }}">Produits (fr)</a>
  </div>
</nav>
  • línea 5: lo mismo, escrito directamente en la vista, sin componente, mediante el operador ternario. [request()->is('/')] solo reconoce la página de inicio. El componente evita repetir la condición en cada enlace;
  • línea 7: el uso del componente;
  • línea 10: un parámetro de [route] que no es un parámetro de ruta se agrega a la URL como parámetro de consulta: [/products?lang=fr].
1
2
3
{{-- una insignia (badge) de Bootstrap: verde si el producto está en existencia, roja en caso contrario --}}
@props(['stock'])
<span @class(['badge', 'text-bg-success' => $stock > 0, 'text-bg-danger' => $stock <= 0])>{{ $stock > 0 ? "$stock in stock" : 'sold out' }}</span>
  • Línea 3: una insignia de [Bootstrap], verde ([text-bg-success]) o roja ([text-bg-danger]) según las existencias, mediante [@class]. El texto de la insignia se elige con el operador ternario; ["$stock in stock"] es una cadena interpolada.
@extends('layout')
@section('title', 'Home')

@section('content')
  <h1>Home</h1>
  {{-- the "home-made" @longDate directive --}}
  <p>Today is @longDate($today).</p>
  {{-- app()->getLocale(): el idioma de la solicitud, establecido por el middleware SetLanguage --}}
  <p>Formatting language: {{ app()->getLocale() }}
    (<a href="/?lang=fr">in French</a>, <a href="/">in English</a>)</p>
@endsection
  • línea 7: la llamada a la directiva “home”;
  • línea 9: la función [app()] devuelve la aplicación, y [getLocale()] establece su idioma para la solicitud actual.
@extends('layout')
{{-- @use: el equivalente, en una vista, de la instrucción use de PHP --}}
@use('App\Helpers\Formats')
@section('title', 'Products')

@section('content')
  <h1>Products</h1>
  <table class="table table-sm w-auto">
    <thead><tr><th>Product</th><th>Price</th><th>Price in dollars</th><th>Stock</th></tr></thead>
    <tbody>
      @foreach ($products as $product)
        <tr>
          {{-- un método estático, luego una directiva, sin y luego con un parámetro --}}
          <td>{{ Formats::uppercase($product->name) }}</td>
          <td>@money($product->price)</td>
          <td>@money($product->price, 'USD')</td>
          {{-- el componente [badge] construye el HTML de la insignia --}}
          <td><x-badge :stock="$product->stock" /></td>
        </tr>
      @endforeach
    </tbody>
  </table>
@endsection
  • línea 3: la directiva [@use] importa una clase en la vista, igual que la instrucción [use] de un archivo [PHP];
  • línea 14: una llamada a un método estático, que actúa como una función;
  • Líneas 15–16: la directiva [@money], primero con su moneda predeterminada y luego con un parámetro;
  • línea 18: el uso del componente [badge].

La plantilla [layout.blade.php] es una versión simplificada de la del ejemplo 15.

4.4.6. Ejecución

Image

Image

La misma página, con el parámetro [?lang=fr]. Solo cambia el formato de los números; el texto en sí está escrito directamente en las vistas. El capítulo sobre internacionalización también traducirá el texto.

Image

Un extracto del HTML producido:

curl "http://localhost:8000/products?lang=en"
1
2
3
4
5
6
7
8
9
...
              <tr>
          <td>KEYBOARD</td>
          <td>€25.00</td>
          <td>$25.00</td>
          <td><span class="badge text-bg-success">12 in stock</span>
</td>
        </tr>
...

4.5. Ejemplo 17: un formulario GET

Un formulario HTML envía sus campos al servidor de una de dos maneras, según su atributo [method]:

  • [method="get"]: los campos se agregan a la URL como parámetros ([/search?keyword=le&genre=novel]). Este es el método que utiliza un formulario que realiza una consulta: una búsqueda o un filtro. La URL que contiene los resultados se puede guardar como marcador, compartir o recargar sin riesgo;
  • [method="post"]: los campos se incluyen en el cuerpo de la solicitud (véase el ejemplo 11). Este es el método que utiliza un formulario que modifica datos: un registro, una adición o una eliminación.

Este primer formulario es una búsqueda de libros.

4.5.1. El modelo: app/Models/Book.php y SearchModel.php

<?php
// app/Models/Book.php: un libro

namespace App\Models;

readonly class Book
{
    public function __construct(
        public string $title,
        public string $author,
        public string $genre,
    ) {
    }
}
<?php
// app/Models/SearchModel.php: el modelo de la vista: la entrada (para mostrarla
// de nuevo), los géneros, los resultados

namespace App\Models;

readonly class SearchModel
{
    /**
     * @param list<string> $genres
     * @param list<Book> $results
     */
    public function __construct(
        public string $keyword,
        public string $genre,
        public array $genres,
        public array $results,
    ) {
    }
}
  • Líneas 14–17: la plantilla de vista contiene la entrada del usuario (que el formulario mostrará), la lista de géneros sugeridos y los resultados.

4.5.2. El controlador: app/Http/Controllers/BooksController.php

<?php
// app/Http/Controllers/BooksController.php: un formulario de búsqueda, enviado por GET

namespace App\Http\Controllers;

use App\Models\Book;
use App\Models\SearchModel;
use Illuminate\Http\Request;
use Illuminate\View\View;

class BooksController
{
    // CONSTANTES de clase: los datos, escritos en el código para el ejemplo
    private const GENRES = ['novel', 'poetry', 'drama'];

    /** @return list<Book> */
    private static function books(): array
    {
        return [
            new Book('Le Rouge et le Noir', 'Stendhal', 'novel'),
            new Book('Les Fleurs du mal', 'Baudelaire', 'poetry'),
            new Book('Madame Bovary', 'Flaubert', 'novel'),
            new Book('Alcools', 'Apollinaire', 'poetry'),
            new Book('Le Cid', 'Corneille', 'drama'),
        ];
    }

    // GET / y GET /search?keyword=...&genre=...: el formulario Y sus resultados
    public function search(Request $request): View
    {
        // string: el parámetro, en forma de cadena ('' si falta)
        $keyword = $request->string('keyword')->value();
        $genre = $request->string('genre')->value();
        $word = mb_strtolower($keyword);
        $results = array_values(array_filter(self::books(), fn (Book $book) =>
            ($word === '' || str_contains(mb_strtolower($book->title), $word)
                || str_contains(mb_strtolower($book->author), $word))
            && ($genre === '' || $book->genre === $genre)));
        return view('books.search', [
            'model' => new SearchModel($keyword, $genre, self::GENRES, $results),
        ]);
    }
}
  • Línea 14: una constante de clase privada llamada [self::GENRES] ([self] hace referencia a la clase actual). Una constante no puede contener objetos: por lo tanto, los libros los proporciona un método estático (líneas 17–25). En una aplicación real, provendrían de una base de datos;
  • líneas 32–33: los campos del formulario se leen como parámetros de la URL (ejemplo 07). El método [string] devuelve el parámetro como un objeto [Stringable] de tipo [Laravel] (una cadena enriquecida con métodos), que está vacío si falta el parámetro; [value()] extrae de él la cadena [PHP];
  • Líneas 35–38: filtrado. La función [array_filter] conserva los elementos de un arreglo para los cuales la función dada devuelve [true]: se conserva un libro si la palabra clave está vacía o aparece en su título o autor (en minúsculas en ambos lados), y si el género está vacío o coincide con el suyo. [array_filter] conserva las claves de los elementos seleccionados (0, 2...): [array_values] las vuelve a numerar a partir de 0;
  • líneas 39–41: la plantilla de vista.

La tabla de rutas asocia dos entradas de URL con la misma acción: en la primera visita ([/]), no hay parámetros y se muestran todos los libros.

1
2
3
4
5
6
7
8
9
<?php
// routes/web.php: las rutas del ejemplo 17

use App\Http\Controllers\BooksController;
use Illuminate\Support\Facades\Route;

// dos rutas para la misma acción
Route::get('/', [BooksController::class, 'search']);
Route::get('search', [BooksController::class, 'search']);

4.5.3. La vista: resources/views/books/search.blade.php

@extends('layout')

@section('content')
  <h1 class="h3">Book search</h1>
  {{-- method="get": los campos se envían en la URL (?keyword=...&genre=...) --}}
  <form method="get" action="/search" class="row g-2 align-items-end mb-3">
    <div class="col-auto">
      <label class="form-label" for="keyword">Title or author</label>
      {{-- value: the field displays again what was typed (escaped by {{ }}) --}}
      <input class="form-control" id="keyword" name="keyword" value="{{ $model->keyword }}">
    </div>
    <div class="col-auto">
      <label class="form-label" for="genre">Genre</label>
      <select class="form-select" id="genre" name="genre">
        <option value="">(all)</option>
        @foreach ($model->genres as $genre)
          {{-- @selected: el atributo booleano selected, escrito si la condición es verdadera, omitido en caso contrario --}}
          <option value="{{ $genre }}" @selected($genre === $model->genre)>{{ $genre }}</option>
        @endforeach
      </select>
    </div>
    <div class="col-auto">
      <button class="btn btn-primary" type="submit">Search</button>
    </div>
  </form>
  <p>{{ count($model->results) }} book(s) found.</p>
  <ul>
    @foreach ($model->results as $book)
      <li><i>{{ $book->title }}</i>, {{ $book->author }} ({{ $book->genre }})</li>
    @endforeach
  </ul>
@endsection
  • Línea 6: la etiqueta [<form>]. El atributo [action] es la URL a la que se envía el formulario; [method="get"] coloca los campos dentro de la URL. Las clases de [Bootstrap] disponen los campos en una sola línea;
  • Línea 8: una etiqueta de campo. Su atributo [for] especifica el identificador ([id]) del campo que describe: al hacer clic en la etiqueta se coloca el cursor en el campo, y los lectores de pantalla leen la etiqueta junto con el campo;
  • línea 10: un campo de entrada. Su atributo [name] es el nombre del parámetro enviado al servidor: este es el vínculo entre el formulario y la acción ([$request->string('keyword')]). El atributo [value] es el valor mostrado: la entrada anterior, vuelta a mostrar (y escapada por [{{ }}], lo cual es esencial en un atributo: una entrada que contenga una comilla ["] cerraría el atributo de lo contrario);
  • líneas 14–20: una lista desplegable. Cada [<option>] tiene un valor ([value]), que se envía al servidor, y un texto, que se muestra. La primera opción, con un valor vacío, significa “todos los géneros”;
  • línea 18: la opción seleccionada en la solicitud anterior recibe el atributo [selected]. Se trata de un atributo booleano: basta con su presencia; no tiene valor. La directiva [@selected(condition)] lo establece si la condición es verdadera y no establece nada en caso contrario. De manera similar, existen [@checked], [@disabled], [@readonly], y [@required];
  • línea 23: el botón de envío;
  • línea 26: el número de resultados.

4.5.4. Ejecución

Image

Escriba [le] y seleccione el tipo [novel]:

Image

La URL de la página de resultados contiene los campos del formulario: [/search?keyword=le&genre=novel]. La respuesta del formulario:

curl "http://localhost:8000/search?keyword=le&genre=novel"
...
  <form method="get" action="/search" class="row g-2 align-items-end mb-3">
    <div class="col-auto">
      <label class="form-label" for="keyword">Title or author</label>
      <input class="form-control" id="keyword" name="keyword" value="le">
    </div>
    <div class="col-auto">
      <label class="form-label" for="genre">Genre</label>
      <select class="form-select" id="genre" name="genre">
        <option value="">(all)</option>
          <option value="novel" selected>novel</option>
          <option value="poetry" >poetry</option>
          <option value="drama" >drama</option>
              </select>
    </div>
...
  </form>
  <p>1 book(s) found.</p>
  <ul>
          <li><i>Le Rouge et le Noir</i>, Stendhal (novel)</li>
      </ul>
...

“Madame Bovary” no está seleccionada: “le” no aparece ni en el título ni en el nombre del autor.

4.6. Ejemplo 18: campos de formulario

Este ejemplo presenta todos los tipos de campos de un formulario HTML, que en este caso se envía mediante POST. Muestra cómo volver a mostrar cada tipo de campo junto con su valor actual, cómo envía el navegador los valores de cada campo y cómo verifica el servidor que un valor recibido es efectivamente una de las opciones disponibles. [Laravel] no tiene una biblioteca que defina formularios mediante clases (como [WTForms] y [Python]): los campos se escriben en HTML dentro de la vista, y las directivas de [Blade] ([@checked], [@selected]...) ayudan a renderizarlos.

4.6.1. El servicio de listas: app/Services/ListsService.php

<?php
// app/Services/ListsService.php: las listas ofrecidas por el formulario. En una
// aplicación real, provendrían de una base de datos.

namespace App\Services;

class ListsService
{
    // cada lista: un arreglo asociativo enviado valor => texto mostrado
    public function titles(): array
    {
        return ['Mr' => 'Mr', 'Mme' => 'Mme', 'Melle' => 'Melle'];
    }

    public function countries(): array
    {
        return ['fr' => 'France', 'be' => 'Belgium', 'ch' => 'Switzerland', 'ca' => 'Canada'];
    }

    public function hobbies(): array
    {
        return ['reading' => 'reading', 'music' => 'music', 'sport' => 'sport',
            'cinema' => 'cinema'];
    }

    public function languages(): array
    {
        return ['French' => 'French', 'English' => 'English', 'Spanish' => 'Spanish',
            'German' => 'German'];
    }
}

Las listas desplegables del formulario (títulos, países, pasatiempos, idiomas) las proporciona un servicio, siguiendo el modelo del ejemplo 06: en una aplicación real, provendrían de una base de datos. Cada lista es un arreglo asociativo: la clave es el valor enviado al servidor y el valor es el texto mostrado. El servicio es una clase concreta: el contenedor de [Laravel] sabe cómo crearla sin una declaración (ejemplo 06).

4.6.2. El controlador: app/Http/Controllers/FormController.php

<?php
// app/Http/Controllers/FormController.php: un formulario que usa todos los tipos de campos

namespace App\Http\Controllers;

use App\Services\ListsService;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;
use Illuminate\View\View;

class FormController
{
    // el contenedor inyecta el servicio de listas (véase el ejemplo 06)
    public function __construct(private ListsService $lists)
    {
    }

    // GET: el formulario, con valores iniciales (uno por campo)
    public function display(): View
    {
        $input = ['title' => 'Mme', 'country' => 'fr', 'languages' => ['French'], 'token' => 'A7X2'];
        return view('form.form', ['lists' => $this->lists, 'input' => $input]);
    }

    // POST: los campos enviados se validan y luego el formulario los muestra de nuevo
    public function process(Request $request): View
    {
        $l = $this->lists;
        // array_keys: los VALORES permitidos de cada lista (las claves de los arreglos)
        $validator = Validator::make($request->post(), [
            'title' => ['required', Rule::in(array_keys($l->titles()))],
            'birth_date' => 'nullable|date_format:Y-m-d',
            'hobbies' => 'array',
            'hobbies.*' => Rule::in(array_keys($l->hobbies())),
            'country' => ['required', Rule::in(array_keys($l->countries()))],
            'languages' => 'array',
            'languages.*' => Rule::in(array_keys($l->languages())),
        ]);
        // lo que el navegador envió realmente, parámetro por parámetro
        $received = [];
        foreach ($request->post() as $name => $value) {
            $received[] = "$name = [".implode(', ', (array) $value).']';
        }
        return view('form.form', [
            'lists' => $l,
            'input' => $request->post(),
            'received' => implode("\n", $received),
            'valid' => $validator->passes(),
            'errors' => $validator->errors(),
        ]);
    }
}
  • línea 15: el servicio se inyecta mediante el constructor;
  • líneas 20–23: los valores iniciales del formulario, un arreglo asociativo: un valor por campo (un arreglo para un campo de varios valores). La vista recibe estos valores en la variable [$input], junto con el servicio de listas;
  • líneas 31–39: se validan los campos recibidos. Los campos desplegables deben contener uno de los valores sugeridos: un usuario malintencionado podría enviar cualquier cosa, no solo lo que la página sugirió. [Rule::in(...)] genera la regla [in] (ejemplo 08) a partir de un arreglo de valores; en este caso, las claves de la lista ([array_keys]). Los campos múltiples se verifican elemento por elemento ([hobbies.*], ejemplo 10). [date_format:Y-m-d]: un campo [<input type="date">] intercambia sus valores con el servidor en el formato [yyyy-mm-dd], sea cual sea el formato en que el navegador lo muestre;
  • líneas 41–44: para el ejemplo, la lista de lo que el navegador envió realmente. [(array) $value] convierte un valor único en un arreglo de un elemento (un arreglo sigue siendo un arreglo); [implode] une los elementos de un arreglo en una cadena, separados por el primer parámetro;
  • líneas 45–51: el formulario se vuelve a mostrar con los valores recibidos ([$input]), lo que recibió el servidor, el resultado de la validación ([passes()], lo opuesto de [fails()]) y los errores, si los hay.

La tabla de rutas asocia la URL [/form] con la acción [display] para el método GET, y con la acción [process] para el método POST.

4.6.3. La vista: resources/views/form/form.blade.php

@extends('layout')

@section('content')
  <h1 class="h3">A complete form</h1>
  <form method="post" action="/form" style="max-width: 40rem">
    {{-- los campos ocultos: el token anti-CSRF de Laravel y nuestro campo [token] --}}
    @csrf
    <input type="hidden" name="token" value="{{ $input['token'] ?? '' }}">

    <div class="mb-2">
      <span class="form-label me-3">Title</span>
      {{-- radio buttons: same [name], a single value sent --}}
      @foreach ($lists->titles() as $value => $text)
        <div class="form-check form-check-inline">
          <input class="form-check-input" type="radio" id="title-{{ $loop->index }}" name="title"
                 value="{{ $value }}" @checked(($input['title'] ?? '') === $value)>
          <label class="form-check-label" for="title-{{ $loop->index }}">{{ $text }}</label>
        </div>
      @endforeach
    </div>

    <div class="row g-2 mb-2">
      <div class="col">
        <label class="form-label" for="name">Name</label>
        <input class="form-control" type="text" id="name" name="name" value="{{ $input['name'] ?? '' }}">
      </div>
      <div class="col">
        {{-- una contraseña NUNCA se reenvía en la página: sin atributo value --}}
        <label class="form-label" for="password">Password</label>
        <input class="form-control" type="password" id="password" name="password">
      </div>
      <div class="col">
        <label class="form-label" for="birth_date">Date of birth</label>
        <input class="form-control" type="date" id="birth_date" name="birth_date" value="{{ $input['birth_date'] ?? '' }}">
      </div>
    </div>

    <div class="mb-2">
      <span class="form-label me-3">Hobbies</span>
      {{-- casillas de verificación: el nombre hobbies[] hace que el valor recibido sea un ARREGLO (véase el ejemplo 10) --}}
      @foreach ($lists->hobbies() as $value => $text)
        <div class="form-check form-check-inline">
          <input class="form-check-input" type="checkbox" id="hobbies-{{ $loop->index }}" name="hobbies[]"
                 value="{{ $value }}" @checked(in_array($value, $input['hobbies'] ?? []))>
          <label class="form-check-label" for="hobbies-{{ $loop->index }}">{{ $text }}</label>
        </div>
      @endforeach
    </div>

    <div class="row g-2 mb-2">
      <div class="col">
        <label class="form-label" for="country">Country</label>
        <select class="form-select" id="country" name="country">
          @foreach ($lists->countries() as $value => $text)
            <option value="{{ $value }}" @selected(($input['country'] ?? '') === $value)>{{ $text }}</option>
          @endforeach
        </select>
      </div>
      <div class="col">
        <label class="form-label" for="languages">Spoken languages</label>
        {{-- multiple-selection list: several possible values, hence languages[] --}}
        <select class="form-select" id="languages" name="languages[]" multiple size="4">
          @foreach ($lists->languages() as $value => $text)
            <option value="{{ $value }}" @selected(in_array($value, $input['languages'] ?? []))>{{ $text }}</option>
          @endforeach
        </select>
      </div>
    </div>

    <div class="mb-2">
      <label class="form-label" for="comment">Comment</label>
      {{-- un área de texto: el valor va ENTRE las etiquetas --}}
      <textarea class="form-control" id="comment" name="comment" rows="2">{{ $input['comment'] ?? '' }}</textarea>
    </div>

    <button class="btn btn-primary" type="submit">Send</button>
  </form>

  {{-- isset: verdadero si la variable $received fue pasada a la vista (por la acción POST) --}}
  @isset($received)
    <h2 class="h5 mt-3">What the server received</h2>
    <pre class="bg-light p-2 border">{{ $received }}</pre>
    <p>Valid form: {{ $valid ? 'yes' : 'no' }}</p>
    {{-- $errors->messages(): field -> list of its error messages --}}
    <ul>
      @foreach ($errors->messages() as $field => $messages)
        <li>{{ $field }}: {{ implode(', ', $messages) }}</li>
      @endforeach
    </ul>
  @endisset
@endsection
  • línea 5: un formulario con método POST;
  • línea 7: la directiva [@csrf] escribe un campo oculto llamado [_token], que contiene el token anti-CSRF. Un ataque CSRF (*Cross-Site Request Forgery*) consiste en que un sitio malicioso engaña al navegador de la víctima para que envíe un formulario a nuestra aplicación. El navegador incluye las cookies de nuestra aplicación en la solicitud (y, por lo tanto, la sesión del usuario autenticado), lo que hace que la solicitud parezca legítima. La defensa: todos los formularios de nuestra aplicación contienen un token aleatorio vinculado a la sesión del usuario, que el sitio malicioso no puede conocer. El middleware [PreventRequestForgery] del grupo [web] (ejemplo 01) rechaza toda solicitud POST (así como PUT, PATCH y DELETE) cuyo token falte o sea inválido, incluso antes de que se llame a la acción: ninguna acción puede omitirlo. Es el que los ejemplos 02 y 11 excluyeron para sus solicitudes [curl];
  • línea 8: nuestro propio campo oculto;
  • líneas 13–19: un grupo de botones de opción, uno por título. Todos tienen el mismo atributo [name]: solo uno está seleccionado a la vez y solo se envía un valor. Cada botón tiene su propio identificador ([title-0], [title-1]...), generado mediante [$loop->index], al que hace referencia su etiqueta. La directiva [@checked] marca el botón cuyo valor coincide con el título actual;
  • línea 25: el campo de entrada del nombre; [?? ''] maneja el caso en que un nombre no está en el arreglo;
  • Línea 30: una contraseña nunca debe enviarse de ida y vuelta dentro de una página HTML: el campo no tiene el atributo [value]; siempre aparece vacío al mostrarse;
  • Líneas 41–47: casillas de verificación, con el estilo de los botones de opción. También comparten el mismo nombre; sin embargo, se pueden seleccionar varias casillas, y entonces el navegador envía varios valores: el nombre [hobbies[]] indica a [PHP] que los organice en un arreglo (ejemplo 10). La función [in_array] verifica si un valor está presente en un arreglo;
  • líneas 53–57: una lista desplegable, cuya opción actual se marca con [@selected];
  • línea 62: una lista de selección múltiple (atributo [multiple]), mostrada en cuatro líneas ([size]), cuyo nombre también termina con [[]];
  • línea 73: un campo de texto de dos líneas. Su valor se escribe entre sus etiquetas, no en un atributo;
  • Líneas 80–90: la directiva [@isset] verifica la existencia de una variable: [$received] solo fue pasada a la vista por la acción POST. [$errors->messages()] devuelve, para cada campo inválido, una lista de sus mensajes de error (ejemplo 09).

4.6.4. Ejecución

Image

Se ven los valores predeterminados: el botón de opción “Mme”, el país “France” y el idioma “French”. El HTML produce (extractos):

<input type="hidden" name="_token" value="mjFN6z3WBF79ZEA8EWgmoX3Hio8DjjmG7hGQlGax" autocomplete="off">
<input type="hidden" name="token" value="A7X2">
...
<input class="form-check-input" type="radio" id="title-1" name="title"
       value="Mme" checked>
<label class="form-check-label" for="title-1">Mme</label>
...
<input class="form-control" type="date" id="birth_date" name="birth_date" value="">
...
<input class="form-check-input" type="checkbox" id="hobbies-0" name="hobbies[]"
       value="reading" >
<label class="form-check-label" for="hobbies-0">reading</label>
...
<select class="form-select" id="country" name="country">
  <option value="fr" selected>France</option>
  <option value="be" >Belgium</option>
...
<select class="form-select" id="languages" name="languages[]" multiple size="4">
  <option value="French" selected>French</option>
...
<textarea class="form-control" id="comment" name="comment" rows="2"></textarea>

El token anti-CSRF es una cadena aleatoria de 40 caracteres, almacenada en la sesión del usuario (ejemplo 20). Llenemos el formulario y enviémoslo:

Image

La página muestra lo que recibió el servidor: un parámetro por campo, con varios valores para las casillas de verificación y la lista desplegable; la contraseña se envió, pero no vuelve a mostrarse en su campo. El campo oculto [token] se devolvió exactamente como estaba: así se envía y se recibe información que el usuario no puede ver (el caso de estudio lo utiliza para el número de versión de un registro). Sin embargo, un campo oculto no es un campo protegido: el usuario puede modificarlo con las herramientas de desarrollo de su navegador, y el servidor debe validarlo igual que cualquier otro campo. También se observa que el token anti-CSRF ([_token]) figura entre los campos recibidos.

Ahora enviemos un formulario sin token, con [curl]:

curl -i -d "name=Martin&country=xx" http://localhost:8000/form
1
2
3
4
5
6
7
8
HTTP/1.1 419 unknown status
Content-Type: text/html; charset=utf-8

<!DOCTYPE html>
<html lang="en">
...
        <title>Page Expired</title>
...

La solicitud es rechazada por el middleware [PreventRequestForgery] con el código de estado 419, específico de [Laravel] (*Page Expired*: este es el mensaje que ve un usuario cuya sesión expiró entre el momento en que se mostró el formulario y el momento en que se envió). Para resolverlo, [curl] debe comportarse como un navegador: primero solicitar el formulario, conservando la cookie de sesión (opción [-c], que guarda en un archivo las cookies recibidas), y luego reenviar la cookie (opción [-b]) y el token leído de la página:

curl -c cookies.txt http://localhost:8000/form
curl -b cookies.txt -d "_token=WkdoQuahsZxMScUg5UJ5UOwWN4nDF8l3Niyce9WK&name=Martin&country=xx" http://localhost:8000/form
...
      <h2 class="h5 mt-3">What the server received</h2>
    <pre class="bg-light p-2 border">_token = [WkdoQuahsZxMScUg5UJ5UOwWN4nDF8l3Niyce9WK]
name = [Martin]
country = [xx]</pre>
    <p>Valid form: no</p>
    <ul>
              <li>title: The title field is required.</li>
              <li>country: The selected country is invalid.</li>
          </ul>
...

(el token es el de la página recibida por el primer comando). Dos errores: el país [xx] no figura entre las opciones; no se envió ningún título. Los mensajes son los predeterminados de Laravel: el ejemplo siguiente los personaliza.

4.7. Ejemplo 19: validación de formularios

Un formulario de registro, donde cada campo tiene sus propias reglas de validación. Si ocurre un error, el formulario se vuelve a mostrar con la entrada del usuario y un mensaje debajo de cada campo inválido. Este ejemplo utiliza el enfoque estándar de [Laravel]: una solicitud de formulario (form request, ejemplo 08) valida los campos antes de la acción; si ocurre un error, [Laravel] redirige a la página del formulario, conservando la entrada del usuario y los errores para la siguiente solicitud.

4.7.1. El formulario: app/Http/Requests/RegistrationRequest.php

<?php
// app/Http/Requests/RegistrationRequest.php: los campos del formulario y sus restricciones

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class RegistrationRequest extends FormRequest
{
    // las reglas de cada campo. Los espacios que rodean la entrada ya fueron
    // eliminados por el middleware TrimStrings, y una entrada vacía se reemplazó por null
    public function rules(): array
    {
        return [
            'name' => 'required|max:20',
            // email:filter: la verificación de la función filter_var de PHP, que
            // exige un nombre de dominio completo (example.com, y no example)
            'email' => 'required|email:filter',
            'age' => 'required|integer|between:18,120',
            'password' => 'required|min:6',
            // una regla sobre DOS campos: same compara este campo con otro
            'confirmation' => 'required|same:password',
        ];
    }

    // los mensajes de error, campo.regla => mensaje
    public function messages(): array
    {
        return [
            'name.required' => 'The name is required.',
            'name.max' => 'The name must not exceed 20 characters.',
            'email.required' => 'The email address is required.',
            'email.email' => 'Invalid email address.',
            'age.required' => 'The age is required.',
            'age.between' => 'The age must be between 18 and 120 years.',
            'password.required' => 'The password is required.',
            'password.min' => 'The password must have at least 6 characters.',
            'confirmation.required' => 'The confirmation is required.',
            'confirmation.same' => 'The confirmation does not match the password.',
        ];
    }
}
  • Líneas 12–23: las reglas de validación de cada campo (ejemplo 08). Los espacios que rodean la entrada ya fueron eliminados por el middleware [TrimStrings] (ejemplo 08): un nombre compuesto por espacios se convierte en una cadena vacía y luego en [null], y será rechazado por [required];
  • Línea 18: la regla [email] acepta variantes, que determinan qué validación se aplica. De forma predeterminada, sigue el estándar de direcciones de correo electrónico, que acepta [martin@example] (un nombre de host sin dominio). [email:filter] utiliza la función [filter_var] de [PHP] (ejemplo 07), que exige un nombre de dominio completo ([example.com]);
  • línea 19: [integer] seguida de [between:18,120];
  • Línea 22: una regla que se aplica a dos campos: [same:password] compara el valor de un campo con el de otro campo. [Laravel] también ofrece la regla [confirmed], que, aplicada al campo [password], exigiría un campo llamado [password_confirmation];
  • Líneas 27–40: el método [messages] proporciona mensajes específicos de este formulario. Cada clave designa un campo y una regla ([name.required]); una clave simple como [required] se aplicaría a todos los campos. Estos mensajes tienen prioridad sobre los de los archivos de idioma (ejemplo 09).

Los mensajes que la clase no proporciona provienen del archivo [lang/en/validation.php] (el archivo [.env] establece el idioma en [en]; véase el ejemplo 09):

1
2
3
4
5
6
<?php
// lang/en/validation.php: los mensajes que la clase RegistrationRequest no
// proporciona por sí misma
return [
    'integer' => 'An integer is expected.',
];

Este es el caso del mensaje de la regla [integer], que solo se muestra si se escribe algo distinto de un número en el campo de edad, algo que un navegador no hace (lo veremos con [curl]).

4.7.2. El controlador: app/Http/Controllers/RegistrationController.php

<?php
// app/Http/Controllers/RegistrationController.php: un formulario validado por el servidor

namespace App\Http\Controllers;

use App\Http\Requests\RegistrationRequest;
use Illuminate\Http\Request;
use Illuminate\View\View;

class RegistrationController
{
    // GET /register: el formulario; ?html5=true: dejamos que el navegador
    // lo valide antes de enviarlo
    public function display(Request $request): View
    {
        return view('registration.registration', ['html5' => $request->query('html5') === 'true']);
    }

    // POST /register: la acción se invoca solo si el formulario es VÁLIDO.
    // De lo contrario, Laravel REDIRIGE a la página del formulario, conservando la entrada y
    // los errores para la siguiente solicitud (véanse old y @error en las vistas)
    public function register(RegistrationRequest $request): View
    {
        return view('registration.welcome', ['registration' => $request->validated()]);
    }
}
  • líneas 14–17: la visualización del formulario. El parámetro [?html5=true] activa la validación del navegador (véase más abajo);
  • líneas 22–25: la acción solo acepta formularios válidos: la solicitud de formulario [RegistrationRequest] fue validada antes de que se la llamara (ejemplo 08). Muestra la página de bienvenida con los datos validados. (El ejemplo siguiente mostrará que es mejor redirigir después de un POST exitoso.)

¿Y un formulario inválido? Nunca llega a la acción. La solicitud de formulario lanza una [ValidationException] (ejemplo 08), que [Laravel] maneja de la siguiente manera para una solicitud proveniente de un navegador: almacena los errores y los valores ingresados (excepto las contraseñas) en la sesión del usuario y luego responde con una redirección a la página anterior, la del formulario. El navegador solicita de inmediato esta página de nuevo (mediante un GET), y la vista del formulario recupera los errores y la entrada del usuario, que la sesión proporciona una sola vez (veremos este mecanismo de datos “flash” en el ejemplo siguiente). El formulario se vuelve a mostrar, así, mediante su acción GET y no mediante la acción POST: este es ya el patrón Post/Redirect/Get del ejemplo siguiente, aplicado a los errores.

4.7.3. Un campo reutilizable: resources/views/components/field.blade.php

Cada campo se muestra de la misma manera: una etiqueta, el campo de entrada y, en caso de error, la zona delineada en rojo y el mensaje debajo. Un componente evita tener que escribir esto cinco veces:

{{-- un campo de entrada, con su etiqueta y su PRIMER mensaje de error.
     old($name): la entrada anterior, conservada por Laravel después de un
     formulario inválido; $attributes: los demás atributos dados al componente (required,
     min, max...), copiados a la etiqueta input --}}
@props(['name', 'label', 'type' => 'text'])
<div class="mb-2">
  <label class="form-label" for="{{ $name }}">{{ $label }}</label>
  <input {{ $attributes->class(['form-control', 'is-invalid' => $errors->has($name)]) }}
         type="{{ $type }}" id="{{ $name }}" name="{{ $name }}"
         @if ($type !== 'password') value="{{ old($name) }}" @endif>
  {{-- @error: el bloque se muestra solo si el campo tiene un error, cuyo
       primer mensaje está en la variable $message --}}
  @error($name)
    <div class="invalid-feedback">{{ $message }}</div>
  @enderror
</div>
  • línea 5: los parámetros del componente: el nombre del campo, su etiqueta y su tipo, [text] de forma predeterminada;
  • línea 8: la variable [$attributes] contiene los atributos asignados al componente que no son parámetros declarados por [@props] (aquí, [required], [min], [max]...): al escribirla en la etiqueta, los copia. Su método [class] le agrega el atributo [class], de forma similar a la directiva [@class] (ejemplo 16): la clase [is-invalid] de [Bootstrap] delinea el campo en rojo si contiene un error. La variable [$errors] está disponible en todas las vistas: es una “bolsa” de mensajes (ejemplo 09), que contiene los errores del formulario anterior almacenados en la sesión, o una bolsa vacía; [has] verifica si hay errores en un campo;
  • Línea 10: la función [old] devuelve el valor ingresado en el formulario anterior, almacenado en la sesión, o [null]. Un campo de tipo [password] no tiene el atributo [value] (ejemplo 18);
  • Líneas 13–15: el bloque [@error] ... [@enderror] solo se muestra si el campo contiene un error; en ese caso, su primer mensaje se almacena en la variable [$message]. El elemento [invalid-feedback] se muestra en rojo mediante [Bootstrap], debajo de una zona marcada con [is-invalid].

4.7.4. Las vistas

@extends('layout')

@section('content')
  <h1 class="h3">Registration</h1>
  @if ($html5)
    <p>Browser validation <b>enabled</b> - <a href="/register">disable it</a></p>
  @else
    <p>Browser validation <b>disabled</b> - <a href="/register?html5=true">enable it</a></p>
  @endif
  {{-- novalidate: el navegador ignora los atributos required, min... y
       envía el formulario tal cual; solo el servidor valida --}}
  <form method="post" action="/register" @if (! $html5) novalidate @endif>
    @csrf
    <x-field name="name" label="Name" required maxlength="20" />
    <x-field name="email" label="Email address" type="email" required />
    <x-field name="age" label="Age" type="number" required min="18" max="120" />
    <x-field name="password" label="Password" type="password" required minlength="6" />
    <x-field name="confirmation" label="Confirmation" type="password" required />
    <button class="btn btn-primary" type="submit">Register</button>
  </form>
@endsection
  • línea 12: el atributo [novalidate] desactiva la validación del navegador: el formulario se envía tal cual y solo el servidor lo valida. Esto es lo que queremos observar primero;
  • líneas 14–18: un componente por campo. Los atributos HTML5 ([required], [maxlength], [min], [max], [minlength], [type="email"]) permiten que el navegador verifique la entrada incluso antes de enviarla (lo veremos más adelante). [Laravel] no los deriva de las reglas de validación: se escriben en la vista y deben mantenerse coherentes con las reglas.
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Registration</title>
  <link rel="stylesheet" href="{{ route('bootstrap', 'css/bootstrap.min.css') }}">
  <link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
  <div class="container py-3" style="max-width: 36rem">
    <main>
      @yield('content')
    </main>
    {{-- el error global, en la parte inferior de la página, sobre un fondo rosa claro. $errors: los errores
         del formulario anterior, disponibles en todas las vistas --}}
    @if ($errors->any())
      <div class="error-area" role="alert">The form contains errors.</div>
    @endif
  </div>
</body>
</html>
  • líneas 16–18: un mensaje general al final de la página si el formulario anterior contenía errores ([any()] verifica si la bolsa contiene al menos un mensaje), en una zona cuyo estilo está definido por [public/css/styles.css] (ejemplo 15). El atributo [role="alert"] lo señala a los lectores de pantalla.
1
2
3
4
5
6
7
8
@extends('layout')

@section('content')
  {{-- $registration: the validated data --}}
  <h1 class="h3">Welcome {{ $registration['name'] }}</h1>
  <p>Your registration is saved: address <b>{{ $registration['email'] }}</b>,
    age <b>{{ $registration['age'] }}</b> years.</p>
@endsection

[$registration] contiene los datos validados: el nombre sin espacios y la edad (una cadena; véase el ejemplo 08).

4.7.5. Ejecución

Enviemos un formulario lleno de errores: un nombre compuesto por espacios, una dirección de correo sin dominio completo, una edad de 12, una contraseña demasiado corta y una confirmación diferente:

Image

La entrada se conservó (excepto las contraseñas) y cada error se señala debajo de su campo correspondiente. La URL es la del formulario, y [/register] indica que la página fue mostrada por la acción GET después de la redirección. Con [curl], proporcionando el token anti-CSRF como en el ejemplo 18, vemos esta redirección:

curl -i -b cookies.txt -c cookies.txt -d "_token=...&name=Martin&email=martin@example.com&age=abc&password=abcdef&confirmation=abcdef" http://localhost:8000/register
1
2
3
4
HTTP/1.1 302 Found
Location: http://localhost:8000/register
Content-Type: text/html; charset=utf-8
...

También se puede enviar algo que un navegador no enviaría, como una edad no numérica. La página siguiente ([curl -b cookies.txt http://localhost:8000/register]) muestra el campo de edad, con su entrada y el mensaje de la regla [integer], tomado del archivo de idioma:

1
2
3
4
  <input class="form-control is-invalid" required="required" min="18" max="120"
         type="number" id="age" name="age"
          value="abc" >
      <div class="invalid-feedback">An integer is expected.</div>

También vemos los atributos HTML5 copiados por [$attributes]: [required] (escrito como [required="required"], una forma equivalente), [min], [max].

4.7.6. Validación en el navegador

Quitemos el atributo [novalidate] siguiendo el enlace “Enable” (parámetro [?html5=true]). El navegador verifica entonces los atributos [required], [type="email"], [min], [maxlength]... antes de enviar el formulario, y muestra sus propios mensajes en un globo de ayuda debajo del primer campo inválido (“Please fill in this field”, “The value must be greater than or equal to 18”, etc.): el formulario no se envía mientras haya un error.

Esta validación es cómoda para el usuario: es inmediata, sin idas y vueltas con el servidor. Pero no reemplaza la validación del lado del servidor: un usuario puede desactivarla, y un programa como [curl] la ignora por completo. La regla es absoluta: el servidor siempre valida; la validación en el navegador es solo una comodidad adicional.

Por fin, una entrada correcta. El nombre, escrito con espacios a ambos lados, fue limpiado por el middleware [TrimStrings]:

Image

4.8. Ejemplo 20: el patrón Post/Redirect/Get

Cuando una acción POST devuelve una página, esa página es el resultado de un POST. Si el usuario actualiza la página (presionando [F5]), el navegador vuelve a enviar la solicitud POST, tras una advertencia que pocas personas leen: el comando se envía dos veces y el mensaje se publica dos veces. El patrón Post/Redirect/Get (PRG) evita este problema: una acción POST exitosa no devuelve una página; responde con una redirección (ejemplo 04) a una página GET, que el navegador solicita de inmediato. Recargar esta página simplemente vuelve a ejecutar la acción GET.

Queda un problema: la página GET querría mostrar un mensaje (“la tarea ha sido agregada”), pero es la acción POST la que conoce este mensaje, y no puede pasar una variable a una solicitud que aún no ha ocurrido. La solución: el mensaje flash, almacenado en la sesión por la acción POST, se conserva hasta la siguiente solicitud, se muestra y luego se descarta. Este es el mecanismo que [Laravel] ya utilizaba, en el ejemplo 19, para los errores de formulario.

4.8.1. El servicio: app/Services/TasksService.php

<?php
// app/Services/TasksService.php: la lista de tareas, compartida por todos los
// usuarios. En PHP, los objetos no sobreviven a la solicitud: la lista se
// almacena en la CACHÉ de Laravel (aquí, un archivo de la carpeta storage/framework/cache)

namespace App\Services;

use Illuminate\Support\Facades\Cache;

class TasksService
{
    private const KEY = 'tasks';

    /** @return list<string> */
    public function list(): array
    {
        // el valor almacenado bajo la clave [tasks], o la lista inicial
        return Cache::get(self::KEY, ['Read chapter 3']);
    }

    public function add(string $label): void
    {
        // varias solicitudes pueden ejecutarse AL MISMO TIEMPO (el servidor las atiende
        // en varios procesos): un bloqueo garantiza que solo una a la
        // vez lea, modifique y reescriba la lista. block(5, ...) espera el bloqueo 5
        // segundos como máximo, ejecuta la función y luego libera el bloqueo
        Cache::lock('tasks-lock', 10)->block(5, function () use ($label) {
            $tasks = $this->list();
            $tasks[] = $label;
            // forever: el valor se conserva sin límite de tiempo
            Cache::forever(self::KEY, $tasks);
        });
    }
}

La lista de tareas es compartida por todos los usuarios y debe persistir de una solicitud a la siguiente. En [Java], [C#] o [Python], se mantendría en memoria dentro de un único servicio. En [PHP], esto es imposible: como vimos en los ejemplos 01 y 06, nada sobrevive a la solicitud. Por lo tanto, la lista debe almacenarse fuera de [PHP]: en una base de datos, en un archivo... o en la caché de [Laravel], que es la que utilizamos aquí.

  • Línea 18: la interfaz [Cache] proporciona acceso a la caché de la aplicación: un almacén de pares clave→valor. El archivo [.env] de los ejemplos almacena estos datos en archivos dentro de la carpeta [storage/framework/cache] ([CACHE_STORE=file], ejemplo 01); en producción, se prefiere un servidor dedicado, como [Redis]. [get] devuelve el valor almacenado bajo una clave, o el valor predeterminado proporcionado como segundo parámetro. Se puede almacenar cualquier valor (en este caso, un arreglo de cadenas): [Laravel] lo serializa, es decir, lo convierte en texto, mediante la función [serialize] de [PHP];
  • Líneas 27–32: el servidor de desarrollo, al igual que un servidor de producción, puede procesar varias solicitudes al mismo tiempo, en varios procesos (la variable de entorno [PHP_CLI_SERVER_WORKERS] establece el número de procesos de [php artisan serve]). Dos inserciones simultáneas podrían leer la misma lista, agregar cada una su propia tarea y luego escribirla de nuevo: la segunda escritura sobrescribiría la primera tarea. Un bloqueo garantiza que solo una solicitud a la vez ejecute el código que protege: [Cache::lock('tasks-lock', 10)] crea un bloqueo con nombre (que también se almacena en la caché) que expira después de 10 segundos como máximo (por si la solicitud que lo mantiene terminara abruptamente); [block(5, function)] espera hasta 5 segundos a que el bloqueo esté disponible, lo adquiere, ejecuta la función y luego lo libera. La palabra clave [use] en una función anónima le da acceso a una variable de la función que la contiene (aquí, [$label]); una función flecha, en cambio, ve automáticamente esas variables;
  • Línea 31: [forever] almacena un valor de manera indefinida; [put(key, value, seconds)] lo almacenaría durante una duración específica.

4.8.2. El controlador: app/Http/Controllers/TasksController.php

<?php
// app/Http/Controllers/TasksController.php: el patrón Post / Redirect / Get

namespace App\Http\Controllers;

use App\Services\TasksService;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\View\View;

class TasksController
{
    public function __construct(private TasksService $tasks)
    {
    }

    // GET /tasks: la lista y el formulario de adición
    public function display(): View
    {
        return view('tasks.tasks', ['tasks' => $this->tasks->list()]);
    }

    // POST /tasks: el patrón Post / Redirect / Get
    public function add(Request $request): View|RedirectResponse
    {
        $label = $request->string('label')->value();
        if ($label === '' || mb_strlen($label) > 40) {
            // entrada no válida: mostramos la página de nuevo, sin redirección
            return view('tasks.tasks', ['tasks' => $this->tasks->list(),
                'label' => $label,
                'error' => 'The label must have 1 to 40 characters.']);
        }
        $this->tasks->add($label);
        // sin página: una redirección a la página GET; with deja un mensaje "flash"
        // en la sesión: sobrevivirá a la redirección, para la SIGUIENTE solicitud
        return redirect()->route('tasks')->with('message', "The task [$label] has been added.");
    }

    // POST /tasks/without-prg: el contraejemplo (una página como respuesta al POST)
    public function addWithoutPrg(Request $request): View
    {
        $this->tasks->add($request->string('label')->value() ?: '(untitled)');
        return view('tasks.tasks', ['tasks' => $this->tasks->list(), 'withoutPrg' => true]);
    }
}
  • líneas 26–31: la entrada se valida manualmente para mantener el ejemplo sencillo. Una entrada inválida se vuelve a mostrar, sin redirección: no hay nada que proteger contra un envío duplicado, ya que no se ha modificado nada. [mb_strlen] cuenta los caracteres de una cadena UTF-8;
  • línea 36: la redirección a la página GET, llamada [tasks]. El método [with] de una redirección coloca un mensaje flash en la sesión: datos conservados solo para la siguiente solicitud;
  • líneas 40–43: el contraejemplo: una página en respuesta a un POST. El operador [?:] devuelve su operando izquierdo si es “verdadero” (aquí, una cadena no vacía) y el operando derecho en caso contrario.

La tabla de rutas:

<?php
// routes/web.php: las rutas del ejemplo 20

use App\Http\Controllers\TasksController;
use Illuminate\Support\Facades\Route;

Route::controller(TasksController::class)->group(function () {
    Route::get('tasks', 'display')->name('tasks');
    Route::post('tasks', 'add');
    Route::post('tasks/without-prg', 'addWithoutPrg');
});

4.8.3. Las vistas

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Tasks</title>
  <link rel="stylesheet" href="{{ route('bootstrap', 'css/bootstrap.min.css') }}">
  <link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
  <div class="container py-3" style="max-width: 36rem">
    {{-- el mensaje flash, en la parte superior de la página: dejado ANTES de la redirección; la sesión
         lo devuelve durante la siguiente solicitud y luego lo olvida --}}
    @session('message')
      <div class="alert alert-success" role="status">{{ $value }}</div>
    @endsession
    <main>
      @yield('content')
    </main>
    @isset($error)
      <div class="error-area" role="alert">{{ $error }}</div>
    @endisset
  </div>
</body>
</html>
  • Líneas 13–15: el bloque [@session('message')] ... [@endsession] solo se muestra si la sesión contiene una entrada [message], en cuyo caso su valor se almacena en la variable [$value]. La clase [alert alert-success] de [Bootstrap] muestra el mensaje en un recuadro verde.
@extends('layout')

@section('content')
  <h1 class="h3">My tasks</h1>
  <ol>
    @foreach ($tasks as $task)
      <li>{{ $task }}</li>
    @endforeach
  </ol>
  <form method="post" action="/tasks" class="d-flex gap-2">
    @csrf
    <input class="form-control" name="label" value="{{ $label ?? '' }}" placeholder="New task">
    <button class="btn btn-primary text-nowrap" type="submit">Add</button>
    {{-- formaction: este botón envía el MISMO formulario a otra dirección --}}
    <button class="btn btn-outline-secondary text-nowrap" type="submit" formaction="/tasks/without-prg">Add without PRG</button>
  </form>
  @isset($withoutPrg)
    <p class="text-danger mt-2">Page displayed in response to a POST: press F5 and the task will be added a second time.</p>
  @endisset
@endsection
  • Línea 15: el atributo [formaction] de un botón envía el formulario a una dirección distinta de la especificada por su atributo [action]: un único formulario puede así desencadenar dos acciones diferentes.

4.8.4. ¿Dónde se almacenan los mensajes flash?

Entre la solicitud POST y la solicitud GET posterior, el mensaje debe almacenarse en algún lugar: en la sesión del usuario. La sesión de [Laravel] se almacena en el servidor: el archivo [.env] de los ejemplos la almacena en un archivo dentro de la carpeta [storage/framework/sessions] ([SESSION_DRIVER=file]), con un archivo por usuario. El navegador, en cambio, recibe solo un ID de sesión en la cookie [example20_session] (el nombre se deriva de [APP_NAME]), que devuelve con cada solicitud. Examinemos esto con [curl], almacenando las cookies en un archivo (opciones [-c] y [-b], ejemplo 18) y proporcionando el token anti-CSRF:

curl -i -b cookies.txt -c cookies.txt -d "_token=...&label=Do%20the%20exercises" http://localhost:8000/tasks
1
2
3
4
5
6
HTTP/1.1 302 Found
Location: http://localhost:8000/tasks
Content-Type: text/html; charset=utf-8
Set-Cookie: XSRF-TOKEN=eyJpdiI6IjFJLzhDVy9CWndjODZNb2s3N2VMUnc9PSIsInZhbHVlIjoiT3JXZy96MmJROHUrYmZaNUFNbUFoM3d4...; expires=...; Max-Age=7200; path=/; samesite=lax
Set-Cookie: example20_session=eyJpdiI6IlMwK3R3ZkQ2TEhKUVZ4SW9saDVMNUE9PSIsInZhbHVlIjoiMVVnUTNvTHFL...; expires=...; Max-Age=7200; path=/; httponly; samesite=lax
...

La respuesta al POST es una redirección (código de estado 302, encabezado [Location]), acompañada de la cookie de sesión. Su valor está cifrado con la clave [APP_KEY] (este es el papel del middleware [EncryptCookies] del grupo [web]): el usuario no puede leerlo ni modificarlo. Una vez descifrado, contiene solo el ID de sesión (40 caracteres aleatorios), que es también el nombre del archivo de sesión en el servidor: [storage/framework/sessions/HNuWctWJ0HcPvmsAhFN5v3iCiw1SFFDMXv46F6og]. Este es ese archivo, tras la solicitud POST (mostrado en varias líneas):

1
2
3
4
a:4:{s:6:"_token";s:40:"X0omnUmKl13zVLUrzTdZy5mWN7R6fBaiOmfEUPpr";
     s:9:"_previous";a:2:{s:3:"url";s:27:"http://localhost:8000/tasks";s:5:"route";s:5:"tasks";}
     s:6:"_flash";a:2:{s:3:"old";a:1:{i:0;s:7:"message";}s:3:"new";a:0:{}}
     s:7:"message";s:43:"The task [Do the exercises] has been added.";}

Se trata de un arreglo [PHP] serializado: [a:4] indica un arreglo de 4 elementos, [s:6:"_token"] una cadena de 6 bytes... Contiene el token anti-CSRF de la sesión, la URL de la página anterior ([_previous], que utiliza la redirección a la página anterior del ejemplo 19), nuestro mensaje y la lista [_flash] de datos flash. Al final de cada solicitud, los datos flash establecidos durante la solicitud (lista [new]) se mueven a la lista [old], y los datos que ya estaban en [old] se eliminan: así, un dato flash sobrevive exactamente una solicitud. Sigamos la redirección enviando la cookie de vuelta:

curl -i -b cookies.txt -c cookies.txt http://localhost:8000/tasks
1
2
3
4
5
6
7
HTTP/1.1 200 OK
...
          <div class="alert alert-success" role="status">The task [Do the exercises] has been added.</div>
...
          <li>Read chapter 3</li>
          <li>Do the exercises</li>
...

El mensaje se muestra y, después de esta solicitud, el archivo de sesión ya no lo contiene:

1
2
3
a:3:{s:6:"_token";s:40:"X0omnUmKl13zVLUrzTdZy5mWN7R6fBaiOmfEUPpr";
     s:9:"_previous";a:2:{s:3:"url";s:27:"http://localhost:8000/tasks";s:5:"route";s:5:"tasks";}
     s:6:"_flash";a:2:{s:3:"old";a:0:{}s:3:"new";a:0:{}}}

Una nueva solicitud GET ya no mostraría el mensaje. La lista de tareas, en cambio, se almacena en un archivo de caché cuyo nombre se calcula a partir de la clave ([storage/framework/cache/data/55/d8/55d8727a05eb80b0788af57a5317f3e0a1f4aa55]):

9999999999a:2:{i:0;s:14:"Read chapter 3";i:1;s:16:"Do the exercises";}

Los primeros diez dígitos representan la fecha de expiración del valor (en este caso, nunca); el resto es la lista serializada.

4.8.5. Ejecución

Agregar una tarea: el navegador siguió la redirección; la URL corresponde a la página GET, que se puede recargar sin riesgo.

Image

Una entrada inválida, vuelta a mostrar con su mensaje de error:

Image

El contraejemplo: la página es la respuesta a un POST, y su URL es [/tasks/without-prg]. Si se presiona [F5], el navegador pregunta si se desea reenviar el formulario; si se acepta, la tarea se agrega por segunda vez.

Image

4.9. Ejemplo 21: enlaces, botones y confirmación

Un principio del protocolo HTTP: una solicitud GET no cambia nada. Los navegadores, los motores de búsqueda y las herramientas que precargan páginas siguen los enlaces libremente, sin pedir permiso al usuario. Un enlace “eliminar” ([<a href="/contacts/2/delete">]) sería, por lo tanto, peligroso: un bot que rastree el sitio eliminaría todo. En una aplicación web:

  • la consulta se realiza mediante un enlace ([<a href>]), que envía una solicitud GET;
  • la modificación (guardar, duplicar, eliminar) se realiza mediante un botón colocado en un formulario, protegido por un token anti-CSRF.

Este ejemplo gestiona una lista de contactos y muestra una ventana de confirmación antes de cada eliminación.

4.9.1. El servicio: app/Services/ContactsService.php

<?php
// app/Services/ContactsService.php: los contactos, compartidos por todos, almacenados en
// la caché de Laravel (véase el ejemplo 20)

namespace App\Services;

use App\Models\Contact;
use Illuminate\Support\Facades\Cache;

class ContactsService
{
    private const KEY = 'contacts';

    /** @return array{contacts: list<Contact>, lastId: int} */
    private function data(): array
    {
        return Cache::get(self::KEY, [
            'contacts' => [
                new Contact(1, 'Marie Durand', '01 23 45 67 89'),
                new Contact(2, 'Paul Martin', '06 12 34 56 78'),
                new Contact(3, 'Philippe Jandot', '02 98 76 54 32'),
            ],
            'lastId' => 3,
        ]);
    }

    // una modificación de los datos, bajo bloqueo: la función recibe los datos,
    // los modifica (&) y devuelve el resultado de la operación
    private function editData(callable $operation): mixed
    {
        return Cache::lock('contacts-lock', 10)->block(5, function () use ($operation) {
            $data = $this->data();
            $result = $operation($data);
            Cache::forever(self::KEY, $data);
            return $result;
        });
    }

    /** @return list<Contact> */
    public function list(): array
    {
        return $this->data()['contacts'];
    }

    // el contacto, o null si no existe
    public function read(int $id): ?Contact
    {
        return array_find($this->list(), fn (Contact $c) => $c->id === $id);
    }

    public function edit(int $id, string $name, string $phone): ?Contact
    {
        return $this->editData(function (array &$data) use ($id, $name, $phone) {
            foreach ($data['contacts'] as $i => $contact) {
                if ($contact->id === $id) {
                    // un contacto es inmutable (readonly): construimos uno nuevo,
                    // que reemplaza al anterior en el arreglo
                    return $data['contacts'][$i] = new Contact($id, $name, $phone);
                }
            }
            return null;
        });
    }

    public function add(string $name, string $phone): Contact
    {
        return $this->editData(function (array &$data) use ($name, $phone) {
            $contact = new Contact(++$data['lastId'], $name, $phone);
            $data['contacts'][] = $contact;
            return $contact;
        });
    }

    public function delete(int $id): ?Contact
    {
        return $this->editData(function (array &$data) use ($id) {
            foreach ($data['contacts'] as $i => $contact) {
                if ($contact->id === $id) {
                    // array_splice elimina el elemento i del arreglo y renumera los siguientes
                    array_splice($data['contacts'], $i, 1);
                    return $contact;
                }
            }
            return null;
        });
    }
}

Los contactos se almacenan en la caché, igual que las tareas del ejemplo 20. Cada contacto es un objeto [Contact] inmutable (un ID, un nombre, un número de teléfono), almacenado en un arreglo junto con el último ID asignado. Algunos puntos sobre [PHP]:

  • Líneas 29–37: todas las modificaciones siguen el mismo patrón: adquirir el bloqueo, leer los datos, modificarlos, escribirlos de nuevo y liberar el bloqueo. Este método escribe en el arreglo una sola vez; cada modificación le pasa una función (de tipo [callable], “invocable”) que recibe los datos y los modifica. La función debe modificar el propio arreglo, no una copia: su parámetro se declara como [array &$data], donde [&] especifica un paso por referencia (sin [&], un arreglo se copia; véase el ejemplo 06);
  • líneas 51–63: un contacto es inmutable: se crea uno nuevo, que reemplaza al anterior en el arreglo. Una asignación es una expresión cuyo valor es el valor asignado: [return $data['contacts'][$i] = new Contact(...)] reemplaza el contacto y lo devuelve;
  • línea 68: [++] colocado antes de una variable la incrementa en 1 y devuelve el nuevo valor;
  • línea 80: [array_splice] elimina un elemento del arreglo y vuelve a numerar los elementos siguientes;
  • Los métodos devuelven [null] para un contacto inexistente: le corresponde al controlador decidir la respuesta.

4.9.2. El controlador: app/Http/Controllers/ContactsController.php

<?php
// app/Http/Controllers/ContactsController.php: enlaces (GET) y botones (POST, DELETE)

namespace App\Http\Controllers;

use App\Models\Contact;
use App\Services\ContactsService;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\View\View;

class ContactsController
{
    public function __construct(private ContactsService $contacts)
    {
    }

    // el contacto, o una respuesta 404 si no existe
    private static function contactOr404(?Contact $contact): Contact
    {
        abort_if($contact === null, 404, 'unknown contact');
        return $contact;
    }

    // un ENLACE (<a href>): una solicitud GET, que no modifica nada
    public function list(): View
    {
        return view('contacts.list', ['contacts' => $this->contacts->list()]);
    }

    public function details(int $id): View
    {
        return view('contacts.details', ['contact' => self::contactOr404($this->contacts->read($id))]);
    }

    // un BOTÓN en un formulario POST: una solicitud que modifica datos
    public function save(Request $request, int $id): RedirectResponse
    {
        $contact = self::contactOr404($this->contacts->edit($id,
            $request->string('name')->value(), $request->string('phone')->value()));
        return redirect()->route('contacts')->with('message', "The contact [$contact->name] has been edited.");
    }

    // el mismo formulario, otro botón (atributo formaction): otra acción
    public function duplicate(Request $request, int $id): RedirectResponse
    {
        $copy = $this->contacts->add($request->string('name')->value().' (copy)',
            $request->string('phone')->value());
        return redirect()->route('contacts')->with('message', "The contact [$copy->name] has been created.");
    }

    // una solicitud DELETE, simulada por un formulario POST (véase @method en la vista)
    public function delete(int $id): RedirectResponse
    {
        $contact = self::contactOr404($this->contacts->delete($id));
        return redirect()->route('contacts')->with('message', "The contact [$contact->name] has been deleted.");
    }
}
  • líneas 19–23: una función de utilidad: un contacto inexistente termina la acción con una respuesta 404 ([abort_if], véase el ejemplo 15);
  • líneas 26–34: las dos acciones GET, que no modifican nada: la lista y la ficha de un contacto;
  • líneas 37–42: guardado de la ficha: una acción POST, que sigue el esquema PRG. La misma URL [/contacts/2] es manejada por dos acciones diferentes, según el método: GET muestra, POST guarda;
  • Líneas 45–50: duplicación, otra acción POST, desencadenada por un segundo botón del mismo formulario;
  • Líneas 53–57: eliminación, manejada por una solicitud DELETE.

La tabla de rutas:

<?php
// routes/web.php: las rutas del ejemplo 21

use App\Http\Controllers\ContactsController;
use Illuminate\Support\Facades\Route;

Route::prefix('contacts')->controller(ContactsController::class)->group(function () {
    Route::get('/', 'list')->name('contacts');
    Route::get('{id}', 'details')->whereNumber('id')->name('contacts.details');
    Route::post('{id}', 'save')->whereNumber('id')->name('contacts.save');
    Route::post('{id}/duplicate', 'duplicate')->whereNumber('id')->name('contacts.duplicate');
    Route::delete('{id}', 'delete')->whereNumber('id')->name('contacts.delete');
});
  • Línea 12: la eliminación se declara para el método HTTP DELETE, que el protocolo HTTP especifica para eliminar un recurso. Sin embargo, un formulario HTML solo puede enviar solicitudes GET y POST. [Laravel] sortea esta limitación: un formulario POST que contiene un campo oculto [_method], con el valor [DELETE] (o [PUT], [PATCH]), se trata como una solicitud de ese método. Esto es la simulación de métodos (method spoofing), que implementa la directiva [@method] en las vistas.

4.9.3. Las vistas

@extends('layout')

@section('content')
  <h1 class="h3">Contacts</h1>
  <table class="table align-middle">
    <tbody>
      @foreach ($contacts as $contact)
        <tr>
          <td>{{ $contact->name }}</td>
          <td>{{ $contact->phone }}</td>
          <td class="text-end">
            {{-- vista: un enlace simple; route() coloca el id en la ruta: /contacts/2 --}}
            <a class="btn btn-sm btn-outline-primary" href="{{ route('contacts.details', $contact->id) }}">View</a>
            {{-- delete: a form, whose submission will be confirmed --}}
            <form method="post" class="d-inline" action="{{ route('contacts.delete', $contact->id) }}"
                  data-confirmation="Delete the contact {{ $contact->name }}?">
              {{-- el token anti-CSRF, requerido para toda solicitud que no sea GET --}}
              @csrf
              {{-- el método DELETE, que un formulario HTML no puede enviar --}}
              @method('DELETE')
              <button class="btn btn-sm btn-outline-danger" type="submit">Delete</button>
            </form>
          </td>
        </tr>
      @endforeach
    </tbody>
  </table>
@endsection
  • línea 13: un enlace, presentado como un botón mediante las clases de [Bootstrap] ([btn]...): la apariencia no tiene nada que ver con el método HTTP. [route('contacts.details', $contact->id)] coloca el ID en la ruta: [/contacts/2] (se puede proporcionar un único parámetro sin un arreglo);
  • Líneas 15–22: un formulario por cada botón “Delete”, sin más campos que el token y el método. La clase [d-inline] lo muestra en la misma línea que el enlace. El atributo [data-confirmation] contiene el mensaje de confirmación; los atributos [data-...] no están especificados y están pensados para el [JavaScript] de la página;
  • línea 18: el token anti-CSRF (ejemplo 18), obligatorio para toda solicitud que no sea GET;
  • línea 20: la directiva [@method] escribe el campo oculto [_method]: [<input type="hidden" name="_method" value="DELETE">].
@extends('layout')

@section('content')
  <h1 class="h3">Contact no. {{ $contact->id }}</h1>
  <form method="post" action="{{ route('contacts.save', $contact->id) }}">
    @csrf
    <div class="mb-2">
      <label class="form-label" for="name">Name</label>
      <input class="form-control" id="name" name="name" value="{{ $contact->name }}">
    </div>
    <div class="mb-3">
      <label class="form-label" for="phone">Phone</label>
      <input class="form-control" id="phone" name="phone" value="{{ $contact->phone }}">
    </div>
    {{-- two submit buttons for the same form --}}
    <button class="btn btn-primary" type="submit">Save</button>
    <button class="btn btn-outline-primary" type="submit"
            formaction="{{ route('contacts.duplicate', $contact->id) }}">Duplicate</button>
    <a class="btn btn-link" href="{{ route('contacts') }}">Back to the list</a>
  </form>
@endsection
  • Líneas 16–18: dos botones de envío para el mismo formulario: “Save” envía el formulario a la dirección especificada por su atributo [action], y “Duplicate” lo envía a la dirección especificada por su atributo [formaction] (ejemplo 20). Este formulario no utiliza [@method]: el campo [_method] sería enviado por ambos botones, y la duplicación también se convertiría en una solicitud PUT o DELETE;
  • Línea 19: regreso a la lista: un enlace.

4.9.4. La ventana de confirmación

El navegador puede mostrar un cuadro de confirmación (función [JavaScript] [confirm]), pero no es muy atractivo y su apariencia depende del navegador. Aquí utilizamos una ventana modal de [Bootstrap], mostrada mediante unas pocas líneas de [JavaScript]. La ventana es un fragmento incluido en la plantilla y, por lo tanto, está presente, aunque oculta, en todas las páginas:

{{-- una única ventana para toda la página, oculta (d-none) al inicio --}}
<div id="confirmation-modal" class="d-none">
  <div class="modal-backdrop fade show"></div>
  <div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true">
    <div class="modal-dialog modal-dialog-centered">
      <div class="modal-content">
        <div class="modal-header">
          <h5 class="modal-title">Confirmation</h5>
        </div>
        <div class="modal-body">
          <p class="mb-0" id="confirmation-modal-message"></p>
        </div>
        <div class="modal-footer">
          <button type="button" class="btn btn-secondary" data-action="no">No, go back</button>
          <button type="button" class="btn btn-danger" data-action="yes">Yes, confirm</button>
        </div>
      </div>
    </div>
  </div>
</div>
  • línea 2: la clase [d-none] de [Bootstrap] oculta el elemento;
  • líneas 3–4: el fondo gris, seguido de la ventana, se renderizan mediante las clases de [Bootstrap];
  • línea 11: la ubicación del mensaje;
  • líneas 14–15: los dos botones, de tipo [button] (no [submit]: no envían ningún formulario), que se distinguen por su atributo [data-action].
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Contacts</title>
  <link rel="stylesheet" href="{{ route('bootstrap', 'css/bootstrap.min.css') }}">
  <link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
  <div class="container py-3" style="max-width: 40rem">
    @session('message')
      <div class="alert alert-success" role="status">{{ $value }}</div>
    @endsession
    <main>
      @yield('content')
    </main>
  </div>
  {{-- la ventana de confirmación, presente en todas las páginas --}}
  @include('fragments.confirmation')
  {{-- el script, al final de la página: los elementos que busca ya existen --}}
  <script src="{{ asset('js/app.js') }}"></script>
</body>
</html>
  • línea 19: la ventana, incluida en todas las páginas;
  • línea 21: el script, colocado al final de la página: cuando se ejecuta, los elementos que busca ya existen. Se almacena en la carpeta [public/js].

El script [public/js/app.js]:

// confirmación de los formularios que llevan el atributo data-confirmation="..."
// Sin JavaScript, estos formularios simplemente se envían sin confirmación.
(() => {
  const modal = document.getElementById('confirmation-modal');
  const message = document.getElementById('confirmation-modal-message');
  let pending = null; // el formulario que se enviará si el usuario confirma

  // 1. interceptamos el envío de los formularios por confirmar
  document.querySelectorAll('form[data-confirmation]').forEach((form) => {
    form.addEventListener('submit', (event) => {
      event.preventDefault(); // el envío se suspende
      pending = form;
      message.textContent = form.dataset.confirmation;
      modal.classList.remove('d-none'); // aparece la ventana
    });
  });

  // 2. los dos botones de la ventana
  modal.addEventListener('click', (event) => {
    const action = event.target.dataset.action;
    if (action === 'yes') {
      pending.submit(); // envío, SIN volver a disparar el evento 'submit'
    } else if (action === 'no') {
      modal.classList.add('d-none');
      pending = null;
    }
  });
})();
  • línea 3: el código está encerrado en una función anónima, que se ejecuta de inmediato; sus variables no interfieren con las de los demás scripts de la página;
  • líneas 4–6: la ventana, la ubicación del mensaje y el formulario en espera de confirmación;
  • líneas 9–14: para cada formulario que tiene un atributo [data-confirmation], se intercepta el evento [submit], que se desencadena cuando se envía el formulario. [preventDefault()] suspende el envío; el formulario se pone en espera y su mensaje ([dataset.confirmation], el valor del atributo [data-confirmation]) se muestra en la ventana, que aparece;
  • líneas 19–25: un único manejador para los clics en la ventana: [event.target] es el elemento en el que se hizo clic; su atributo [data-action] especifica de qué botón se trata. “Yes” envía el formulario pendiente mediante el método [submit()], que, a diferencia de hacer clic en un botón, no desencadena el evento [submit] (de lo contrario, la ventana volvería a aparecer); “No” oculta la ventana.

Sin [JavaScript], el formulario simplemente se envía sin confirmación: la página sigue siendo utilizable. Esto es mejora progresiva: [JavaScript] agrega comodidad, pero la aplicación no depende de él.

4.9.5. Ejecución

La lista de contactos:

Image

Al hacer clic en “Delete” se muestra la ventana de confirmación:

Image

Tras la confirmación, la solicitud DELETE (simulada), la redirección y el mensaje emergente:

Image

La ficha de un contacto, con sus dos botones de envío:

Image

Una solicitud sin token anti-CSRF es rechazada, y un contacto inexistente devuelve un error 404:

curl -i -X POST -d "_method=DELETE" http://localhost:8000/contacts/2
curl -i http://localhost:8000/contacts/9
HTTP/1.1 419 unknown status
Content-Type: text/html; charset=utf-8
...
        <title>Page Expired</title>
...
HTTP/1.1 404 Not Found
Content-Type: text/html; charset=utf-8
...
        <title>Not Found</title>
...

Las páginas de error siguen siendo las de [Laravel] en inglés. El capítulo sobre el ciclo de vida de la solicitud mostrará cómo reemplazarlas por páginas personalizadas.