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, formulários, views): lê a requisição, chama a camada de negócio e 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 e o mínimo possível de seus detalhes: a camada web desconhece o SQL, e a camada de negócio desconhece o 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 escala menor, 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 para todas as extensões 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 framework DBAL (Database Abstraction Layer) acrescenta o gerenciamento de conexões e de transações, um construtor de consultas e a conversão de tipos, e traduz os erros de cada SGBD em exceções comuns (a violação de uma restrição de unicidade se torna uma [UniqueConstraintViolationException], independentemente do SGBD);
  • O Doctrine ORM (Object-Relational Mapper) mapeia classes (entidades) para tabelas do banco de dados e transforma as linhas recuperadas em objetos. Ele segue o chamado modelo Data Mapper : as entidades são objetos comuns que nada sabem sobre o banco de dados; um objeto separado, o gerenciador de entidades, as lê e as salva. Essa é a diferença entre o [Eloquent] e o ORM (que deriva do [Laravel]), que segue o modelo Active Record (cada objeto sabe como se ler e se salvar, [$person->save()]).

O [Doctrine] não pertence ao [Symfony]: é um projeto independente, mas o ORM é o recomendado pelo [Symfony], e o DoctrineBundle o integra à aplicação. Ele é o equivalente do [JDBC], do [JPA], e do [Hibernate] no [Java] (no qual o [Doctrine] se baseou), do [Entity Framework Core] no [C#], ou do [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 consulta SQL) e a fecha ao terminar. Não há um 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.

O exemplo requer um servidor [MySQL] (ou [MariaDB]) 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/
├── .env
├── config/
│   ├── bundles.php
│   └── packages/
│       ├── doctrine.yaml
│       ├── framework.yaml
│       └── twig.yaml
├── database/
│   └── dbpersons.sql
├── public/
│   ├── css/
│   │   └── styles.css
│   └── js/
│       └── app.js
├── src/
│   ├── Controller/
│   │   └── PersonsController.php
│   ├── Dao/
│   │   └── PersonsDao.php
│   ├── Entity/
│   │   └── Person.php
│   ├── Form/
│   │   ├── PersonInput.php
│   │   └── PersonType.php
│   └── Business/
│       ├── PersonData.php
│       ├── BusinessException.php
│       └── PersonsBusiness.php
├── templates/
│   ├── fragments/
│   │   └── confirmation.html.twig
│   ├── layout.html.twig
│   └── persons/
│       ├── form.html.twig
│       └── list.html.twig
└── ...

9.1.1. O banco de dados

O banco de dados [dbpersons] é criado pelo script SQL. Com 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 a 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 nem 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 [Doctrine] também pode criar as tabelas por conta própria, com base nas entidades (comando [bin/console doctrine:schema:create]), ou por meio de migrações: classes [PHP] que descrevem, passo a passo, a criação e a modificação de cada tabela (biblioteca [DoctrineMigrationsBundle], comando [bin/console doctrine:migrations: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

O DoctrineBundle é adicionado à lista de bundles:

1
2
3
4
5
6
7
8
<?php
// config/bundles.php: os bundles da aplicação; o DoctrineBundle integra
// o Doctrine (DBAL e ORM), a biblioteca de acesso ao banco de dados
return [
    Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
    Symfony\Bundle\TwigBundle\TwigBundle::class => ['all' => true],
    Doctrine\Bundle\DoctrineBundle\DoctrineBundle::class => ['all' => true],
];

A conexão com o banco de dados é descrita no arquivo [.env] por uma URL:

1
2
3
4
5
6
# .env: a configuração do exemplo 28 (veja o exemplo 01)
APP_ENV=dev
APP_SECRET=fe7d5dd3bafdb5b7ffcab097dd4e1c0c
# a conexão com o banco de dados: o SGBD MySQL, nesta máquina (127.0.0.1), porta 3306,
# o banco dbpersons, o usuário root sem senha (configurações do Laragon)
DATABASE_URL="mysql://root:@127.0.0.1:3306/dbpersons?serverVersion=8.0.32&charset=utf8mb4"

A URL [DATABASE_URL] reúne todos os parâmetros de conexão: o SGBD ([mysql]), o nome de usuário e a senha ([root], sem nada após o [:]), o host e a porta e, por fim, o nome do banco de dados. Se o seu servidor tiver uma senha, digite-a após o [:] ([root:secret@...]). Dois parâmetros seguem o [?]: [serverVersion], a versão do servidor (o [Doctrine] adapta o SQL que gera a cada versão; para o [MariaDB], por exemplo, escreveríamos [serverVersion=10.11.2-MariaDB]), e [charset], o conjunto de caracteres usado na comunicação com o servidor, que é o conjunto de caracteres do banco de dados. A configuração do DoctrineBundle:

# config/packages/doctrine.yaml: a configuração do DoctrineBundle
doctrine:
    # DBAL: a conexão com o banco de dados, descrita por uma URL (arquivo .env)
    dbal:
        url: '%env(resolve:DATABASE_URL)%'
        # as instruções SQL são escritas no log (o console) em modo de depuração
        logging: '%kernel.debug%'
    # ORM: as ENTIDADES, as classes associadas às tabelas, são as classes da
    # pasta src/Entity; seu mapeamento para as tabelas é descrito por atributos PHP
    orm:
        mappings:
            App:
                type: attribute
                dir: '%kernel.project_dir%/src/Entity'
                prefix: 'App\Entity'
  • linha 5: a conexão. O prefixo [resolve:] substitui quaisquer referências a outros parâmetros ([%...%]) no valor da variável, se houver;
  • linha 7: no modo de depuração, cada comando SQL é escrito no log, que podemos ver no console (exemplo 24). Essa também é a configuração padrão;
  • linhas 10–15: as entidades são as classes da pasta [src/Entity], cujo namespace começa com [App\Entity]; seu mapeamento para as tabelas é descrito por atributos [PHP].

Os demais arquivos de configuração são os do exemplo 21: a sessão, a proteção anti-CSRF e os métodos PUT e DELETE ([framework.yaml]), bem como o tema de formulários [Bootstrap] ([twig.yaml]). Não há mais nada a configurar: as classes das três camadas são criadas pelo contêiner do [Symfony], que injeta em cada uma a camada abaixo (o controller recebe a camada de negócio, a camada de negócio recebe a camada DAO), e o DoctrineBundle registra o gerenciador de entidades ([EntityManagerInterface]) no contêiner.

9.1.3. A entidade Person

<?php
// src/Entity/Person.php: uma linha da tabela [persons], uma ENTIDADE do Doctrine

namespace App\Entity;

use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\Mapping as ORM;

// #[ORM\Entity]: a classe é uma entidade; #[ORM\Table]: sua tabela
#[ORM\Entity]
#[ORM\Table(name: 'persons')]
class Person
{
    // a chave primária, gerada pelo banco de dados (AUTO_INCREMENT); null antes da inserção
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    // a VERSÃO da linha: o Doctrine a incrementa a cada modificação e só
    // modifica a linha se sua versão não mudou desde a leitura (bloqueio
    // otimista); o tipo da coluna deve ser informado explicitamente
    #[ORM\Version]
    #[ORM\Column(type: Types::INTEGER)]
    private int $version = 0;

    // as colunas: seu tipo SQL é deduzido do tipo PHP (string: VARCHAR)
    #[ORM\Column(name: 'first_name', length: 30)]
    private string $firstName;

    #[ORM\Column(name: 'last_name', length: 30)]
    private string $lastName;

    #[ORM\Column]
    private int $age;

    public function __construct(string $firstName, string $lastName, int $age)
    {
        $this->edit($firstName, $lastName, $age);
    }

    public function edit(string $firstName, string $lastName, int $age): void
    {
        $this->firstName = $firstName;
        $this->lastName = $lastName;
        $this->age = $age;
    }

    public function getId(): ?int
    {
        return $this->id;
    }

    public function getVersion(): int
    {
        return $this->version;
    }

    public function getFirstName(): string
    {
        return $this->firstName;
    }

    public function getLastName(): string
    {
        return $this->lastName;
    }

    public function getAge(): int
    {
        return $this->age;
    }
}
  • linhas 10–11: o atributo [#[ORM\Entity]] designa a classe como uma entidade; [#[ORM\Table]] especifica o nome de sua tabela (caso contrário, o [Doctrine] usaria o nome da classe, [person]). [ORM] é um alias para o namespace [Doctrine\ORM\Mapping] (linha 7): [use ... as ORM] permite escrever os atributos de forma abreviada;
  • Linhas 15–18: a chave primária ([#[ORM\Id]]), gerada pelo banco de dados ([#[ORM\GeneratedValue]]: derivada de [AUTO_INCREMENT], que vem do [MySQL]). Ela é [null] até que a entidade seja inserida;
  • linhas 23–25: a versão da linha. O atributo [#[ORM\Version]] concede ao [Doctrine] o bloqueio otimista, descrito mais adiante;
  • linhas 28–35: as colunas. Cada propriedade marcada com [#[ORM\Column]] corresponde à coluna de mesmo nome; seu tipo SQL é derivado do tipo [PHP] ([string]: [VARCHAR], de comprimento [length]; [int]: [INT]). Diferentemente do [Eloquent], as colunas são declaradas: a classe especifica exatamente o que a tabela contém;
  • linhas 37–72: a entidade é uma classe comum: um construtor, um método que modifica a pessoa e métodos de acesso. As propriedades são privadas: uma pessoa só pode ser modificada por meio de seus métodos. O [Doctrine], por outro lado, lê e escreve as propriedades diretamente (por reflexão), sem passar pelo construtor nem pelos métodos.

Em um projeto padrão, o comando [bin/console make:entity] do [MakerBundle] escreve a entidade, fazendo algumas perguntas sobre suas propriedades.

9.1.4. A camada DAO

<?php
// src/Dao/PersonsDao.php: a camada DAO, consultas, sem regras de negócio

namespace App\Dao;

use App\Entity\Person;
use Doctrine\ORM\EntityManagerInterface;

class PersonsDao
{
    // o ENTITY MANAGER do Doctrine: ele lê e escreve as entidades
    public function __construct(private EntityManagerInterface $em)
    {
    }

    // SELECT ... FROM persons ORDER BY last_name, first_name
    /** @return list<Person> */
    public function list(): array
    {
        return $this->em->getRepository(Person::class)->findBy([], ['lastName' => 'ASC', 'firstName' => 'ASC']);
    }

    // SELECT ... FROM persons WHERE id = ?; null se a pessoa não existir
    public function read(int $id): ?Person
    {
        return $this->em->find(Person::class, $id);
    }

    // uma pessoa com o mesmo nome e sobrenome, diferente de [$exceptId], escrita em DQL,
    // a linguagem de consulta do Doctrine: ela fala de entidades e propriedades, não
    // de tabelas e colunas
    public function namesake(string $firstName, string $lastName, int $exceptId = 0): ?Person
    {
        return $this->em->createQuery(
            'SELECT p FROM App\Entity\Person p WHERE p.firstName = :firstName AND p.lastName = :lastName AND p.id <> :id')
            ->setParameters(['firstName' => $firstName, 'lastName' => $lastName, 'id' => $exceptId])
            ->setMaxResults(1)
            ->getOneOrNullResult();
    }

    // INSERT (nova entidade) ou UPDATE (entidade lida e depois modificada): persist confia
    // a entidade ao manager, flush envia as instruções SQL necessárias ao banco de dados
    public function save(Person $person): void
    {
        $this->em->persist($person);
        $this->em->flush();
    }

    // DELETE FROM persons WHERE id = ?
    public function delete(Person $person): void
    {
        $this->em->remove($person);
        $this->em->flush();
    }
}

A camada DAO contém apenas consultas, sem lógica de negócio. Ela recebe o gerenciador de entidades (linha 12), que usa a conexão da requisição atual e participa da transação aberta — se houver uma — iniciada pela camada de negócio.

  • Linhas 18–21: cada entidade tem um repositório (repository), um objeto que a recupera do banco de dados: [getRepository]. Seu método [findBy(criteria, orderBy)] retorna a lista de entidades que atendem aos critérios (neste caso, nenhum: todas), na ordem solicitada. (Um repositório também tem [findAll], [findOneBy], [count]...; uma aplicação pode escrever sua própria classe de repositório, com suas próprias consultas: é o que o [make:entity] gera.);
  • linhas 24–27: [find]: recuperação pela chave primária, ou [null];
  • linhas 32–39: uma consulta escrita em DQL (Doctrine Query Language), a linguagem de consulta do [Doctrine]. Ela se parece com o SQL, mas se refere a entidades e propriedades ([App\Entity\Person p], [p.firstName]), que o [Doctrine] traduz em tabelas e colunas. Os valores são parâmetros nomeados ([:firstName]), fornecidos por [setParameters]: eles são transmitidos ao banco de dados separadamente e nunca são copiados para o texto do comando SQL, o que torna a injeção de SQL impossível. [setMaxResults(1)] limita o resultado a uma linha ([LIMIT 1]); [getOneOrNullResult] retorna a entidade encontrada, ou [null];
  • Linhas 43–47: o registro. [persist] atribui uma nova entidade ao gerenciador (uma entidade lida pelo gerenciador já está atribuída a ele); [flush] envia ao banco de dados todos os comandos SQL necessários: um [INSERT] para uma nova entidade e um [UPDATE] contendo apenas as colunas modificadas para uma entidade que foi lida e depois modificada. O gerenciador compara cada entidade que leu com seu estado original: isso é o rastreamento de alterações. Após um [INSERT], o [Doctrine] armazena na entidade o identificador gerado pelo banco de dados;
  • linhas 50–54: a exclusão: [remove], seguido de [flush], que dispara o [DELETE].

9.1.5. A camada de negócio

<?php
// src/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 [Symfony].

<?php
// src/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 é destinada ao usuário. Ela herda de [RuntimeException] sem acrescentar nada — só o seu nome importa.

<?php
// src/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\Entity\Person;
use Doctrine\DBAL\Exception\UniqueConstraintViolationException;
use Doctrine\ORM\EntityManagerInterface;
use Doctrine\ORM\OptimisticLockException;

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, private EntityManagerInterface $em)
    {
    }

    /** @return list<Person> */
    public function list(): array
    {
        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
    {
        // wrapInTransaction: a função é executada em uma transação
        return $this->transaction(function () use ($data) {
            // regra 1: nenhuma pessoa com o mesmo nome e sobrenome de outra
            if ($this->dao->namesake($data->firstName, $data->lastName)) {
                throw new BusinessException(self::NAMESAKE);
            }
            $person = new Person($data->firstName, $data->lastName, $data->age);
            $this->dao->save($person);
            return $person;
        });
    }

    public function edit(int $id, int $version, PersonData $data): Person
    {
        return $this->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->getVersion() !== $version) {
                throw new BusinessException(self::MODIFIED);
            }
            if ($this->dao->namesake($data->firstName, $data->lastName, $id)) {
                throw new BusinessException(self::NAMESAKE);
            }
            $person->edit($data->firstName, $data->lastName, $data->age);
            // o UPDATE "WHERE id = ... AND version = ..." do Doctrine lança uma
            // OptimisticLockException se não modificou nenhuma linha (veja transaction)
            $this->dao->save($person);
            return $person;
        });
    }

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

    // a função [$operation], executada em uma transação. Dois erros do
    // banco de dados são erros de negócio: a restrição de unicidade (duas adições simultâneas)
    // e o bloqueio otimista (duas edições simultâneas)
    private function transaction(callable $operation): Person
    {
        try {
            return $this->em->wrapInTransaction($operation);
        } catch (UniqueConstraintViolationException $e) {
            throw new BusinessException(self::NAMESAKE, previous: $e);
        } catch (OptimisticLockException $e) {
            throw new BusinessException(self::MODIFIED, previous: $e);
        }
    }
}
  • linhas 16–20: 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] à direita: se a pessoa for [null], a exceção é lançada;
  • linhas 37–49: regra nº 1: duas pessoas não podem ter o mesmo nome e sobrenome. A regra é verificada antes de gravar no banco de dados, e uma exceção [BusinessException] é lançada se ela não for satisfeita. Mas essa verificação não é suficiente: duas requisições simultâneas poderiam verificar que não há homônimos e, em seguida, ambas prosseguir com a inserção dos registros. A restrição de unicidade do banco de dados então rejeita o segundo [INSERT], e o [Doctrine] dispara uma [UniqueConstraintViolationException], que o método [transaction] transforma na mesma [BusinessException]. O banco de dados é a última linha de defesa;
  • linhas 51–68: regra nº 2: não modificar um registro que tenha sido 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. Resta o caso em que a modificação concorrente ocorre entre a leitura da linha 54 e a gravação da linha 65: isso é detectado pelo bloqueio otimista do [Doctrine]. Para uma entidade que tem uma versão, o [UPDATE] verifica duas condições — o identificador e a versão lida — e incrementa a versão em 1; se outra consulta tiver modificado a linha nesse meio-tempo — sua versão mudou —o [UPDATE] não modifica nenhuma linha, e o [Doctrine] lança uma [OptimisticLockException]. Esse é o princípio do bloqueio otimista: nada é bloqueado, mas as modificações concorrentes são detectadas. (O [Doctrine] faz isso por conta própria, assim como o [Hibernate] e o [SQLAlchemy]; a versão [Laravel] deste curso precisou escrever a condição manualmente.);
  • linhas 70–77: a exclusão marca a pessoa como excluída para a mensagem de confirmação;
  • Linhas 82–91: toda operação que grava dados é executada dentro de uma transação: [wrapInTransaction] abre a transação, executa a função, envia as alterações pendentes ([flush]), depois confirma a transação ([COMMIT]) e retorna o valor da função; se uma exceção for lançada pela função, a transação é revertida ([ROLLBACK]): nenhuma das alterações feitas dentro da função é mantida, e a exceção é propagada. A camada de negócio determina, assim, o escopo das transações: uma operação de negócio, uma transação. Os dois erros de banco de dados que são erros de negócio se tornam [BusinessException]; o parâmetro chamado [previous] anexa a exceção original à nova para o log. Qualquer outro erro é repassado como está: não é um erro de negócio, mas um erro de programação (ou uma falha do sistema). Após uma exceção, o [Doctrine] fecha o gerenciador de entidades, cujo estado deixa de ser confiável: ele não pode mais ser usado durante a requisição, o que não é um problema aqui, já que a requisição está terminando.

O parâmetro [callable] do método [transaction] se refere a uma função arbitrária; as funções anônimas das linhas 40, 53 e 72 capturam, por meio de [use], as variáveis de que precisam.

9.1.6. A camada web

A entrada do formulário é descrita por uma classe, e suas restrições, por atributos (exemplo 19):

<?php
// src/Form/PersonInput.php: os campos do formulário e suas restrições (veja o exemplo 19)

namespace App\Form;

use App\Entity\Person;
use App\Business\PersonData;
use Symfony\Component\Validator\Constraints as Assert;

class PersonInput
{
    #[Assert\NotBlank(message: 'The first name is required.')]
    #[Assert\Length(max: 30, maxMessage: '30 characters at most.')]
    public ?string $firstName = null;

    #[Assert\NotBlank(message: 'The last name is required.')]
    #[Assert\Length(max: 30, maxMessage: '30 characters at most.')]
    public ?string $lastName = null;

    #[Assert\NotNull(message: 'The age is required.')]
    #[Assert\Range(notInRangeMessage: 'The age must be between 0 and 150.', min: 0, max: 150)]
    public ?int $age = null;

    // a versão do registro, carregada por um campo oculto (apenas na edição)
    public ?int $version = null;

    // a entrada, preenchida previamente com uma pessoa existente
    public static function from(Person $p): self
    {
        $input = new self();
        $input->firstName = $p->getFirstName();
        $input->lastName = $p->getLastName();
        $input->age = $p->getAge();
        $input->version = $p->getVersion();
        return $input;
    }

    // os dados validados, para a camada de negócio
    public function data(): PersonData
    {
        return new PersonData(trim($this->firstName), trim($this->lastName), $this->age);
    }
}
  • linhas 12–22: as restrições, com mensagens em inglês;
  • linha 25: a versão do registro, carregada por um campo oculto (somente no modo de edição);
  • linhas 28–36: uma entrada pré-preenchida com uma pessoa existente, para o formulário de atualização;
  • linhas 39–42: os dados validados, no formato esperado pela camada de negócio.

Poderíamos ter vinculado o formulário diretamente à entidade [Person] (opção [data_class], exemplo 19) e colocado as restrições nela: isso é comum no [Symfony]. No entanto, o formulário então modificaria a entidade antes que a camada de negócio verificasse suas regras, e uma entidade inválida seria passada ao gerenciador de entidades. Uma classe de entrada separada mantém as camadas distintas: a camada web transmite apenas dados validados à camada de negócio.

<?php
// src/Form/PersonType.php: o formulário de uma pessoa (veja o exemplo 18)

namespace App\Form;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\HiddenType;
use Symfony\Component\Form\Extension\Core\Type\IntegerType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;

class PersonType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            ->add('firstName', TextType::class, ['label' => 'First name', 'attr' => ['maxlength' => 30]])
            ->add('lastName', TextType::class, ['label' => 'Last name', 'attr' => ['maxlength' => 30]])
            ->add('age', IntegerType::class, ['label' => 'Age', 'attr' => ['min' => 0, 'max' => 150],
                'invalid_message' => 'The age must be an integer.']);
        // a versão: um campo oculto, apenas no formulário de edição
        if ($options['edit']) {
            $builder->add('version', HiddenType::class);
        }
    }

    // as opções do formulário: a classe dos dados e uma opção nossa
    public function configureOptions(OptionsResolver $resolver): void
    {
        $resolver->setDefaults(['data_class' => PersonInput::class, 'edit' => false]);
    }
}
  • linhas 20–21: um campo de número inteiro; [invalid_message] é a mensagem exibida quando a entrada não pode ser convertida em um inteiro;
  • linhas 23–25: o campo oculto de versão, apenas no formulário de atualização, de acordo com a opção [edit];
  • linhas 29–32: [configureOptions] declara as opções do formulário e seus valores padrão: a classe de dados e uma opção personalizada, [edit].
<?php
// src/Controller/PersonsController.php: a camada WEB; ela conhece apenas a camada de negócio

namespace App\Controller;

use App\Form\PersonInput;
use App\Form\PersonType;
use App\Business\BusinessException;
use App\Business\PersonsBusiness;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Form\FormInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
use Symfony\Component\Routing\Attribute\Route;

// name: um prefixo para o nome de todas as rotas da classe (persons_list...)
#[Route(name: 'persons_')]
class PersonsController extends AbstractController
{
    public function __construct(private PersonsBusiness $business)
    {
    }

    #[Route('/', name: 'home', methods: ['GET'])]
    public function home(): Response
    {
        return $this->redirectToRoute('persons_list');
    }

    #[Route('/persons', name: 'list', methods: ['GET'])]
    public function list(): Response
    {
        return $this->render('persons/list.html.twig', ['persons' => $this->business->list()]);
    }

    // GET: o formulário vazio; POST: o formulário enviado
    #[Route('/persons/add', name: 'add', methods: ['GET', 'POST'])]
    public function add(Request $request): Response
    {
        $input = new PersonInput();
        $form = $this->createForm(PersonType::class, $input);
        $form->handleRequest($request);
        if ($form->isSubmitted() && $form->isValid()) {
            try {
                $p = $this->business->add($input->data());
                $this->addFlash('success', "{$p->getFirstName()} {$p->getLastName()} has been added.");
                return $this->redirectToRoute('persons_list');
            } catch (BusinessException $e) {
                // uma regra de negócio recusa: o formulário é exibido novamente, com a
                // entrada e a mensagem, na parte inferior da página
                return $this->formPage('Add a person', $form, $e->getMessage());
            }
        }
        return $this->formPage('Add a person', $form);
    }

    // GET: o formulário de edição, preenchido previamente
    #[Route('/persons/{id<\d+>}/edit', name: 'edit_form', methods: ['GET'])]
    public function editForm(int $id): Response
    {
        try {
            $p = $this->business->read($id);
        } catch (BusinessException $e) {
            $this->addFlash('error', $e->getMessage());
            return $this->redirectToRoute('persons_list');
        }
        return $this->formPage('Edit a person', $this->editFormFor($id, PersonInput::from($p)));
    }

    // PUT: o formulário de edição enviado
    #[Route('/persons/{id<\d+>}', name: 'edit', methods: ['PUT'])]
    public function edit(Request $request, int $id): Response
    {
        $input = new PersonInput();
        $form = $this->editFormFor($id, $input);
        $form->handleRequest($request);
        if ($form->isSubmitted() && $form->isValid()) {
            try {
                $p = $this->business->edit($id, (int) $input->version, $input->data());
                $this->addFlash('success', "{$p->getFirstName()} {$p->getLastName()} has been edited.");
                return $this->redirectToRoute('persons_list');
            } catch (BusinessException $e) {
                return $this->formPage('Edit a person', $form, $e->getMessage());
            }
        }
        return $this->formPage('Edit a person', $form);
    }

    #[Route('/persons/{id<\d+>}', name: 'delete', methods: ['DELETE'])]
    public function delete(Request $request, int $id): Response
    {
        if (! $this->isCsrfTokenValid("delete-person-$id", $request->request->getString('_token'))) {
            throw new AccessDeniedHttpException('invalid anti-CSRF token');
        }
        try {
            $p = $this->business->delete($id);
            $this->addFlash('success', "{$p->getFirstName()} {$p->getLastName()} has been deleted.");
        } catch (BusinessException $e) {
            // nenhum formulário a exibir novamente: o erro também viaja como mensagem flash
            $this->addFlash('error', $e->getMessage());
        }
        return $this->redirectToRoute('persons_list');
    }

    // o formulário de edição: enviado pelo método PUT, para a URL /persons/{id}
    private function editFormFor(int $id, PersonInput $input): FormInterface
    {
        return $this->createForm(PersonType::class, $input, ['edit' => true,
            'method' => 'PUT', 'action' => $this->generateUrl('persons_edit', ['id' => $id])]);
    }

    private function formPage(string $title, FormInterface $form, ?string $error = null): Response
    {
        // um erro de negócio: o código 422, como para um formulário inválido (veja o exemplo 19)
        return $this->render('persons/form.html.twig',
            ['title' => $title, 'form' => $form, 'error' => $error],
            new Response(status: $error ? 422 : 200));
    }
}
  • linha 18: o atributo de classe [#[Route]] aplica um prefixo apenas aos nomes das rotas aqui: a rota chamada [list] na verdade se chama [persons_list];
  • linha 21: a camada de negócio, a única camada conhecida pelo controller;
  • linhas 38–56: o processo, em três etapas: validação do formulário (erros de entrada, exemplo 19); a chamada à camada de negócio (regras de negócio); e, por fim, o esquema PRG, com uma mensagem flash de sucesso (exemplo 20). Uma [BusinessException] exibe o formulário novamente, junto com os dados digitados e a mensagem da exceção, que o template exibirá no final da página. Os erros de entrada e os erros de regra de negócio são, assim, tratados da mesma maneira;
  • linhas 59–69: o formulário de edição, pré-preenchido com a pessoa recuperada. Se a pessoa não existir, o usuário é redirecionado para a lista com uma mensagem flash de erro;
  • linhas 72–88: a atualização, seguindo o mesmo padrão da adição;
  • linhas 90–104: a exclusão, protegida por um token CSRF exclusivo de cada pessoa (exemplo 21). Não há formulário a ser exibido novamente: qualquer erro também é transmitido por uma mensagem flash, [error];
  • linhas 107–111: o formulário de edição é enviado com o método PUT (opção [method]: [form_start] então adiciona o campo oculto [_method], exemplo 21), para a URL [/persons/{id}] (opção [action]);
  • linhas 113–119: a página do formulário. Um erro de negócio é retornado com o código 422, que indica um formulário inválido.

A camada web não contém nenhum 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.

As views:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Persons</title>
  <link rel="stylesheet" href="{{ path('bootstrap', {file: 'css/bootstrap.min.css'}) }}">
  <link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
  <div class="container py-3" style="max-width: 40rem">
    {# a mensagem de sucesso (mensagem flash [success]): no topo #}
    {% for message in app.flashes('success') %}
      <div class="alert alert-success" role="status">{{ message }}</div>
    {% endfor %}
    <main>
      {% block content %}{% endblock %}
    </main>
    {# os erros: no final; uma mensagem flash [error] ou a variável [error] da view #}
    {% for message in app.flashes('error') %}
      <div class="error-area" role="alert">{{ message }}</div>
    {% endfor %}
    {% if error is defined and error %}
      <div class="error-area" role="alert">{{ error }}</div>
    {% endif %}
  </div>
  {% include 'fragments/confirmation.html.twig' %}
  <script src="{{ asset('js/app.js') }}"></script>
</body>
</html>
  • linhas 13–15: a mensagem de sucesso no topo da página (exemplo 20);
  • Linhas 20–25: os erros; no final da página: uma mensagem flash (após um redirecionamento) ou a variável de view [error] (formulário exibido novamente). O teste [is defined] evita um erro nas páginas que não têm essa variável.
{% extends 'layout.html.twig' %}

{% block 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>
      {% for p in persons %}
        <tr>
          <td>{{ p.firstName }}</td>
          <td>{{ p.lastName }}</td>
          <td>{{ p.age }}</td>
          <td class="text-end">
            <a class="btn btn-sm btn-outline-primary" href="{{ path('persons_edit_form', {id: p.id}) }}">Edit</a>
            <form method="post" class="d-inline" action="{{ path('persons_delete', {id: p.id}) }}"
                  data-confirmation="Delete {{ p.firstName }} {{ p.lastName }}?">
              <input type="hidden" name="_method" value="DELETE">
              <input type="hidden" name="_token" value="{{ csrf_token('delete-person-' ~ p.id) }}">
              <button class="btn btn-sm btn-outline-danger" type="submit">Delete</button>
            </form>
          </td>
        </tr>
      {% endfor %}
    </tbody>
  </table>
  <a class="btn btn-primary" href="{{ path('persons_add') }}">Add a person</a>
{% endblock %}

A lista inclui os links e botões do exemplo 21, junto com sua janela de confirmação (os arquivos [fragments/confirmation.html.twig] e [public/js/app.js] são os do exemplo 21). As propriedades [p.firstName], [p.lastName]... são lidas pelos métodos de acesso [getFirstName()], [getLastName()]...: o [Twig] os encontra por conta própria (exemplo 13).

{% extends 'layout.html.twig' %}

{% block content %}
  <h1 class="h3">{{ title }}</h1>
  {# novalidate: a validação é a do servidor (veja o exemplo 19); form_start
     também escreve o campo oculto _method de um formulário PUT #}
  {{ form_start(form, {attr: {novalidate: 'novalidate'}}) }}
    {{ form_widget(form) }}
    <button class="btn btn-primary" type="submit">Save</button>
    <a class="btn btn-link" href="{{ path('persons_list') }}">Cancel</a>
  {{ form_end(form) }}
{% endblock %}

Uma view usada tanto para adicionar quanto para modificar registros. [form_widget] renderiza todos os campos do formulário, inclusive o campo oculto de versão e o token anti-CSRF.

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 letras maiúsculas e 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 também modificar o registro:

Image

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

Image

Image

9.1.8. Os comandos SQL

Vamos acompanhar no console os comandos SQL de uma modificação (as datas e linhas do servidor de desenvolvimento foram removidas). A exibição do formulário de modificação da pessoa nº 1:

1
2
3
[info] Connecting with parameters [array]
[debug] Executing statement: SELECT t0.id AS id_1, t0.version AS version_2, t0.first_name AS first_name_3, t0.last_name AS last_name_4, t0.age AS age_5 FROM persons t0 WHERE t0.id = ? (parameters: [array], types: [array])
[info] Disconnecting

Uma conexão, uma leitura pela chave primária (cujo valor é passado como parâmetro — [?]), seguida de uma desconexão no final da requisição. Não há transação: uma leitura isolada não precisa de uma. O [Doctrine] atribui um alias a cada tabela ([t0]) e a cada coluna ([id_1]). Os valores dos parâmetros são um array, que o log mínimo do [Symfony] não exibe ([[array]]); o [Monolog], ou a barra de depuração do [Symfony] ([WebProfilerBundle], instalado por [composer require --dev profiler]), os exibiria. A atualização do registro principal, com uma nova idade:

1
2
3
4
5
6
7
8
[debug] Beginning transaction
[debug] Executing statement: SELECT t0.id AS id_1, t0.version AS version_2, t0.first_name AS first_name_3, t0.last_name AS last_name_4, t0.age AS age_5 FROM persons t0 WHERE t0.id = ? (parameters: [array], types: [array])
[debug] Executing statement: SELECT p0_.id AS id_0, p0_.version AS version_1, p0_.first_name AS first_name_2, p0_.last_name AS last_name_3, p0_.age AS age_4 FROM persons p0_ WHERE p0_.first_name = ? AND p0_.last_name = ? AND p0_.id <> ? LIMIT 1 (parameters: [array], types: [array])
[debug] Executing statement: SAVEPOINT DOCTRINE_2
[debug] Executing statement: UPDATE persons SET age = ?, version = version + 1 WHERE id = ? AND version = ? (parameters: [array], types: [array])
[debug] Executing statement: SELECT version FROM persons WHERE id = ? (parameters: [array], types: [array])
[debug] Executing statement: RELEASE SAVEPOINT DOCTRINE_2
[debug] Committing transaction

Em uma única transação, vemos: a leitura do registro, a busca por um homônimo (a consulta DQL, traduzida para SQL), seguida do [UPDATE]. Essa transação modifica apenas a coluna que mudou ([age]), incrementa o número de versão e define a condição do bloqueio otimista ([AND version = ?]). [Doctrine] então lê novamente a nova versão para gravá-la na entidade. [flush] abre uma transação por conta própria; como já existe uma — a transação da camada de negócio —, ele simplesmente cria um savepoint ([SAVEPOINT]), uma transação aninhada que é confirmada ([RELEASE]) ao final do [flush]. Agora vamos enviar o mesmo formulário uma segunda vez, ainda com a versão antiga:

1
2
3
[debug] Beginning transaction
[debug] Executing statement: SELECT t0.id AS id_1, t0.version AS version_2, t0.first_name AS first_name_3, t0.last_name AS last_name_4, t0.age AS age_5 FROM persons t0 WHERE t0.id = ? (parameters: [array], types: [array])
[debug] Rolling back transaction

A versão lida não é a do formulário: a camada de negócio lançou uma [BusinessException], que reverteu a transação ([ROLLBACK]), e a página exibe “This record has been modified meanwhile: reload it.” Da mesma forma, a adição de um homônimo para após a busca por homônimos, sem um [INSERT].