19. Exercício prático – Versão 9
Nesta versão, melhoraremos o servidor da seguinte forma:
- Atualmente, a cada requisição, os dados da administração tributária são obtidos do banco de dados. Usaremos uma sessão:
- quando um usuário faz sua primeira requisição, os dados da administração tributária são obtidos do banco de dados e armazenados na sessão;
- nas requisições seguintes do mesmo usuário, os dados da administração tributária são obtidos da sessão. Podemos esperar uma ligeira melhoria no tempo de execução, já que as consultas ao banco de dados são custosas;
- a sessão também garantirá que o usuário seja autenticado apenas uma vez;
- O servidor registrará os eventos importantes em um arquivo de texto (logs):
- autenticação bem-sucedida ou malsucedida;
- se os parâmetros enviados pelo cliente são válidos;
- o resultado do cálculo do imposto;
- diversos casos de erro;
- em caso de erro fatal, um e-mail será enviado ao administrador da aplicação.
O cliente também precisará ser modificado para tratar o cookie de sessão que o servidor lhe enviará.
19.1. O servidor
Vamos nos concentrar no lado servidor da aplicação.

Esta arquitetura será implementada pelos seguintes arquivos:
| scripts-web/tax/version-09
├── Dao
│ └── ServerDaoWithSession.php
├── Data
│ ├── .htaccess
│ ├── config-server.json
│ └── logs.txt
├── Tests
│ └── ServerDaoTest.php
├── Utilities
│ ├── Logger.php
│ └── SendAdminMail.php
└── tax-server.php
|
Os demais arquivos são das versões 5 e 8.
19.1.1. Utilitários
19.1.1.1. A classe [Logger]
A classe [Logger] será usada para gravar logs em um arquivo de texto:
| <?php
declare(strict_types=1);
// namespace
namespace Application;
// um log em um arquivo de texto
final readonly class Logger
{
// construtor: o arquivo de log é criado se não existir
public function __construct(private string $logsFilename)
{
// verificamos que podemos escrever no arquivo (anexando uma string vazia)
if (@file_put_contents($logsFilename, "", FILE_APPEND) === false) {
throw new TaxException("Failed to create the log file [$logsFilename]", 50);
}
}
// escrita de uma mensagem nos logs, precedida da data e da hora
public function write(string $message): void
{
$date = (new \DateTimeImmutable())->format("d/m/y H:i:s.v");
// FILE_APPEND: escrevemos no fim do arquivo
// LOCK_EX: o arquivo é bloqueado durante a escrita
file_put_contents($this->logsFilename, "$date : $message\n", FILE_APPEND | LOCK_EX);
}
}
|
Comentários
- Linha 9: A classe é [final] (não pode ser estendida) e [readonly]: seu único atributo, o nome do arquivo de log, não pode ser modificado após a criação do objeto;
- linha 12: O construtor da classe recebe o nome do arquivo de log como parâmetro;
- linha 15: Verificamos se é possível gravar no arquivo acrescentando-lhe uma string vazia. O flag [FILE_APPEND] garante que o arquivo seja criado se não existir e que seu conteúdo seja preservado caso contrário. O operador [@] impede que o PHP exiba um aviso em caso de falha: tratamos o erro nós mesmos;
- linha 16: se a gravação falhou, uma exceção é lançada;
- linha 21: o método [write] grava a mensagem [$message] no arquivo de log, precedida da data e da hora. O formato [d/m/y H:i:s.v] especifica o dia, o mês e o ano (com dois dígitos), seguidos das horas, minutos, segundos e milissegundos;
- Linha 26: A função [file_put_contents] abre o arquivo, acrescenta a linha e o fecha. Portanto, não há mais um método [close] como na versão PHP 7 da classe, que mantinha o arquivo aberto entre duas gravações.
A aplicação servidor pode atender vários clientes simultaneamente. No entanto, há um único arquivo de log para todos eles. Existe, portanto, o risco de acesso concorrente na gravação do arquivo. O curso de PHP 7 ignorava esse problema. Aqui, o flag [LOCK_EX] instrui o [file_put_contents] a bloquear o arquivo durante a gravação: se outra requisição tentar gravar ao mesmo tempo, ela espera até que o bloqueio seja liberado. Assim, uma única linha de log nunca se mistura com outra. No entanto, as linhas gravadas por duas requisições simultâneas podem ficar intercaladas entre si.
19.1.1.2. A classe [SendAdminMail]
A classe [SendAdminMail] permite enviar um e-mail ao administrador da aplicação em caso de falha:
| <?php
declare(strict_types=1);
// namespace
namespace Application;
// dependências do Symfony Mailer
use Symfony\Component\Mailer\Mailer;
use Symfony\Component\Mailer\Transport;
use Symfony\Component\Mime\Email;
// envio de um e-mail ao administrador da aplicação
final readonly class SendAdminMail
{
// $config: as informações necessárias para enviar o e-mail
// $logger: um log opcional para registrar o resultado do envio
public function __construct(private array $config, private ?Logger $logger = null)
{
}
// envio da mensagem [$message] ao administrador
// o método não lança exceção: uma falha no envio é apenas registrada nos logs
public function send(string $message): void
{
// o e-mail é enviado ao servidor SMTP $this->config["smtp-server"] na porta $this->config["smtp-port"]
// de $this->config["from"] para o destinatário $this->config["to"]
// com o assunto $this->config["subject"] e os anexos $this->config["attachments"]
// se $this->config["tls"] for true, a conexão é segura e autenticada
$config = $this->config;
try {
// criação da mensagem
$email = (new Email())
->from($config["from"])
->to($config["to"])
->subject($config["subject"])
->text($message);
// anexos
foreach ($config["attachments"] as $attachment) {
if (file_exists($attachment)) {
$email->attachFromPath($attachment);
} else {
$this->logger?->write("The attachment [$attachment] does not exist");
}
}
// o transporte da mensagem
$dsn = "smtp://{$config["smtp-server"]}:{$config["smtp-port"]}";
if ($config["tls"]) {
// conexão segura (STARTTLS) e autenticada
$verifyPeer = ($config["verify-peer"] ?? true) ? 1 : 0;
$dsn = sprintf("smtp://%s:%s@%s:%d?require_tls=1&verify_peer=%d",
rawurlencode($config["user"]), rawurlencode($config["password"]),
$config["smtp-server"], $config["smtp-port"], $verifyPeer);
}
// envio da mensagem
(new Mailer(Transport::fromDsn($dsn)))->send($email);
$this->logger?->write("Message [$message] sent to {$config["to"]}");
} catch (\Throwable $ex) {
// falha no envio
$this->logger?->write("Error while sending the message [$message]: {$ex->getMessage()}");
}
}
}
|
Comentários
- Linhas 9–11: O curso de PHP 7 usava a biblioteca [SwiftMailer], que não é mais mantida. Usamos o [Symfony Mailer], apresentado no capítulo sobre funções de rede;
- Linha 18: O construtor recebe dois parâmetros:
- [$config]: um array associativo contendo todas as informações necessárias para enviar o e-mail;
- [$logger]: um log para registrar o resultado do envio do e-mail. Este parâmetro é opcional; seu valor padrão é [null];
- linha 24: o método [send] envia a mensagem [$message]. O código é o da função [sendmail] do script [smtp-02.php] do capítulo sobre funções de rede;
- Linha 43: O operador null-safe [?->] (PHP 8.0) chama o método [write] somente se [$this->logger] não for [null]. Ele substitui o teste [if ($this->logger !== NULL)] do script PHP 7;
- linha 58: o método [send] captura todos os erros: uma falha no envio do e-mail é apenas registrada em log. Um erro no tratamento de erros não deve impedir o servidor de responder ao seu cliente.
O array associativo [$config] terá a seguinte forma:
| "adminMail": {
"smtp-server": "localhost",
"smtp-port": 1025,
"from": "guest@localhost",
"to": "guest@localhost",
"subject": "tax calculation server crash",
"tls": false,
"attachments": []
},
|
O e-mail é enviado ao servidor [Mailpit] descrito no capítulo sobre funções de rede, que escuta na porta 1025 da máquina [localhost] e armazena todos os e-mails que recebe. Ele deve estar iniciado (arquivo [mailpit.bat] na pasta [scripts-console/inet/mailpit]).
19.1.2. A camada [dao]
A camada [dao] da versão 9 é implementada pela seguinte classe [ServerDaoWithSession]:
| <?php
declare(strict_types=1);
// namespace
namespace Application;
// uma camada [dao] que pode ser construída a partir de dados tributários já obtidos
class ServerDaoWithSession extends ServerDao
{
// o construtor recebe:
// - o nome do arquivo JSON que descreve o banco de dados: os dados tributários são lidos do banco de dados
// - ou os próprios dados tributários, já obtidos (na sessão, por exemplo)
public function __construct(string|TaxAdminData $source)
{
if ($source instanceof TaxAdminData) {
// caso mais simples: os dados já estão disponíveis
$this->taxAdminData = $source;
} else {
// repassamos à classe pai, que sabe usar o banco de dados
parent::__construct($source);
}
}
}
|
Comentários
- Linha 9: A classe [ServerDaoWithSession] da versão 9 estende a classe [ServerDao] da versão 8. Isso porque a classe [ServerDao] é capaz de usar o banco de dados. Resta apenas tratar o caso em que os dados da administração tributária já foram obtidos;
- linha 14: o construtor recebe um parâmetro que pode ser de dois tipos. O tipo união [string|TaxAdminData] (PHP 8.0) o define da seguinte forma:
- uma string: o nome do arquivo contendo as informações necessárias para se conectar ao banco de dados, se os dados da administração tributária ainda não foram obtidos;
- um objeto [TaxAdminData]: os dados da administração tributária, se já foram obtidos;
- linhas 16–18: o operador [instanceof] determina qual dos dois tipos foi recebido. Se forem os dados tributários, eles são armazenados no atributo [taxAdminData], herdado da classe [ServerDao]. É por isso que esse atributo foi declarado como [protected readonly] na versão 8. A classe PHP da versão 7 tinha um construtor com dois parâmetros, um dos quais devia ser [NULL];
- linha 21: caso contrário, o controle é passado ao construtor da classe pai, que obtém os dados do banco de dados.
Quando uma sessão web é iniciada, a camada [dao] será construída com o nome do arquivo do banco de dados. Os dados da administração tributária serão então obtidos do banco de dados e armazenados na sessão. Nas requisições seguintes da mesma sessão, a camada [dao] será construída com o objeto [TaxAdminData] da sessão. Portanto, não haverá consulta ao banco de dados.
19.1.3. O script do servidor
O script do servidor [tax-server.php] é configurado pelo seguinte arquivo JSON [config-server.json]:
| {
"databaseFilename": "../version-08/Data/database-mysql.json",
"dependencies": [
"../../../scripts-console/tax/version-05/Entities/TaxException.php",
"../../../scripts-console/tax/version-05/Entities/TaxAdminData.php",
"../../../scripts-console/tax/version-05/Entities/Database.php",
"../../../scripts-console/tax/version-05/Utilities/Utilities.php",
"../version-08/Dao/InterfaceServerDao.php",
"../version-08/Dao/ServerDao.php",
"Dao/ServerDaoWithSession.php",
"../version-08/Business/InterfaceServerBusiness.php",
"../version-08/Business/ServerBusiness.php",
"Utilities/Logger.php",
"Utilities/SendAdminMail.php"
],
"users": [
{
"login": "admin",
"passwd": "admin"
}
],
"adminMail": {
"smtp-server": "localhost",
"smtp-port": 1025,
"from": "guest@localhost",
"to": "guest@localhost",
"subject": "tax calculation server crash",
"tls": false,
"attachments": []
},
"logsFilename": "Data/logs.txt"
}
|
- linha 2: é usada a descrição do banco de dados MySQL da versão 8;
- linhas 3–15: os arquivos das versões 5 e 8 e os três novos arquivos da versão 9;
- linhas 22–30: as informações necessárias para enviar um e-mail ao administrador. Agora elas têm tipos JSON apropriados: um número para a porta, um booleano para [tls]. O arquivo do PHP 7 usava strings (["25"], ["FALSE"]);
- linha 31: o arquivo de log, relativo à pasta [version-09] do servidor. Ele fica na pasta [Data], protegida pelo arquivo [.htaccess] da versão 8: os logs não devem ser legíveis por todos.
O script do servidor [tax-server.php] muda da seguinte forma:
| <?php
// conformidade estrita com os tipos declarados dos parâmetros e resultados das funções
declare(strict_types=1);
// namespace
namespace Application;
// dependências do Symfony
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\Session\Session;
// os erros do PHP não são enviados ao cliente (vão para o log do servidor web)
ini_set("display_errors", "0");
// a pasta raiz do servidor: os caminhos do arquivo de configuração são relativos a esta pasta
const ROOT_DIRECTORY = __DIR__;
// caminho do arquivo de configuração
const CONFIG_FILENAME = ROOT_DIRECTORY . "/Data/config-server.json";
// recuperamos a configuração
$config = json_decode(file_get_contents(CONFIG_FILENAME), true, flags: JSON_THROW_ON_ERROR);
// incluímos as dependências necessárias ao script
require_once ROOT_DIRECTORY . "/../../../vendor/autoload.php";
foreach ($config["dependencies"] as $dependency) {
require_once ROOT_DIRECTORY . "/$dependency";
}
// sessão (após o carregamento da classe [TaxAdminData], da qual um objeto pode estar na sessão)
$session = new Session();
$session->start();
// criação do arquivo de log
try {
$logger = new Logger(ROOT_DIRECTORY . "/" . $config["logsFilename"]);
} catch (TaxException $ex) {
// erro 500 sem logs - a mensagem não deve revelar a árvore de arquivos do servidor
$message = "Failed to create the log file [{$config["logsFilename"]}]";
doInternalServerError($message, $config["adminMail"]);
// concluído
exit;
}
// 1º log
$logger->write("---new request");
// recuperamos a requisição atual
$request = Request::createFromGlobals();
// autenticação apenas na 1ª vez
if (!$session->has("user")) {
// log
$logger->write("Authentication in progress…");
// as credenciais enviadas pelo cliente (null se ele não enviou nenhuma)
$requestUser = $request->getUser();
$requestPassword = $request->getPassword();
// o usuário é um dos usuários autorizados?
$found = $requestUser !== null && $requestPassword !== null
&& array_any(
$config["users"],
fn(array $user): bool => $user["login"] === $requestUser && hash_equals($user["passwd"], $requestPassword)
);
if (!$found) {
// não encontrado - código 401
sendResponse(
["error" => "Authentication failed [$requestUser]"],
Response::HTTP_UNAUTHORIZED,
["WWW-Authenticate" => 'Basic realm="Tax calculation server"'],
$logger
);
// concluído
exit;
}
// registramos na sessão que o usuário foi autenticado
$session->set("user", $requestUser);
// log
$logger->write("Authentication successful [$requestUser]");
} else {
// log
$logger->write("Authentication taken from the session…");
}
// temos um usuário válido - verificamos os parâmetros recebidos
$errors = [];
// devemos ter uma requisição GET com três parâmetros
if ($request->getMethod() !== "GET" || $request->query->count() !== 3) {
$errors[] = "GET method required with only the parameters [married, children, salary]";
}
// o estado civil
if (!$request->query->has("married")) {
$errors[] = "missing married parameter";
} else {
$married = strtolower(trim($request->query->getString("married")));
if (!in_array($married, ["yes", "no"], true)) {
$errors[] = "invalid married parameter [$married]";
}
}
// o número de filhos e o salário: inteiros >= 0
$values = [];
foreach (["children", "salary"] as $parameter) {
if (!$request->query->has($parameter)) {
$errors[] = "missing $parameter parameter";
continue;
}
$value = trim($request->query->getString($parameter));
if (preg_match('/^\d+$/', $value) !== 1) {
$errors[] = "invalid $parameter parameter [$value]";
} else {
$values[$parameter] = (int) $value;
}
}
// há outros parâmetros na requisição?
foreach (array_diff(array_keys($request->query->all()), ["married", "children", "salary"]) as $parameter) {
$errors[] = "invalid parameter [$parameter]";
}
// erros?
if ($errors !== []) {
// enviamos um código de erro 400 ao cliente
sendResponse(["errors" => $errors], Response::HTTP_BAD_REQUEST, [], $logger);
// concluído
exit;
}
// log
[$children, $salary] = [$values["children"], $values["salary"]];
$logger->write("valid parameters ['married'=>$married, 'children'=>$children, 'salary'=>$salary]");
// temos tudo o que é preciso para trabalhar
// criação da camada [dao]
if (!$session->has("taxAdminData")) {
// os dados tributários são obtidos do banco de dados
$logger->write("tax data taken from the database");
try {
// construção da camada [dao]
$dao = new ServerDaoWithSession(ROOT_DIRECTORY . "/" . $config["databaseFilename"]);
// colocamos os dados tributários na sessão
$session->set("taxAdminData", $dao->getTaxAdminData());
} catch (TaxException $ex) {
// erro 500
doInternalServerError($ex->getMessage(), $config["adminMail"], $logger);
// concluído
exit;
}
} else {
// os dados tributários são obtidos da sessão
$dao = new ServerDaoWithSession($session->get("taxAdminData"));
// log
$logger->write("tax data taken from the session");
}
// criação da camada [business]
$business = new ServerBusiness($dao);
// cálculo do imposto
$result = $business->calculateTax($married, $children, $salary);
// retornamos a resposta
sendResponse($result, Response::HTTP_OK, [], $logger);
// fim
exit;
// --------------------------------------------------------------------------
// erro fatal: um e-mail ao administrador e uma resposta 500 ao cliente
function doInternalServerError(string $message, array $adminMail, ?Logger $logger = null): void
{
// a mensagem de erro de um driver de SGBD pode não estar codificada em UTF-8 (Windows-1252 no Windows)
if (!mb_check_encoding($message, "UTF-8")) {
$message = mb_convert_encoding($message, "UTF-8", "Windows-1252");
}
// enviamos um e-mail ao administrador
// [SendAdminMail] captura todas as exceções e as registra ela mesma
(new SendAdminMail($adminMail, $logger))->send($message);
// enviamos um código de erro 500 ao cliente
sendResponse(["error" => $message], Response::HTTP_INTERNAL_SERVER_ERROR, [], $logger);
}
// envio da resposta HTTP ao cliente
// $result: o array a enviar, na forma ["response" => $result]
// $statusCode: o status HTTP da resposta
// $headers: cabeçalhos HTTP a adicionar à resposta
// $logger: o log da aplicação (null se não pôde ser criado)
function sendResponse(array $result, int $statusCode, array $headers = [], ?Logger $logger = null): void
{
// a resposta JSON
$response = new JsonResponse(null, $statusCode, $headers);
$response->setEncodingOptions(JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_PRESERVE_ZERO_FRACTION);
$response->setData(["response" => $result]);
// envio
$response->send();
// log
$logger?->write($response->getContent());
}
|
Comentários
- linha 13: é usada a classe [Session] do [HttpFoundation], apresentado no capítulo anterior;
- Linha 16: Os erros detectados pelo PHP (avisos, erros fatais etc.) não são exibidos no documento enviado ao cliente. Eles corromperiam a resposta JSON esperada pelo cliente. São registrados no log de erros do servidor web (arquivo [error.log] do Apache);
- linhas 33–34: uma sessão é iniciada. Ela é iniciada depois que os arquivos da aplicação foram carregados: a sessão pode conter um objeto [TaxAdminData], e a classe [TaxAdminData] deve ser conhecida no momento em que o PHP reconstrói os objetos da sessão;
- Linhas 37–44: Tenta-se criar o arquivo de log. Se ocorrer uma exceção, a função [doInternalServerError] é chamada sem log (o último parâmetro é omitido). A mensagem de erro inclui o nome do arquivo de log especificado na configuração: a mensagem da exceção contém o caminho completo do arquivo, o que revelaria ao cliente a estrutura de pastas do servidor;
- Linha 162: A função [doInternalServerError] aceita três parâmetros:
- [$message]: a mensagem de erro;
- [$adminMail]: as informações necessárias para enviar um e-mail ao administrador da aplicação;
- [$logger]: o log da aplicação, se pôde ser criado;
- linhas 165–166: a mensagem de erro pode vir de um driver de SGBD e pode não estar codificada em UTF-8 (veja a versão 8);
- linha 170: um e-mail é enviado ao administrador da aplicação;
- linha 172: a resposta é enviada ao cliente com o código [500 Internal Server Error];
- linha 180: a função [sendResponse] envia todas as respostas ao cliente. Seus parâmetros são:
- [$result]: o array a ser enviado. O servidor envia a string JSON do array [["response" => $result]];
- [$statusCode]: o status HTTP da resposta;
- [$headers]: os cabeçalhos HTTP a serem adicionados à resposta. É o caso do cabeçalho [WWW-Authenticate] na resposta 401;
- [$logger]: o log da aplicação;
- linha 183: o construtor da classe [JsonResponse] aceita os dados, o status e os cabeçalhos da resposta. Os dados são definidos depois por [setData], após a seleção das opções de [json_encode] , que são as da versão 8;
- linha 189: a resposta JSON enviada é registrada em log;
- linha 48: a primeira entrada de log da requisição;
- linha 53: Graças à sessão estabelecida, o cliente será autenticado apenas uma vez:
- depois que o cliente é autenticado, a chave [user] é armazenada na sessão, com o identificador do usuário da linha 77 como valor;
- durante a próxima requisição do mesmo cliente, a verificação evita uma nova autenticação desnecessária;
- linhas 67–72: se a autenticação falhar, uma resposta 401 é enviada pela função [sendResponse], com o cabeçalho [WWW-Authenticate];
- linhas 86–118: A validação dos parâmetros segue a especificação da versão 8;
- linha 126: a desestruturação de array [[$a, $b] = [...]] atribui valores às duas variáveis [$children] e [$salary] em uma única instrução. Ela substitui a função [list] do PHP 7;
- linha 131: Graças à sessão, os dados serão obtidos do banco de dados apenas uma vez:
- durante a primeira consulta, a busca no banco de dados ocorre na linha 136. Os dados obtidos são então armazenados na sessão, associados à chave [taxAdminData] na linha 138;
- nas requisições seguintes, a chave [taxAdminData] é encontrada na sessão, e os dados tributários são então transmitidos diretamente à camada [dao] na linha 147;
- linhas 139–143: A busca dos dados tributários no banco de dados pode falhar. Nesse caso, um código [500 Internal Server Error] é enviado ao cliente e um e-mail é enviado ao administrador;
- linha 156: o restante do código é igual ao da versão anterior, com a resposta sendo enviada pela função [sendResponse].
Observe que as funções [doInternalServerError] e [sendResponse] são definidas no final do script, após a instrução [exit]: o PHP conhece todas as funções definidas no nível superior de um arquivo antes de executar a primeira instrução desse arquivo.
Testaremos apenas a camada [dao], que é a única que mudou. O código de teste de [Tests/ServerDaoTest.php] é o seguinte:
| <?php
// conformidade estrita com os tipos declarados dos parâmetros e resultados das funções
declare(strict_types=1);
// namespace dos testes
namespace Application\Tests;
// a classe testada
use Application\ServerDaoWithSession;
// as classes do PHPUnit
use PHPUnit\Framework\TestCase;
final class ServerDaoTest extends TestCase
{
// a pasta raiz do servidor
private const string ROOT_DIRECTORY = __DIR__ . "/..";
// a configuração do servidor
private static array $config;
// executado uma vez, antes do primeiro teste da classe
#[\Override]
public static function setUpBeforeClass(): void
{
// recuperamos a configuração do servidor
self::$config = json_decode(file_get_contents(self::ROOT_DIRECTORY . "/Data/config-server.json"), true, flags: JSON_THROW_ON_ERROR);
// incluímos as dependências do servidor
foreach (self::$config["dependencies"] as $dependency) {
require_once self::ROOT_DIRECTORY . "/$dependency";
}
}
// os dados da administração tributária lidos do banco de dados (1ª requisição de uma sessão)
public function testTaxAdminData(): void
{
// criação da camada [dao] a partir do arquivo que descreve o banco de dados
$dao = new ServerDaoWithSession(self::ROOT_DIRECTORY . "/" . self::$config["databaseFilename"]);
$taxAdminData = $dao->getTaxAdminData();
// constantes de cálculo
$this->assertSame(1551.0, $taxAdminData->halfShareQfCeiling);
$this->assertSame(21037.0, $taxAdminData->singleIncomeCeilingForReduction);
$this->assertSame(42074.0, $taxAdminData->coupleIncomeCeilingForReduction);
$this->assertSame(3797.0, $taxAdminData->halfShareReductionValue);
$this->assertSame(1196.0, $taxAdminData->singleDiscountCeiling);
$this->assertSame(1970.0, $taxAdminData->coupleDiscountCeiling);
$this->assertSame(1595.0, $taxAdminData->singleTaxCeilingForDiscount);
$this->assertSame(2627.0, $taxAdminData->coupleTaxCeilingForDiscount);
$this->assertSame(12502.0, $taxAdminData->tenPercentAllowanceMax);
$this->assertSame(437.0, $taxAdminData->tenPercentAllowanceMin);
// faixas de tributação
$this->assertSame([9964.0, 27519.0, 73779.0, 156244.0, 0.0], $taxAdminData->limits);
$this->assertSame([0.0, 0.14, 0.30, 0.41, 0.45], $taxAdminData->coeffR);
$this->assertSame([0.0, 1394.96, 5798.0, 13913.69, 20163.45], $taxAdminData->coeffN);
}
// os dados da administração tributária já obtidos (requisições seguintes da sessão)
public function testTaxAdminDataInSession(): void
{
// os dados lidos do banco de dados durante a 1ª requisição
$databaseFilename = self::ROOT_DIRECTORY . "/" . self::$config["databaseFilename"];
$taxAdminData = (new ServerDaoWithSession($databaseFilename))->getTaxAdminData();
// criação da camada [dao] a partir desses dados, como durante as requisições seguintes da sessão
$dao = new ServerDaoWithSession($taxAdminData);
// a camada [dao] retorna o mesmo objeto, sem acessar o banco de dados
$this->assertSame($taxAdminData, $dao->getTaxAdminData());
}
}
|
- linhas 23–31: criamos um ambiente de execução idêntico ao do script do servidor [tax-server.php];
- linha 37: Para construir a camada [dao], a classe [ServerDaoWithSession] é instanciada com o nome do arquivo do banco de dados. O teste então verifica a versão 8;
- Linhas 57–65: Um segundo teste verifica a construção da camada [dao] a partir de dados tributários previamente obtidos: a camada [dao] deve retornar o mesmo objeto, o que é verificado por [assertSame].
Os resultados do teste são os seguintes:
| > php vendor/bin/phpunit scripts-web/tax/version-09/Tests --testdox
PHPUnit 12.5.37 by Sebastian Bergmann and contributors.
Runtime: PHP 8.5.11
Configuration: .../php8-oct-2026/phpunit.xml
.. 2 / 2 (100%)
Time: 00:00.004, Memory: 16.00 MB
Server Dao (Application\Tests\ServerDao)
✔ Tax admin data
✔ Tax admin data in session
OK (2 tests, 14 assertions)
|
19.2. O cliente
Vamos nos concentrar na parte cliente da aplicação.

Esta arquitetura será implementada pelos seguintes arquivos:
| scripts-console/tax/version-09
├── Dao
│ └── ClientDao.php
├── Data
│ ├── config-client-ko.json
│ ├── config-client.json
│ ├── errors.json
│ ├── results.json
│ └── taxpayersdata.json
├── Main
│ └── MainTaxClient.php
└── Tests
└── ClientBusinessTest.php
|
Na nova versão, as únicas mudanças são:
- o arquivo de configuração [config-client.json];
- a camada [dao] do cliente.
O script [MainTaxClient.php] é o da versão 8.
19.2.1. A camada [dao]
A camada [dao] mudou da seguinte forma:
| <?php
declare(strict_types=1);
// namespace
namespace Application;
// dependências do Symfony
use Symfony\Component\HttpClient\HttpClient;
use Symfony\Contracts\HttpClient\Exception\ExceptionInterface;
use Symfony\Contracts\HttpClient\HttpClientInterface;
// a camada [dao] do cliente: um cliente HTTP do servidor de cálculo de imposto que gerencia uma sessão
class ClientDao implements InterfaceClientDao
{
// a trait da versão 5 implementa os métodos [getTaxPayersData] e [saveResults] da interface
use TraitDao;
// o cliente HTTP
private readonly HttpClientInterface $httpClient;
// o cookie de sessão (null enquanto o servidor não o tiver enviado)
private ?string $sessionCookie = null;
// construtor
// $urlServer: a URL do servidor de cálculo de imposto
// $user: o usuário que faz as requisições, array [login, passwd]
// $httpClientOptions: opções adicionais do cliente HTTP (verify_peer, verify_host...)
public function __construct(
private readonly string $urlServer,
#[\SensitiveParameter] private readonly array $user,
array $httpClientOptions = [],
) {
// o cliente HTTP: as credenciais do usuário só serão enviadas na 1ª requisição
$this->httpClient = HttpClient::create($httpClientOptions);
}
// cálculo do imposto pelo servidor
#[\Override]
public function calculateTax(string $married, int $children, int $salary): array
{
// as opções da requisição: os parâmetros esperados pelo servidor
$options = [
"query" => [
"married" => $married,
"children" => $children,
"salary" => $salary,
],
];
if ($this->sessionCookie === null) {
// ainda sem sessão: enviamos as credenciais do usuário
$options["auth_basic"] = [$this->user["login"], $this->user["passwd"]];
} else {
// enviamos o cookie de sessão: o usuário já está autenticado nesta sessão
$options["headers"] = ["Cookie" => $this->sessionCookie];
}
try {
// fazemos a requisição ao servidor
$response = $this->httpClient->request("GET", $this->urlServer, $options);
// o status, os cabeçalhos e o documento JSON da resposta, mesmo em caso de erro (parâmetro false)
$statusCode = $response->getStatusCode();
$headers = $response->getHeaders(false);
$json = $response->getContent(false);
} catch (ExceptionInterface $ex) {
// não foi possível alcançar o servidor
throw new TaxException("Error communicating with the server ({$ex->getMessage()})", 40, $ex);
}
// logs
// print "$json\n";
// o servidor envia a string JSON de um array ["response" => algo]
try {
$serverResponse = json_decode($json, true, flags: JSON_THROW_ON_ERROR)["response"] ?? null;
} catch (\JsonException $ex) {
$serverResponse = null;
}
if (!is_array($serverResponse)) {
throw new TaxException("Invalid server response [$json]", 41);
}
// erro?
if ($statusCode !== 200) {
// lançamos uma exceção cuja mensagem é a resposta do servidor completada com seu status HTTP
$message = json_encode(
["HTTP status" => $statusCode] + $serverResponse,
JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR
);
throw new TaxException($message, 42);
}
// recuperamos o cookie de sessão se ainda não for conhecido
if ($this->sessionCookie === null) {
foreach ($headers["set-cookie"] ?? [] as $cookie) {
if (preg_match('/^PHPSESSID=(.+?);/', $cookie, $fields) === 1) {
$this->sessionCookie = "PHPSESSID=$fields[1]";
}
}
}
// retornamos a resposta: o array [tax, surcharge, discount, reduction, rate]
return $serverResponse;
}
}
|
Comentários
A mudança na camada [dao] agora envolve o gerenciamento de uma sessão:
- linha 22: o cookie de sessão. Seu valor é [null] até que o servidor o envie. Este atributo não é [readonly]: seu valor muda após a primeira requisição;
- linha 30: as credenciais do usuário agora são armazenadas em um atributo, já que não são mais enviadas a cada requisição;
- linha 34: O cliente HTTP é criado sem a opção [auth_basic];
- linhas 49–51: Durante a primeira requisição, o cookie não existe; portanto, a requisição é enviada ao servidor junto com as informações de autenticação. A opção [auth_basic] agora faz parte da própria requisição, e não do cliente HTTP;
- linhas 52–55: Nas requisições seguintes, o cookie de sessão normalmente está presente. Nesse caso, as informações de autenticação não são enviadas; em vez disso, o cookie é enviado no cabeçalho HTTP [Cookie];
- linha 61: Obtemos os cabeçalhos da resposta. Como em [getContent], o parâmetro [false] evita uma exceção se o status da resposta indicar um erro;
- Linhas 88–94: A resposta do servidor à primeira requisição inclui um cookie de sessão em um cabeçalho [Set-Cookie]. Nós o obtemos como descrito no capítulo anterior e o armazenamos no atributo [$sessionCookie].
Poderíamos ter mantido a versão antiga da camada [dao] e feito a autenticação a cada requisição, já que o custo disso é desprezível. Para fins didáticos, porém, quisemos demonstrar como um cliente HTTP pode gerenciar uma sessão.
19.2.2. O arquivo de configuração
O arquivo de configuração JSON muda da seguinte forma:
| {
"urlServer": "http://localhost/php8-oct-2026/scripts-web/tax/version-09/tax-server.php",
"user": {
"login": "admin",
"passwd": "admin"
},
"httpClientOptions": {
"verify_peer": false,
"verify_host": false
},
"taxPayersDataFilename": "Data/taxpayersdata.json",
"resultsFilename": "Data/results.json",
"errorsFilename": "Data/errors.json",
"dependencies": [
"../version-05/Entities/TaxException.php",
"../version-05/Entities/TaxPayerData.php",
"../version-05/Utilities/Utilities.php",
"../version-05/Dao/TraitDao.php",
"../version-08/Dao/InterfaceClientDao.php",
"Dao/ClientDao.php",
"../version-08/Business/InterfaceClientBusiness.php",
"../version-08/Business/ClientBusiness.php"
]
}
|
- linha 2: a URL do servidor da versão 9;
- linhas 14–23: apenas a camada [dao] é nova. Os demais arquivos são das versões 5 e 8.
19.3. Alguns testes
Para estes testes, o servidor Apache, o SGBD MySQL e o servidor de e-mail [Mailpit] devem estar em execução.
19.3.1. Teste 1
Primeiro, executamos o cliente em um ambiente sem erros:
| > php MainTaxClient.php
The results have been saved in the file [Data/results.json]
Done
|
Os resultados são os mesmos das versões anteriores. Mas agora, do lado do servidor, há um arquivo de log chamado [Data/logs.txt]:
| 01/10/26 18:08:11.971 : ---new request
01/10/26 18:08:11.972 : Authentication in progress…
01/10/26 18:08:11.972 : Authentication successful [admin]
01/10/26 18:08:11.972 : valid parameters ['married'=>yes, 'children'=>2, 'salary'=>55555]
01/10/26 18:08:11.972 : tax data taken from the database
01/10/26 18:08:11.973 : {"response":{"tax":2814,"surcharge":0,"discount":0,"reduction":0,"rate":0.14}}
01/10/26 18:08:11.976 : ---new request
01/10/26 18:08:11.977 : Authentication taken from the session…
01/10/26 18:08:11.977 : valid parameters ['married'=>yes, 'children'=>2, 'salary'=>50000]
01/10/26 18:08:11.977 : tax data taken from the session
01/10/26 18:08:11.977 : {"response":{"tax":1384,"surcharge":0,"discount":384,"reduction":347,"rate":0.14}}
01/10/26 18:08:11.979 : ---new request
01/10/26 18:08:11.979 : Authentication taken from the session…
01/10/26 18:08:11.979 : valid parameters ['married'=>yes, 'children'=>3, 'salary'=>50000]
01/10/26 18:08:11.980 : tax data taken from the session
01/10/26 18:08:11.980 : {"response":{"tax":0,"surcharge":0,"discount":720,"reduction":0,"rate":0.14}}
…
|
- Linhas 1–6: Durante a primeira requisição, ocorre a autenticação e os dados são obtidos do banco de dados;
- Linhas 7–11: Durante a requisição seguinte, não há autenticação, e os dados são obtidos da sessão. Esse padrão se repete nas requisições subsequentes (linha 12 em diante).
19.3.2. Teste 2
Agora, vamos simular uma falha do SGBD MySQL como na versão 8 (porta 3307 no arquivo [version-08/Data/database-mysql.json]). Do lado do cliente, obtemos a seguinte saída no console:
| > php MainTaxClient.php
Error no. 42: {"HTTP status":500,"error":"Database access error (SQLSTATE[HY000] [2002] Connection refused)"}
Done
|
Do lado do servidor, vemos os seguintes logs:
| 01/10/26 18:06:48.367 : ---new request
01/10/26 18:06:48.367 : Authentication in progress…
01/10/26 18:06:48.367 : Authentication successful [admin]
01/10/26 18:06:48.367 : valid parameters ['married'=>yes, 'children'=>2, 'salary'=>55555]
01/10/26 18:06:48.367 : tax data taken from the database
01/10/26 18:06:48.450 : Message [Database access error (SQLSTATE[HY000] [2002] Connection refused)] sent to guest@localhost
01/10/26 18:06:48.450 : {"response":{"error":"Database access error (SQLSTATE[HY000] [2002] Connection refused)"}}
|
- Linha 6: o e-mail enviado ao administrador;
- linha 7: a resposta enviada ao cliente.
A interface web do [Mailpit] [http://localhost:8025] mostra o e-mail recebido pelo administrador:

O curso de PHP 7 lia esse e-mail usando o script [imap-03.php] do capítulo sobre funções de rede. Isso ainda pode ser feito usando o servidor POP3 do [Mailpit]. A aba [Raw] do [Mailpit] exibe o texto simples do e-mail:
| Return-Path: <guest@localhost>
Received: from [127.0.0.1] (localhost [127.0.0.1])
by vm (Mailpit) with SMTP
for <guest@localhost>; Thu, 1 Oct 2026 18:06:48 +0200 (CEST)
From: guest@localhost
To: guest@localhost
Subject: tax calculation server crash
Message-ID: <abc3d7c0b4e68b2d5e70d6710a13a897@localhost>
MIME-Version: 1.0
Date: Thu, 01 Oct 2026 18:06:48 +0200
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
Database access error (SQLSTATE[HY000] [2002] =
Connection refused)
|
- linha 7: o assunto contém apenas caracteres ASCII, portanto não é codificado (um assunto contendo caracteres não ASCII seria codificado conforme a RFC 2047);
- Linhas 11–12: O texto do e-mail está em UTF-8, codificado em [quoted-printable]: os caracteres não ASCII seriam codificados (por exemplo, [è] se torna [=C3=A8]), e o caractere [=] no final da linha 14 indica que a linha continua na seguinte.
19.3.3. Teste 3
Agora, vamos garantir que o arquivo [logs.txt] não possa ser criado. Para isso, basta excluir o arquivo [Data/logs.txt] e criar no lugar dele uma pasta chamada [Data/logs.txt]. Feito isso, vamos executar o cliente. Do lado do cliente, obtemos a seguinte saída no console:
| > php MainTaxClient.php
Error no. 42: {"HTTP status":500,"error":"Failed to create the log file [Data/logs.txt]"}
Done
|
Do lado do servidor, não há logs, mas o administrador recebe o seguinte e-mail:
| Return-Path: <guest@localhost>
Received: from [127.0.0.1] (localhost [127.0.0.1])
by vm (Mailpit) with SMTP
for <guest@localhost>; Thu, 1 Oct 2026 18:07:32 +0200 (CEST)
From: guest@localhost
To: guest@localhost
Subject: tax calculation server crash
Message-ID: <4ec9aec48972386b80bbcbb0e2967dfd@localhost>
MIME-Version: 1.0
Date: Thu, 01 Oct 2026 18:07:32 +0200
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
Failed to create the log file [Data/logs.txt]
|
Em seguida, excluímos a pasta [Data/logs.txt].
19.3.4. Teste 4
Desta vez, vamos usar a configuração [config-client-ko.json], que fornece ao cliente credenciais incorretas. O cliente exibe a seguinte saída no console:
| > php MainTaxClient.php config-client-ko.json
Error no. 42: {"HTTP status":401,"error":"Authentication failed [x]"}
Done
|
Do lado do servidor, aparecem os seguintes logs:
| 01/10/26 18:07:08.838 : ---new request
01/10/26 18:07:08.838 : Authentication in progress…
01/10/26 18:07:08.839 : {"response":{"error":"Authentication failed [x]"}}
|
19.3.5. Teste 5
Agora, vamos solicitar ao servidor a URL [http://localhost/php8-oct-2026/scripts-web/tax/version-09/tax-server.php] sem passar nenhum parâmetro:
| > curl -u admin:admin http://localhost/php8-oct-2026/scripts-web/tax/version-09/tax-server.php
{"response":{"errors":["GET method required with only the parameters [married, children, salary]","missing married parameter","missing children parameter","missing salary parameter"]}}
|
No arquivo de log [logs.txt] do servidor, vemos as seguintes linhas:
| 01/10/26 18:07:08.894 : ---new request
01/10/26 18:07:08.894 : Authentication in progress…
01/10/26 18:07:08.894 : Authentication successful [admin]
01/10/26 18:07:08.895 : {"response":{"errors":["GET method required with only the parameters [married, children, salary]","missing married parameter","missing children parameter","missing salary parameter"]}}
|
Como fizemos nas versões anteriores, executaremos o teste [PHPUnit] da camada [business] do cliente, [Tests/ClientBusinessTest.php]. Em comparação com a classe de teste da versão 8, nada mudou: o teste constrói seu ambiente a partir do arquivo de configuração do cliente da versão 9, localizado na pasta [Data] dessa versão.
Os resultados do teste são os seguintes:
| > php vendor/bin/phpunit scripts-console/tax/version-09/Tests --testdox
PHPUnit 12.5.37 by Sebastian Bergmann and contributors.
Runtime: PHP 8.5.11
Configuration: .../php8-oct-2026/phpunit.xml
........... 11 / 11 (100%)
Time: 00:00.063, Memory: 16.00 MB
Client Business (Application\Tests\ClientBusiness)
✔ Calculate tax with data set "couple, 2 children, 55555"
✔ Calculate tax with data set "couple, 2 children, 50000"
✔ Calculate tax with data set "couple, 3 children, 50000"
✔ Calculate tax with data set "single, 2 children, 100000"
✔ Calculate tax with data set "single, 3 children, 100000"
✔ Calculate tax with data set "couple, 3 children, 100000"
✔ Calculate tax with data set "couple, 5 children, 100000"
✔ Calculate tax with data set "single, 0 children, 100000"
✔ Calculate tax with data set "couple, 2 children, 30000"
✔ Calculate tax with data set "single, 0 children, 200000"
✔ Calculate tax with data set "couple, 3 children, 200000"
OK (11 tests, 22 assertions)
|
Vale a pena dar uma olhada nos logs [logs.txt] do servidor:
| 01/10/26 18:08:07.348 : ---new request
01/10/26 18:08:07.348 : Authentication in progress…
01/10/26 18:08:07.348 : Authentication successful [admin]
01/10/26 18:08:07.348 : valid parameters ['married'=>yes, 'children'=>2, 'salary'=>55555]
01/10/26 18:08:07.348 : tax data taken from the database
01/10/26 18:08:07.349 : {"response":{"tax":2814,"surcharge":0,"discount":0,"reduction":0,"rate":0.14}}
01/10/26 18:08:07.354 : ---new request
01/10/26 18:08:07.354 : Authentication in progress…
01/10/26 18:08:07.354 : Authentication successful [admin]
01/10/26 18:08:07.354 : valid parameters ['married'=>yes, 'children'=>2, 'salary'=>50000]
01/10/26 18:08:07.354 : tax data taken from the database
01/10/26 18:08:07.355 : {"response":{"tax":1384,"surcharge":0,"discount":384,"reduction":347,"rate":0.14}}
01/10/26 18:08:07.359 : ---new request
01/10/26 18:08:07.359 : Authentication in progress…
01/10/26 18:08:07.359 : Authentication successful [admin]
01/10/26 18:08:07.359 : valid parameters ['married'=>yes, 'children'=>3, 'salary'=>50000]
01/10/26 18:08:07.359 : tax data taken from the database
01/10/26 18:08:07.360 : {"response":{"tax":0,"surcharge":0,"discount":720,"reduction":0,"rate":0.14}}
…
01/10/26 18:08:07.397 : ---new request
01/10/26 18:08:07.397 : Authentication in progress…
01/10/26 18:08:07.397 : Authentication successful [admin]
01/10/26 18:08:07.397 : valid parameters ['married'=>yes, 'children'=>3, 'salary'=>200000]
01/10/26 18:08:07.397 : tax data taken from the database
01/10/26 18:08:07.398 : {"response":{"tax":42842,"surcharge":17283,"discount":0,"reduction":0,"rate":0.41}}
|
Vemos que os dados da administração tributária são sempre obtidos do banco de dados e nunca da sessão. Voltemos ao código do teste que foi executado:
| // executado antes de cada teste
#[\Override]
protected function setUp(): void
{
// criação das camadas [dao] e [business] como no script principal
$clientDao = new ClientDao(self::$config["urlServer"], self::$config["user"], self::$config["httpClientOptions"]);
$this->business = new ClientBusiness($clientDao);
}
|
- Linha 41: O método [setUp] é executado antes de cada teste. Um novo [ClientDao] é, portanto, criado para cada teste, com um cookie de sessão [null]. Isso explica por que esse cliente não se beneficia de nenhuma sessão: é como se os 11 testes fossem realizados por 11 usuários diferentes.
Este exemplo mostra que a sessão não é o lugar certo para armazenar os dados da administração tributária. De fato, esses dados são compartilhados por todos os usuários da aplicação. No entanto, neste caso, eles são duplicados em cada uma das sessões.
Na programação web, há três tipos de visibilidade para dados compartilhados:
- dados compartilhados por todos os usuários da aplicação web. Geralmente são dados somente leitura. O PHP não oferece suporte nativo a esse tipo de armazenamento: cada requisição é executada por um script que começa com a memória vazia;
- dados compartilhados entre as requisições de um mesmo cliente. Esses dados são armazenados na sessão. Chamamos isso de sessão do cliente, para designar a memória do cliente. Todas as requisições de um cliente têm acesso a essa sessão. Elas podem armazenar e ler informações nela. Nos scripts anteriores, essa sessão é implementada pelo objeto Symfony [HttpFoundation\Session\Session];
- o contexto da requisição. A requisição de um usuário pode ser processada por várias ações sucessivas. O contexto da requisição permite que a ação 1 passe informações à ação 2. Com o [HttpFoundation], a requisição é implementada pelo objeto [Request], e seu contexto é implementado por seu atributo [attributes].

Existem ferramentas para atribuir memória de aplicação ao PHP. A nova versão do exercício de aplicação demonstra o uso de uma delas.