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:
| <?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:
| # .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:

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

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].

Uma adição bem-sucedida:

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:

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


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:
| [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:
| [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:
| [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].