Skip to content

9. Arquitetura em camadas e acesso a dados

Os exemplos anteriores armazenavam seus dados na memória ou no cache. Uma aplicação real os armazena em um banco de dados e é organizada em camadas (veja o diagrama na introdução):

  • a camada web (controllers, views): lê a requisição, chama a camada de negócio, seleciona a view;
  • a camada de negócio: regras de negócio;
  • a camada DAO (*Data Access Object*): consultas ao banco de dados.

Cada camada conhece apenas a camada imediatamente abaixo dela, e o mínimo possível de detalhes sobre ela: a camada web desconhece a camada SQL, e a camada de negócio desconhece a camada HTML. Essa separação torna cada camada mais fácil de entender, testar e evoluir. O exemplo 28 aplica isso ao gerenciamento de uma lista de pessoas: é, em menor escala, o gerenciamento de médicos e clientes do estudo de caso.

No [PHP], o acesso ao banco de dados é organizado em várias camadas:

  • a extensão PDO (*PHP Data Objects*) do [PHP] define uma interface comum a todos os módulos de SGBD: abrir uma conexão, executar um comando SQL e ler linhas. Cada SGBD tem seu próprio driver: [pdo_mysql] para o [MySQL] (e o [MariaDB]), incluído no [PHP];
  • o query builder (*query builder*) do [Laravel] (facade [DB]) constrói os comandos SQL a partir de chamadas de métodos ([where], [orderBy]...), independentemente do SGBD, e gerencia conexões e transações;
  • o Eloquent, o ORM (*Object-Relational Mapper*) do [Laravel], mapeia classes (models, conforme definidos pelo [Eloquent]) para tabelas do banco de dados e transforma as linhas recuperadas em objetos. Ele segue o chamado modelo *Active Record*: cada objeto sabe como se ler e se salvar ([Person::find(1)], [$person->save()]).

Isso equivale ao [JDBC], [JPA], e ao [Hibernate] no [Java], ao [Entity Framework Core] no [C#], ou ao [SQLAlchemy] no [Python]. Observe uma consequência do funcionamento do [PHP]: como nada sobrevive à requisição, cada requisição abre sua própria conexão com o banco de dados (na primeira requisição SQL) e a fecha ao terminar. Não há pool de conexões como no [Java] ou no [Python]; abrir uma conexão com o [MySQL] na mesma máquina leva apenas uma fração de milissegundo.

Este exemplo exige que um servidor [MySQL] (ou [MariaDB]) esteja em execução: o apêndice explica como instalar um usando o [Laragon].

9.1. Exemplo 28: Um sistema de gerenciamento de pessoal em três camadas

28-layers/
├── app/
│   ├── Dao/
│   │   └── PersonsDao.php
│   ├── Http/
│   │   ├── Controllers/
│   │   │   └── PersonsController.php
│   │   └── Requests/
│   │       └── PersonRequest.php
│   ├── Business/
│   │   ├── PersonData.php
│   │   ├── BusinessException.php
│   │   └── PersonsBusiness.php
│   └── Models/
│       └── Person.php
├── bootstrap/
│   └── app.php
├── database/
│   └── dbpersons.sql
├── public/
│   ├── css/
│   │   └── styles.css
│   └── js/
│       └── app.js
├── resources/
│   └── views/
│       ├── components/
│       │   └── field.blade.php
│       ├── fragments/
│       │   └── confirmation.blade.php
│       ├── layout.blade.php
│       └── persons/
│           ├── form.blade.php
│           └── list.blade.php
├── routes/
│   └── web.php
└── ...

9.1.1. O banco de dados

O banco de dados [dbpersons] é criado pelo script SQL. Usando o [Laragon], você pode executá-lo, por exemplo, na ferramenta [HeidiSQL] (menu Arquivo / Executar arquivo SQL), ou pela linha de comando, a partir da pasta do exemplo:

mysql -u root < database/dbpersons.sql

O arquivo [database/dbpersons.sql]:

-- banco de dados do exemplo 28: uma única tabela, [persons]
-- o script é escrito em UTF-8
SET NAMES utf8mb4;
DROP DATABASE IF EXISTS dbpersons;
CREATE DATABASE dbpersons CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbpersons;

CREATE TABLE persons (
  id INT NOT NULL AUTO_INCREMENT,
  -- a versão da linha, incrementada a cada modificação (veja camada DAO)
  version INT NOT NULL DEFAULT 0,
  first_name VARCHAR(30) NOT NULL,
  last_name VARCHAR(30) NOT NULL,
  age INT NOT NULL,
  PRIMARY KEY (id),
  -- duas pessoas não podem ter o mesmo nome e sobrenome
  CONSTRAINT unq_persons_first_name_last_name UNIQUE (first_name, last_name)
) ENGINE = InnoDB;

INSERT INTO persons (first_name, last_name, age) VALUES
  ('Marie', 'Pélissier', 42),
  ('Jacques', 'Bromard', 35),
  ('Philippe', 'Jandot', 58);
  • Linha 3: o script é escrito em [UTF-8]; isso é informado ao servidor para que os acentos dos dados ([Pélissier]) permaneçam intactos;
  • linha 5: o conjunto de caracteres [utf8mb4] aceita todos os caracteres (acentos, emojis etc.). A collation [utf8mb4_unicode_ci] compara strings sem distinguir letras maiúsculas ou acentos: para o [MySQL], [pelissier] e [Pélissier] são iguais;
  • linha 11: um número de versão, incrementado cada vez que a linha é modificada (veja “bloqueio otimista”, abaixo);
  • linha 17: uma restrição de unicidade nomeada: o banco de dados não permite duas pessoas com o mesmo nome e sobrenome. O nome será usado para identificar o erro.

O [Laravel] também pode criar as tabelas por conta própria, usando migrações: classes [PHP] que descrevem, passo a passo, a criação e as modificações de cada tabela (comando [php artisan migrate]). Mantemos um script SQL, comum a todas as versões do estudo de caso, que mostra exatamente o que o banco de dados contém.

9.1.2. Configuração

A conexão com o banco de dados é definida no arquivo [.env]:

# a conexão com o banco de dados: o SGBD MySQL, nesta máquina (127.0.0.1), porta 3306,
# o banco de dados dbpersons, o usuário root sem senha (configurações do Laragon)
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=dbpersons
DB_USERNAME=root
DB_PASSWORD=
# true: os comandos SQL enviados ao banco de dados são exibidos no console
DB_LOG=false

[DB_CONNECTION] refere-se a uma das conexões descritas pela configuração do [Laravel] ([mysql], [mariadb], [pgsql], [sqlite], [sqlsrv]); as linhas seguintes a configuram. Se o seu servidor tiver uma senha, digite-a em [DB_PASSWORD]. A conexão [mysql] se comunica com o servidor usando [utf8mb4], o conjunto de caracteres do banco de dados. [DB_LOG] é uma variável que definimos, lida por [bootstrap/app.php]:

<?php
// bootstrap/app.php: a aplicação do exemplo 28

use Illuminate\Database\Events\QueryExecuted;
use Illuminate\Database\Events\TransactionBeginning;
use Illuminate\Database\Events\TransactionCommitted;
use Illuminate\Database\Events\TransactionRolledBack;
use Illuminate\Foundation\Application;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Event;

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

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        // a rota que serve o Bootstrap (veja o exemplo 15)
        then: fn () => require __DIR__.'/../../common/bootstrap.php')
    ->withMiddleware()
    ->withExceptions()
    ->booted(function () {
        // DB_LOG=true (arquivo .env): cada comando SQL, e cada etapa de uma
        // transação, é exibido no console do servidor
        if (env('DB_LOG')) {
            DB::listen(fn (QueryExecuted $q) =>
                error_log($q->sql.' '.json_encode($q->bindings, JSON_UNESCAPED_UNICODE)));
            Event::listen(TransactionBeginning::class, fn () => error_log('BEGIN'));
            Event::listen(TransactionCommitted::class, fn () => error_log('COMMIT'));
            Event::listen(TransactionRolledBack::class, fn () => error_log('ROLLBACK'));
        }
    })
    ->create();
  • Linhas 24–30: se [DB_LOG] for igual a [true], cada comando SQL é exibido no console. [DB::listen] registra uma função chamada após cada comando SQL, com um objeto [QueryExecuted] (o texto do comando, seus parâmetros e sua duração). [Event::listen] registra uma função chamada a cada evento de um determinado tipo: [Laravel] sinaliza assim, entre outras coisas, o início, a confirmação e o cancelamento de transações. Os eventos são outra maneira — junto com os middlewares — de intervir no funcionamento do framework. (Lemos [env] diretamente, por brevidade; uma aplicação típica usaria um arquivo de configuração; veja o exemplo 25.)

Não há mais nada a configurar: as classes das três camadas são criadas pelo contêiner do [Laravel], que injeta a camada inferior em cada uma (o controller recebe a camada de negócio, e a camada de negócio recebe a camada DAO).

9.1.3. O modelo Person

<?php
// app/Models/Person.php: uma linha da tabela [persons], um "model" do Eloquent

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

// Model: a classe pai das entidades do Eloquent, o ORM do Laravel. As colunas
// da tabela se tornam, sem declarar nada, propriedades do objeto ($p->last_name)
class Person extends Model
{
    // o nome da tabela (o Eloquent o deduziria do nome da classe: people)
    protected $table = 'persons';

    // a tabela não possui as colunas created_at e updated_at que o Eloquent mantém por padrão
    public $timestamps = false;

    // as colunas que podem ser preenchidas em massa: new Person([...]), update([...])
    protected $fillable = ['first_name', 'last_name', 'age'];

    // as conversões de tipo, coluna por coluna
    protected function casts(): array
    {
        return ['age' => 'integer', 'version' => 'integer'];
    }
}
  • Linha 10: um modelo [Eloquent] herda da classe [Model]. As colunas da tabela não são declaradas: o [Eloquent] lê a linha, e cada coluna se torna uma propriedade do objeto ([$p->last_name], [$p->version]). A chave primária é, por padrão, a coluna [id], gerada pelo banco de dados ([AUTO_INCREMENT]);
  • linha 13: a tabela associada à classe. O [Eloquent] a derivaria sozinho a partir do nome da classe, colocando-o no plural (em inglês);
  • linha 16: por padrão, o [Eloquent] mantém duas colunas, [created_at] e [updated_at], que ele presume estarem presentes em todas as tabelas. A nossa não as tem;
  • linha 19: as colunas que podem ser preenchidas “em massa” a partir de um array ([Person::create([...])]). Trata-se de uma precaução: um array vindo de um formulário poderia conter outras colunas ([version], [id]...), que não queremos que sejam preenchidas dessa forma;
  • Linhas 22–25: conversões de tipo: o driver converte certas colunas numéricas em strings; [casts] garante que sejam inteiros. Há conversões para booleanos, datas (objetos [Carbon]), decimais, arrays (uma coluna JSON)...

9.1.4. A camada DAO

<?php
// app/Dao/PersonsDao.php: a camada DAO, consultas, nenhuma regra de negócio

namespace App\Dao;

use App\Business\PersonData;
use App\Models\Person;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Support\Facades\DB;

class PersonsDao
{
    // SELECT * FROM persons ORDER BY last_name, first_name
    public function list(): Collection
    {
        return Person::orderBy('last_name')->orderBy('first_name')->get();
    }

    // SELECT * FROM persons WHERE id = ? LIMIT 1; null se a pessoa não existir
    public function read(int $id): ?Person
    {
        return Person::find($id);
    }

    // uma pessoa com os mesmos nome e sobrenome, diferente de [$exceptId]:
    // SELECT * FROM persons WHERE first_name = ? AND last_name = ? AND id <> ? LIMIT 1
    public function namesake(string $firstName, string $lastName, int $exceptId = 0): ?Person
    {
        return Person::where('first_name', $firstName)->where('last_name', $lastName)
            ->where('id', '<>', $exceptId)->first();
    }

    // INSERT INTO persons (first_name, last_name, age) VALUES (?, ?, ?); o banco de dados gera
    // o id, que o Eloquent armazena no objeto
    public function add(PersonData $data): Person
    {
        return Person::create(['first_name' => $data->firstName, 'last_name' => $data->lastName,
            'age' => $data->age]);
    }

    // o BLOQUEIO OTIMISTA: UPDATE ... SET ..., version = version + 1
    // WHERE id = ? AND version = ?; retorna o número de linhas modificadas (0: a
    // linha foi modificada, ou excluída, desde que foi lida)
    public function edit(int $id, int $version, PersonData $data): int
    {
        return Person::where('id', $id)->where('version', $version)->update([
            'first_name' => $data->firstName, 'last_name' => $data->lastName, 'age' => $data->age,
            // DB::raw: uma expressão SQL, escrita como está no comando SQL
            'version' => DB::raw('version + 1'),
        ]);
    }

    // DELETE FROM persons WHERE id = ?
    public function delete(int $id): void
    {
        Person::whereKey($id)->delete();
    }
}

A camada DAO contém apenas consultas, sem nenhuma lógica de negócio. Cada método usa a conexão da requisição atual e participa da transação aberta, se houver, iniciada pela camada de negócio.

  • Linhas 14–17: [Person::orderBy(...)] inicia uma consulta na tabela de pessoas; os métodos são encadeados ([orderBy] adiciona uma ordenação) e [get()] executa a consulta. O resultado é uma coleção [Eloquent] (exemplo 03) de objetos [Person];
  • linhas 20–23: [find]: recuperação pela chave primária, ou [null];
  • linhas 27–31: [where(column, value)] adiciona uma condição de igualdade; [where(column, operator, value)] adiciona qualquer condição. Os valores são passados ao banco de dados como parâmetros do comando SQL (os marcadores [?] do comando) e nunca são copiados para o seu texto, o que torna a injeção de SQL impossível. [first()] retorna a primeira linha ([LIMIT 1]) ou [null];
  • linhas 35–39: [Person::create] cria o objeto a partir de um array (dentro do escopo de [$fillable]) e o insere no banco de dados; o [Eloquent] armazena no objeto o ID gerado pelo banco de dados;
  • linhas 44–51: a atualização, com um bloqueio otimista. O comando [UPDATE] tem duas condições: o ID da pessoa e a versão lida quando o formulário foi exibido. Ele incrementa a versão em 1: [DB::raw] insere uma expressão SQL como está ([version + 1]), em vez de um valor. Se outra requisição tiver modificado a linha nesse meio-tempo, sua versão mudou, e o [UPDATE] não modifica nenhuma linha: [update] retorna o número de linhas modificadas, que neste caso é 0. Esse é o princípio do bloqueio otimista: nada é bloqueado, mas as modificações concorrentes são detectadas. (O [Eloquent] não gerencia um número de versão por conta própria, ao contrário do [Hibernate] ou do [SQLAlchemy]: a condição é escrita à mão.);
  • linhas 54–57: um [DELETE], construído da mesma forma ([whereKey]: uma condição sobre a chave primária).

9.1.5. A camada de negócio

<?php
// app/Business/PersonData.php: os dados de uma pessoa, como a camada web os repassa

namespace App\Business;

readonly class PersonData
{
    public function __construct(
        public string $firstName,
        public string $lastName,
        public int $age,
    ) {
    }
}

Os dados de uma pessoa, conforme transmitidos pela camada web à camada de negócio: um objeto simples, sem relação com o [Laravel].

<?php
// app/Business/BusinessException.php: uma regra de negócio recusa a operação; a
// mensagem se destina ao usuário

namespace App\Business;

use RuntimeException;

class BusinessException extends RuntimeException
{
}

Uma classe de exceção específica da camada de negócio: uma regra de negócio rejeita a operação, e a mensagem da exceção se destina ao usuário. Ela herda de [RuntimeException] sem acrescentar nada — só o seu nome importa.

<?php
// app/Business/PersonsBusiness.php: a camada de NEGÓCIO, as regras de negócio, e apenas
// elas. Cada operação que escreve é uma TRANSAÇÃO: confirmada (COMMIT) se a
// função terminar normalmente, cancelada (ROLLBACK) se uma exceção sair dela

namespace App\Business;

use App\Dao\PersonsDao;
use App\Models\Person;
use Exception;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Database\QueryException;
use Illuminate\Support\Facades\DB;

class PersonsBusiness
{
    private const NAMESAKE = 'A person already has these first and last names.';

    private const MODIFIED = 'This record has been modified meanwhile: reload it.';

    private const UNKNOWN = 'This person does not exist (anymore).';

    public function __construct(private PersonsDao $dao)
    {
    }

    public function list(): Collection
    {
        return $this->dao->list();
    }

    public function read(int $id): Person
    {
        return $this->dao->read($id) ?? throw new BusinessException(self::UNKNOWN);
    }

    public function add(PersonData $data): Person
    {
        try {
            // DB::transaction: a função é executada em uma transação
            return DB::transaction(function () use ($data) {
                // regra 1: não há duas pessoas com o mesmo nome e sobrenome
                if ($this->dao->namesake($data->firstName, $data->lastName)) {
                    throw new BusinessException(self::NAMESAKE);
                }
                return $this->dao->add($data);
            });
        } catch (QueryException $e) {
            throw self::translate($e);
        }
    }

    public function edit(int $id, int $version, PersonData $data): Person
    {
        try {
            return DB::transaction(function () use ($id, $version, $data) {
                $person = $this->read($id);
                // regra 2: não modificamos um registro modificado nesse meio tempo por outra pessoa
                if ($person->version !== $version) {
                    throw new BusinessException(self::MODIFIED);
                }
                if ($this->dao->namesake($data->firstName, $data->lastName, $id)) {
                    throw new BusinessException(self::NAMESAKE);
                }
                // o UPDATE "WHERE id = ... AND version = ..." não modificou nenhuma linha:
                // outra requisição modificou o registro desde que ele foi lido
                if ($this->dao->edit($id, $version, $data) === 0) {
                    throw new BusinessException(self::MODIFIED);
                }
                // o registro, lido novamente: seus novos valores e sua nova versão
                return $this->read($id);
            });
        } catch (QueryException $e) {
            throw self::translate($e);
        }
    }

    public function delete(int $id): Person
    {
        return DB::transaction(function () use ($id) {
            $person = $this->read($id);
            $this->dao->delete($id);
            return $person;
        });
    }

    // duas inclusões simultâneas: a restrição de unicidade do banco de dados recusou a
    // segunda; getMessage() contém a mensagem do MySQL, com o nome da restrição
    private static function translate(QueryException $e): Exception
    {
        if (str_contains($e->getMessage(), 'unq_persons_first_name_last_name')) {
            return new BusinessException(self::NAMESAKE, previous: $e);
        }
        return $e;
    }
}
  • linhas 17–21: as mensagens das regras de negócio;
  • linhas 32–35: uma pessoa inexistente é um erro de negócio. O operador [??] aceita uma expressão [throw] do lado direito: se a pessoa for [null], a exceção é lançada;
  • linhas 37–51: regra nº 1: duas pessoas não podem ter o mesmo nome e sobrenome. [DB::transaction] executa a função dentro de uma transação: se a função terminar normalmente, a transação é confirmada ([COMMIT]), e [DB::transaction] retorna o valor da função; se uma exceção for lançada, a transação é revertida ([ROLLBACK]): nenhuma das alterações feitas dentro da função é mantida, e a exceção prossegue. A camada de negócio determina, assim, o escopo das transações: uma operação de negócio, uma transação. A regra é verificada antes de gravar, e uma [BusinessException] é lançada se ela não for respeitada. Mas essa verificação não é suficiente: duas requisições simultâneas poderiam verificar ambas que não há duplicata e depois inserir os dados. A restrição de unicidade do banco de dados rejeita então o segundo [INSERT], e o [Laravel] dispara uma [QueryException], que o método [translate] transforma na mesma [BusinessException]. O banco de dados é a última linha de defesa;
  • linhas 53–76: regra nº 2: não modificar um registro que foi modificado nesse meio-tempo por outra pessoa. O formulário de atualização carrega a versão do registro que foi lida (em um campo oculto); se ela for diferente da versão atual, o registro mudou desde que foi exibido. Aqui também, o banco de dados (por meio do bloqueio otimista na camada DAO) detecta quando ocorre uma modificação concorrente entre a leitura e a transação [UPDATE]: a transação [UPDATE] não modifica então nenhuma linha. O registro é então lido novamente, com seus novos valores;
  • linhas 78–85: a exclusão marca a pessoa como excluída para a mensagem de confirmação;
  • linhas 89–95: [getMessage()] contém a mensagem do [MySQL], incluindo o nome da restrição violada. Qualquer outro erro é repassado como está: não é um erro de negócio, mas um erro de programação. O parâmetro chamado [previous] anexa a exceção original à nova para o log.

9.1.6. A camada web

<?php
// app/Http/Requests/PersonRequest.php: os campos do formulário e suas restrições (veja o exemplo 19)

namespace App\Http\Requests;

use App\Business\PersonData;
use Illuminate\Foundation\Http\FormRequest;

class PersonRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'first_name' => 'required|max:30',
            'last_name' => 'required|max:30',
            'age' => 'required|integer|between:0,150',
            // a versão do registro, carregada por um campo oculto (somente na edição)
            'version' => 'nullable|integer',
        ];
    }

    public function messages(): array
    {
        return [
            'first_name.required' => 'The first name is required.',
            'first_name.max' => '30 characters at most.',
            'last_name.required' => 'The last name is required.',
            'last_name.max' => '30 characters at most.',
            'age.required' => 'The age is required.',
            'age.integer' => 'The age must be an integer.',
            'age.between' => 'The age must be between 0 and 150.',
        ];
    }

    // os dados validados, para a camada de negócio
    public function personData(): PersonData
    {
        return new PersonData($this->validated('first_name'), $this->validated('last_name'),
            (int) $this->validated('age'));
    }
}

O form request (exemplo 19). O campo oculto [version] é opcional (formulário de adição). O método [personData] retorna os dados validados no formato esperado pela camada de negócio.

<?php
// app/Http/Controllers/PersonsController.php: a camada WEB; ela só conhece a camada de negócio

namespace App\Http\Controllers;

use App\Http\Requests\PersonRequest;
use App\Business\BusinessException;
use App\Business\PersonsBusiness;
use Illuminate\Http\RedirectResponse;
use Illuminate\View\View;

class PersonsController
{
    public function __construct(private PersonsBusiness $business)
    {
    }

    public function home(): RedirectResponse
    {
        return redirect()->route('persons.list');
    }

    public function list(): View
    {
        return view('persons.list', ['persons' => $this->business->list()]);
    }

    public function addForm(): View
    {
        return view('persons.form', ['title' => 'Add a person',
            'action' => route('persons.add'), 'person' => null]);
    }

    // PersonRequest: um formulário inválido não chega até aqui (veja o exemplo 19)
    public function add(PersonRequest $request): RedirectResponse
    {
        try {
            $p = $this->business->add($request->personData());
        } catch (BusinessException $e) {
            // uma regra de negócio recusa: volta ao formulário, com a entrada e a
            // mensagem, no final da página
            return back()->withInput()->with('error', $e->getMessage());
        }
        return redirect()->route('persons.list')->with('success', "$p->first_name $p->last_name has been added.");
    }

    public function editForm(int $id): View|RedirectResponse
    {
        try {
            $p = $this->business->read($id);
        } catch (BusinessException $e) {
            return redirect()->route('persons.list')->with('error', $e->getMessage());
        }
        return view('persons.form', ['title' => 'Edit a person',
            'action' => route('persons.edit', $id), 'person' => $p]);
    }

    public function edit(PersonRequest $request, int $id): RedirectResponse
    {
        try {
            $p = $this->business->edit($id, (int) $request->validated('version'), $request->personData());
        } catch (BusinessException $e) {
            return back()->withInput()->with('error', $e->getMessage());
        }
        return redirect()->route('persons.list')->with('success', "$p->first_name $p->last_name has been edited.");
    }

    public function delete(int $id): RedirectResponse
    {
        try {
            $p = $this->business->delete($id);
        } catch (BusinessException $e) {
            // nenhum formulário a exibir novamente: o erro também viaja como mensagem flash
            return redirect()->route('persons.list')->with('error', $e->getMessage());
        }
        return redirect()->route('persons.list')->with('success', "$p->first_name $p->last_name has been deleted.");
    }
}
  • linha 14: a camada de negócio, a única camada conhecida pelo controller;
  • linhas 35–45: o processo de adição, em três etapas: validação do formulário (erros de entrada), realizada antes da chamada da action pelo form request; a chamada à camada de negócio (regras de negócio); e depois o padrão PRG, com uma mensagem flash de sucesso. Uma [BusinessException] retorna ao formulário: [back()] redireciona para a página anterior (a página do formulário), [withInput()] preserva a entrada para [old] (exemplo 19) e [with('error', ...)] devolve a mensagem de erro, que o template exibirá no final da página. É exatamente o que o [Laravel] faz para um formulário inválido: os erros de entrada e os erros de lógica de negócio são tratados da mesma maneira;
  • linhas 47–56: o formulário de edição, preenchido previamente com a pessoa recuperada. Se a pessoa não existir, o usuário é redirecionado para a lista com uma mensagem de erro em pop-up;
  • linhas 58–66: a atualização, seguindo o mesmo padrão da adição;
  • linhas 68–77: a exclusão. Não há formulário a exibir novamente: qualquer erro também é transmitido em uma mensagem pop-up, [error].

A camada web não contém nem SQL nem nenhuma regra de negócio: ela traduz a requisição em uma chamada à camada de negócio e o resultado em uma página. A tabela de rotas:

<?php
// routes/web.php: as rotas do exemplo 28

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

Route::controller(PersonsController::class)->name('persons.')->group(function () {
    Route::get('/', 'home');
    Route::get('persons', 'list')->name('list');
    Route::get('persons/add', 'addForm')->name('addForm');
    Route::post('persons/add', 'add')->name('add');
    Route::get('persons/{id}/edit', 'editForm')->whereNumber('id')->name('editForm');
    Route::put('persons/{id}', 'edit')->whereNumber('id')->name('edit');
    Route::delete('persons/{id}', 'delete')->whereNumber('id')->name('delete');
});
  • linha 7: dentro de um grupo, [name] fornece um prefixo para os nomes de rota: a rota chamada [list] na verdade se chama [persons.list];
  • Linhas 13–14: a modificação é uma requisição PUT, e a exclusão é uma requisição DELETE, simuladas por formulários POST (exemplo 21).

As views:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Persons</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">
    {{-- the success message ([success] flash message): at the top --}}
    @session('success')
      <div class="alert alert-success" role="status">{{ $value }}</div>
    @endsession
    <main>
      @yield('content')
    </main>
    {{-- the error ([error] flash message): at the bottom --}}
    @session('error')
      <div class="error-area" role="alert">{{ $value }}</div>
    @endsession
  </div>
  @include('fragments.confirmation')
  <script src="{{ asset('js/app.js') }}"></script>
</body>
</html>
  • linhas 12–14: a mensagem de sucesso, no topo da página (exemplo 20);
  • linhas 19–21: a mensagem de erro, no final da página.
@extends('layout')

@section('content')
  <h1 class="h3">Persons</h1>
  <table class="table align-middle">
    <thead><tr><th>First name</th><th>Last name</th><th>Age</th><th></th></tr></thead>
    <tbody>
      @foreach ($persons as $p)
        <tr>
          <td>{{ $p->first_name }}</td>
          <td>{{ $p->last_name }}</td>
          <td>{{ $p->age }}</td>
          <td class="text-end">
            <a class="btn btn-sm btn-outline-primary" href="{{ route('persons.editForm', $p->id) }}">Edit</a>
            <form method="post" class="d-inline" action="{{ route('persons.delete', $p->id) }}"
                  data-confirmation="Delete {{ $p->first_name }} {{ $p->last_name }}?">
              @csrf
              @method('DELETE')
              <button class="btn btn-sm btn-outline-danger" type="submit">Delete</button>
            </form>
          </td>
        </tr>
      @endforeach
    </tbody>
  </table>
  <a class="btn btn-primary" href="{{ route('persons.addForm') }}">Add a person</a>
@endsection

A lista inclui os links e botões do exemplo 21, junto com sua janela de confirmação (os arquivos [fragments/confirmation.blade.php] e [public/js/app.js] são os do exemplo 21).

@extends('layout')

@section('content')
  <h1 class="h3">{{ $title }}</h1>
  <form method="post" action="{{ $action }}" novalidate>
    @csrf
    {{-- an edit: the PUT method, and the version of the record read --}}
    @if ($person)
      @method('PUT')
      <input type="hidden" name="version" value="{{ old('version', $person->version) }}">
    @endif
    <x-field name="first_name" label="First name" :value="$person?->first_name" required maxlength="30" />
    <x-field name="last_name" label="Last name" :value="$person?->last_name" required maxlength="30" />
    <x-field name="age" label="Age" type="number" :value="$person?->age" required min="0" max="150" />
    <button class="btn btn-primary" type="submit">Save</button>
    <a class="btn btn-link" href="{{ route('persons.list') }}">Cancel</a>
  </form>
@endsection
  • Linhas 8–11: uma view comum à adição e à modificação de registros: para uma modificação ([$person] não é [null]), o método PUT e o campo oculto que carrega a versão do registro lido. [old('version', $person->version)]: a versão digitada anteriormente (após o retorno ao formulário) ou a versão do registro;
  • linhas 12–14: o componente do exemplo 19, que também recebe o valor inicial do campo ([$person?->first_name]: [null] para uma adição).
{{-- an input field, with its label and its FIRST error message (see
     example 19); [value]: the initial value of the field, displayed if the form
     has not been sent yet --}}
@props(['name', 'label', 'type' => 'text', 'value' => null])
<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, $value) }}" @endif>
  {{-- @error: the block is displayed only if the field has an error, whose
       first message is in the $message variable --}}
  @error($name)
    <div class="invalid-feedback">{{ $message }}</div>
  @enderror
</div>
  • linha 4: o componente tem um parâmetro adicional, [value];
  • linha 9: [old] aceita um valor padrão, que é usado se o formulário ainda não foi enviado: o valor inicial do campo.

9.1.7. Execução

A lista de pessoas:

Image

Um formulário de adição preenchido incorretamente: os erros de entrada são detectados pela camada web.

Image

Um homônimo: a entrada está correta, mas a camada de negócio rejeita a adição. Como a comparação é feita pelo banco de dados, ela ignora tanto as letras maiúsculas quanto os acentos: [marie pelissier] é homônimo de [Marie Pélissier].

Image

Uma adição bem-sucedida:

Image

Para testar a regra nº 2, vamos abrir o mesmo registro em duas abas. Na primeira aba, vamos alterar a idade e salvar. Na segunda aba, que ainda exibe a versão antiga, vamos modificar o registro também:

Image

A exclusão, com sua confirmação:

Image

Image

9.1.8. Os comandos SQL

Vamos reiniciar a aplicação com a variável de ambiente [DB_LOG=true] (no [Linux] e no [macOS]: [DB_LOG=true php artisan serve]; para o [Windows]: [$env:DB_LOG="true"] antes de [php artisan serve]; ou modificando o arquivo [.env]) e, em seguida, acompanhar no console os comandos SQL de uma modificação. A exibição do formulário de modificação da pessoa nº 1:

  select * from `persons` where `persons`.`id` = ? limit 1 [1]

Uma leitura pela chave primária, cujo valor é passado como parâmetro ([?]), sem transação: uma leitura isolada não exige uma. Salvando o registro com uma nova idade:

1
2
3
4
5
6
  BEGIN
  select * from `persons` where `persons`.`id` = ? limit 1 [1]
  select * from `persons` where `first_name` = ? and `last_name` = ? and `id` <> ? limit 1 ["Marie","Pélissier",1]
  update `persons` set `first_name` = ?, `last_name` = ?, `age` = ?, `version` = version + 1 where `id` = ? and `version` = ? ["Marie","Pélissier",44,1,1]
  select * from `persons` where `persons`.`id` = ? limit 1 [1]
  COMMIT

Em uma única transação, vemos: a leitura do registro principal, a busca por um homônimo, o [UPDATE] e a nova leitura. O [UPDATE] incrementa a versão ([version + 1], escrito como está graças ao [DB::raw]), e define a condição do bloqueio otimista ([and version = ?], com a versão lida, aqui 1). [Laravel] coloca os nomes de tabelas e colunas entre crases ([persons]), que é como esses nomes são escritos no [MySQL]. Agora vamos enviar o mesmo formulário uma segunda vez, ainda com a versão 1:

1
2
3
  BEGIN
  select * from `persons` where `persons`.`id` = ? limit 1 [1]
  ROLLBACK

A versão lida (2) não é a mesma do formulário (1): a camada de negócio lançou uma [BusinessException], que reverteu a transação ([ROLLBACK]), e a página exibe “Este registro foi modificado nesse meio-tempo: recarregue-o.” Da mesma forma, o processo de adição de um homônimo para após a busca por homônimo, sem um [INSERT].