Skip to content

11. Exercício de aplicação – versão 4

A aplicação de cálculo de imposto passará a implementar a seguinte estrutura em camadas:

Image

Reutilizaremos os componentes da versão 3, modificando-os para adaptá-los à nova arquitetura da aplicação. Isso se chama “refatoração” (retrabalho do código). Aqui, vamos supor que os dados necessários à aplicação estão armazenados em arquivos de texto. A camada [dao] cuidará das interações com esses arquivos.

11.1. Estrutura de diretórios dos scripts

A versão 4 está na pasta [scripts-console/tax/version-04]:

version-04
├── Tests
│   ├── data
│   │   ├── missing-key.json
│   │   ├── negative-value.json
│   │   └── syntax.json
│   ├── BusinessTest.php
│   └── DaoTest.php
├── Business.php
├── DaoTaxWithTaxAdminDataInJsonFile.php
├── errors.txt
├── InterfaceBusiness.php
├── InterfaceDao.php
├── main.php
├── results.txt
├── taxadmindata.json
├── TaxAdminData.php
├── TaxException.php
├── TaxPayerData.php
├── taxpayersdata.txt
├── TraitDao.php
└── Utilities.php

A pasta [Tests] contém os testes automatizados da versão 4, que apresentaremos no final deste capítulo.

11.2. Objetos trocados entre as camadas

Mantemos certos elementos da versão 3 exatamente como estavam:

  • A exceção [TaxException] é a exceção que a camada [dao] lançará ao encontrar um problema, seja no acesso aos dados, seja na natureza dos dados (dados incorretos);
  • a classe [Utilities] contém métodos úteis para gerenciar arquivos de texto (neste caso, um único método, [cutNewLineChar]);
  • A classe [readonly] [TaxAdminData] encapsula os dados da administração tributária. Ela é obtida pelo método estático [TaxAdminData::fromJsonFile($taxAdminDataFilename)] (ou [TaxAdminData::fromArray($data)]), que valida os dados e lança uma exceção [TaxException] se os dados forem inválidos.

Acrescentamos uma nova classe, [TaxPayerData], que encapsula os dados de um contribuinte e os resultados do cálculo de seu imposto ([TaxPayerData.php]):

<?php

declare(strict_types=1);

// namespace
namespace Application;

// os dados de um contribuinte e os resultados do cálculo de seu imposto: um objeto imutável
final readonly class TaxPayerData
{
    public function __construct(
        // dados necessários para calcular o imposto do contribuinte
        public string $married,
        public int $children,
        public int $salary,
        // resultados do cálculo do imposto (null enquanto o imposto não tiver sido calculado)
        public ?int $tax = null,
        public ?int $surcharge = null,
        public ?int $discount = null,
        public ?int $reduction = null,
        public ?float $rate = null,
    ) {
    }

    // retorna uma cópia do objeto completada com os resultados do cálculo do imposto
    // $results: array [tax, surcharge, discount, reduction, rate] retornado pela camada [business]
    public function withResults(array $results): static
    {
        return clone($this, [
            "tax" => $results["tax"],
            "surcharge" => $results["surcharge"],
            "discount" => $results["discount"],
            "reduction" => $results["reduction"],
            "rate" => $results["rate"],
        ]);
    }

    // string JSON do objeto
    public function __toString(): string
    {
        return json_encode(get_object_vars($this), JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
    }
}

Comentários

  • linha 9: assim como [TaxAdminData], a classe [TaxPayerData] é imutável: seus objetos passam de uma camada a outra sem risco de serem modificados no caminho;
  • Linhas 13–15: os dados do contribuinte necessários para calcular seu imposto;
  • Linhas 17–21: os resultados do cálculo do imposto. São campos anuláveis ([?int], [?float]) com o valor padrão [null]: um objeto [TaxPayerData] é criado primeiro pela camada [dao] contendo apenas os dados do contribuinte, a partir de [new TaxPayerData("yes", 2, 55555)], já que o imposto ainda não foi calculado. Os nomes dos atributos são os das chaves JSON do arquivo de resultados da versão 3: o arquivo [results.txt] manterá, assim, o mesmo formato;
  • Linhas 27–36: como o objeto é imutável, os resultados do cálculo não podem ser adicionados a ele. O método [withResults] retorna uma cópia do objeto complementada com os resultados. Ele usa o operador [clone] do PHP 8.5, que aceita como segundo parâmetro um array de atributos a serem modificados na cópia (veja o capítulo sobre classes). O curso de PHP 7 usava um objeto modificável com oito getters e oito setters;
  • linhas 39–42: o método [__toString] retorna a string JSON do objeto. Ele será usado para escrever o arquivo de resultados.

11.3. A camada [dao]

Aqui nos concentramos na camada [1] da nossa aplicação:

Image

11.3.1. A interface [InterfaceDao]

A interface da camada [dao] será a seguinte: [InterfaceDao.php]:

<?php

declare(strict_types=1);

// namespace
namespace Application;

// a interface da camada [dao]
// todos os métodos lançam uma exceção [TaxException] em caso de erro irrecuperável
interface InterfaceDao
{
    // leitura dos dados dos contribuintes
    // as linhas incorretas são relatadas no arquivo de texto [$errorsFilename]
    /** @return TaxPayerData[] */
    public function getTaxPayersData(string $taxPayersFilename, string $errorsFilename): array;

    // leitura dos dados da administração tributária (faixas de tributação e constantes)
    public function getTaxAdminData(): TaxAdminData;

    // salvamento dos resultados
    /** @param TaxPayerData[] $taxPayersData */
    public function saveResults(string $resultsFilename, array $taxPayersData): void;
}

Comentários

  • As especificações são as seguintes:
    • Os dados dos contribuintes são armazenados em um arquivo de texto;
    • os resultados do cálculo do imposto são gravados em um arquivo de texto;
    • Os eventuais erros são gravados em um arquivo de texto;
    • não se sabe em que formato os dados da administração tributária estão disponíveis. Para cada novo formato, a interface [InterfaceDao] deverá ser implementada por uma nova classe;
    • os métodos da interface que encontrarem um erro fatal ao acessar os dados devem lançar uma exceção [TaxException];
  • Linha 15: o método que recupera os dados dos contribuintes [marital status, number of children, annual salary]:
    • o primeiro parâmetro é o nome do arquivo de texto que contém esses dados;
    • o segundo parâmetro é o nome do arquivo de texto no qual devem ser registrados os eventuais erros encontrados;
  • Linha 14: o tipo [array] não especifica o que o array contém. O comentário de documentação [/** @return TaxPayerData[] */] (sintaxe PHPDoc) especifica que se trata de um array de objetos [TaxPayerData]. O PHP ignora isso, mas a extensão [PHP Intelephense] do [VS Code] o utiliza: ela passa a conhecer o tipo dos elementos do array e pode sugerir seus atributos durante a digitação;
  • linha 18: o método que recupera os dados da administração tributária. Nenhum parâmetro lhe é passado porque não sabemos como os dados são armazenados;
  • linha 22: o método que grava os resultados do cálculo do imposto em um arquivo de texto, cujo nome é passado como parâmetro.

Ao escrever a interface [InterfaceDao], sabemos que haverá diferentes maneiras de implementar o método [getTaxAdminData], conforme o modo como os dados da administração tributária estão armazenados. A interface [InterfaceDao] será, portanto, implementada por diferentes classes, cada uma tratando de uma forma específica de armazenamento desses dados (arquivo JSON, banco de dados, serviço web). Essas classes compartilharão, porém, código comum: a implementação dos métodos [getTaxPayersData] e [saveResults]. Como vimos no capítulo sobre traits, esse caso de uso pode ser implementado de duas maneiras:

  • Cria-se uma classe abstrata C que contém o código comum às classes derivadas. A classe C implementa a interface I, mas certos métodos — que devem ser definidos nas classes derivadas — são declarados abstratos na classe C, que portanto é ela própria abstrata. Criam-se então as classes C1 e C2 derivadas de C, cada uma implementando à sua maneira os métodos abstratos de sua classe-mãe C;
  • cria-se um trait T quase idêntico à classe abstrata C da solução anterior. Esse trait não implementa a interface I porque, sintaticamente, não pode. Criam-se então as classes C1 e C2, que implementam a interface I e usam o trait T. Resta a essas classes apenas implementar os métodos da interface I que não são implementados pelo trait T que elas importam.

Neste exemplo, usaremos um trait [TraitDao]. A versão 3 usava uma classe abstrata.

11.3.2. O trait [TraitDao]

O código do trait [TraitDao] é o seguinte: [TraitDao.php]:

<?php

declare(strict_types=1);

// namespace
namespace Application;

// implementação dos métodos de [InterfaceDao] que trabalham com arquivos de texto
trait TraitDao
{
    // separador dos campos de uma linha do arquivo de contribuintes (constante de trait, PHP 8.2)
    private const string SEPARATOR = ",";

    // leitura dos dados dos contribuintes
    #[\Override]
    public function getTaxPayersData(string $taxPayersFilename, string $errorsFilename): array
    {
        // array dos dados dos contribuintes
        $taxPayersData = [];
        // array dos erros
        $errors = [];
        // abertura do arquivo de dados dos contribuintes
        $taxPayersFile = is_readable($taxPayersFilename) ? fopen($taxPayersFilename, "r") : false;
        if ($taxPayersFile === false) {
            throw new TaxException("Unable to open the taxpayers' declarations [$taxPayersFilename] for reading", 12);
        }
        // o arquivo está aberto: teremos de fechá-lo aconteça o que acontecer
        try {
            // processamos a linha atual do arquivo de dados dos contribuintes
            // que tem o formato estado civil, número de filhos, salário anual
            $num = 0;  // nº da linha atual
            while (($line = fgets($taxPayersFile, 100)) !== false) {
                // mais uma linha
                $num++;
                // removemos a possível marca de fim de linha
                $line = Utilities::cutNewLineChar($line);
                // ignoramos as linhas vazias
                if (trim($line) === "") {
                    continue;
                }
                // a linha deve ter 3 campos married,children,salary
                $fields = array_map(trim(...), explode(self::SEPARATOR, $line));
                $error = count($fields) !== 3;
                if (!$error) {
                    [$married, $children, $salary] = $fields;
                    // o estado civil deve ser yes ou no
                    $married = strtolower($married);
                    // o número de filhos e o salário devem ser inteiros positivos ou zero
                    $error = !in_array($married, ["yes", "no"], true)
                        || !preg_match('/^\d+$/', $children)
                        || !preg_match('/^\d+$/', $salary);
                }
                // erro?
                if ($error) {
                    $errors[] = "line [$num] of the file [$taxPayersFilename] is incorrect";
                } else {
                    // armazenamos os dados do contribuinte
                    $taxPayersData[] = new TaxPayerData($married, (int) $children, (int) $salary);
                }
            }
            // chegamos ao fim do arquivo?
            if (!feof($taxPayersFile)) {
                // saímos do laço por causa de um erro de leitura
                throw new TaxException("Error while reading the line no. [" . ($num + 1) . "] of the file [$taxPayersFilename]", 13);
            }
        } finally {
            // fechamos o arquivo
            fclose($taxPayersFile);
        }
        // salvamos os erros em um arquivo de texto
        $this->saveLines($errorsFilename, $errors);
        // resultado da função
        return $taxPayersData;
    }

    // salvamento dos resultados
    #[\Override]
    public function saveResults(string $resultsFilename, array $taxPayersData): void
    {
        // cada elemento [TaxPayerData] é transformado em string JSON por seu método [__toString]
        $this->saveLines($resultsFilename, array_map(strval(...), $taxPayersData));
    }

    // salvamento de um array de linhas em um arquivo de texto
    private function saveLines(string $fileName, array $lines): void
    {
        // se o arquivo de texto [$fileName] não existir, ele é criado; caso contrário, é sobrescrito
        $data = implode("", array_map(fn(string $line): string => "$line\n", $lines));
        if (@file_put_contents($fileName, $data) === false) {
            throw new TaxException("Error while saving data to the text file [$fileName]", 14);
        }
    }
}

Comentários

  • Linha 9: aqui estamos definindo um trait, não uma classe;
  • Linha 12: uma constante de separador de campos (PHP 8.2), tipada (PHP 8.3): o separador de campos de uma linha do arquivo de contribuintes. Ela se torna uma constante da classe que usa o trait e é usada com a notação [self::SEPARATOR];
  • Linha 15: a partir do PHP 8.3, o atributo [#[\Override]] é aceito em um método de trait. Isso é verificado na classe que usa o trait: aqui, o método deve corresponder a um método da interface [InterfaceDao] implementada por essa classe;
  • Linhas 16–74: o método [getTaxPayersData] implementa o método de mesmo nome da interface [InterfaceDao]. Ele recupera os dados dos contribuintes [marital status, number of children, annual salary] do arquivo de texto de nome [$taxPayersFilename]. Retorna esses dados na forma de um array [$taxPayersData] contendo elementos do tipo [TaxPayerData] (linha 58);
  • O método [getTaxPayersData] é muito semelhante ao método [AbstractBaseTax::executeBatchTaxes] da versão 3, com as seguintes diferenças:
    • O método [getTaxPayersData] apenas recupera os dados dos contribuintes. Ele não realiza nenhum cálculo de imposto: esse é o papel da camada [business];
    • Assim como o método [executeBatchTaxes], ele sinaliza as linhas errôneas. Aqui, os erros são primeiro armazenados em um array chamado [$errors], que é gravado em um arquivo de texto ao final do processamento (linha 71). Dependendo da situação, esse array pode estar vazio ou não. Uma linha errônea não dispara mais uma exceção: cabe ao código chamador consultar o arquivo de erros;
    • em caso de erro fatal, uma exceção [TaxException] é lançada (linha 25, linha 64);
  • Linhas 23–26: o arquivo é aberto antes da estrutura [try / finally]. Se a abertura do arquivo falhar, uma exceção é lançada e não há nada a fechar. Se ela der certo, a cláusula [finally] (linhas 66–69) garante que o arquivo seja fechado, ocorra ou não uma exceção. Essa abordagem evita a verificação “O arquivo foi aberto?” presente na versão 3;
  • Linhas 62–65: observe o tratamento realizado na saída do laço de leitura. A função [fgets] tem o inconveniente de retornar [false] tanto quando a leitura chega ao fim do arquivo quanto quando falha por causa de um erro. Para distinguir os dois casos, verificamos se chegamos ao fim do arquivo usando a função [feof]. Se não for o caso, ocorreu um erro, e uma exceção é então lançada;
  • linhas 78–82: implementação do método [saveResults] da interface [InterfaceDao]. Cada elemento [TaxPayerData]do array é convertido em string pela função [strval], que chama o método [__toString] do objeto: isso resulta em sua string JSON. [strval(...)] refere-se à própria função [strval] (first-class callable, PHP 8.1);
  • linhas 85–92: o método privado [saveLines] grava um array de linhas em um arquivo de texto, com cada linha terminada pelo caractere de fim de linha \n;
  • linha 89: a função PHP [file_put_contents] grava uma string em um arquivo de texto. Ela abre o arquivo, grava a string nele e fecha o arquivo. Retorna [false] se ocorrer um erro. Nesse caso, o PHP também emite um aviso. O operador [@]suprime esse aviso: o erro é informado pela exceção lançada na linha seguinte, com uma mensagem mais clara.

O trait [TraitDao] implementou dois dos métodos da interface [InterfaceDao]: [getTaxPayersData] e [saveResults]. Ainda falta implementar o método [getTaxAdminData], que recupera os dados da administração tributária.

11.3.3. A classe [DaoTaxWithTaxAdminDataInJsonFile]

A classe [DaoTaxWithTaxAdminDataInJsonFile] implementa a interface [InterfaceDao] da seguinte forma:

<?php

declare(strict_types=1);

// namespace
namespace Application;

// uma camada [dao] que obtém os dados da administração tributária de um arquivo JSON
class DaoTaxWithTaxAdminDataInJsonFile implements InterfaceDao
{
    // o trait implementa os métodos [getTaxPayersData] e [saveResults] da interface
    use TraitDao;

    // o objeto do tipo [TaxAdminData] que contém os dados da administração tributária
    private readonly TaxAdminData $taxAdminData;

    // o construtor
    public function __construct(string $taxAdminDataFilename)
    {
        // pode lançar uma exceção [TaxException]
        $this->taxAdminData = TaxAdminData::fromJsonFile($taxAdminDataFilename);
    }

    // retorna os dados usados para calcular o imposto
    #[\Override]
    public function getTaxAdminData(): TaxAdminData
    {
        return $this->taxAdminData;
    }
}

Comentários

  • Linha 9: a classe [DaoTaxWithTaxAdminDataInJsonFile] implementa a interface [InterfaceDao];
  • Linha 12: a classe usa o trait [TraitDao], que, como sabemos, implementa os métodos [getTaxPayersData] e [saveResults] da interface [InterfaceDao]. Resta à classe apenas implementar o método [getTaxAdminData], que recupera os dados da administração tributária;
  • linha 15: o atributo do tipo [TaxAdminData] retornado pelo método [getTaxAdminData]. Ele é inicializado pelo construtor;
  • Linha 21: os dados da administração tributária são lidos do arquivo JSON. Se o arquivo estiver ausente ou for inválido, uma exceção [TaxException] é lançada ao código chamador.

Terminamos agora a camada [dao] da nossa aplicação: temos uma classe que implementa integralmente a interface [InterfaceDao] que definimos para nós mesmos. Podemos agora passar à camada [business].

11.4. A camada [business]

Vamos agora implementar a camada [2] da nossa arquitetura:

Image

11.4.1. A interface [InterfaceBusiness]

A interface da camada [business] será a seguinte: [InterfaceBusiness.php]:

<?php

declare(strict_types=1);

// namespace
namespace Application;

// a interface da camada [business]
interface InterfaceBusiness
{
    // cálculo do imposto de um contribuinte
    // retorna o array [tax, surcharge, discount, reduction, rate]
    public function calculateTax(string $married, int $children, int $salary): array;

    // cálculo dos impostos em modo batch
    // pode lançar uma exceção [TaxException] vinda da camada [dao]
    public function executeBatchTaxes(string $taxPayersFileName, string $resultsFileName, string $errorsFileName): void;
}

Comentários

  • Linha 13: a camada [business] pode calcular o valor do imposto de um contribuinte específico, desde que receba as seguintes informações: estado civil, número de filhos e salário anual. O método [calculateTax] é puramente um método “de negócio”: ele não se preocupa com a origem dos dados que usa. Não usa a camada [dao], portanto não lança exceção;
  • Linha 17: a camada [business] também pode calcular o valor do imposto de um grupo de contribuintes cujos dados estão reunidos no arquivo de texto de nome [$taxPayersFileName]. Ela grava os resultados no arquivo de texto de nome [$resultsFileName]. Os erros não fatais são registrados no arquivo de texto de nome [$errorsFileName]. O método [executeBatchTaxes] deve chamar a camada [dao], que cuida do acesso ao sistema de arquivos. Exceções podem então ser propagadas pela camada [dao]: o método [executeBatchTaxes] não as capturará; deixará que se propaguem até o script principal.

11.4.2. A classe [Business]

A classe [Business] implementa a interface [InterfaceBusiness] da seguinte forma:

<?php

declare(strict_types=1);

// namespace
namespace Application;

// a camada [business]
class Business implements InterfaceBusiness
{
    // dados da administração tributária
    private readonly TaxAdminData $taxAdminData;

    // a camada [dao] é injetada pelo construtor
    public function __construct(private readonly InterfaceDao $dao)
    {
        // recuperamos os dados usados para calcular o imposto
        // o método [getTaxAdminData] pode lançar uma exceção [TaxException]
        // deixamos então que ela suba até o código chamador
        $this->taxAdminData = $this->dao->getTaxAdminData();
    }

    // cálculo do imposto
    // --------------------------------------------------------------------------
    #[\Override]
    public function calculateTax(string $married, int $children, int $salary): array
    {
        // $married: yes, no
        // $children: número de filhos
        // $salary: salário anual
        // $this->taxAdminData: dados da administração tributária
        //
        // cálculo do imposto com filhos
        $result1 = $this->calculateTax2($married, $children, $salary);
        $tax1 = $result1["tax"];
        // cálculo do imposto sem filhos
        if ($children !== 0) {
            $result2 = $this->calculateTax2($married, 0, $salary);
            $tax2 = $result2["tax"];
            // aplicação do teto do quociente familiar
            $halfShareCeiling = $this->taxAdminData->halfShareQfCeiling;
            if ($children < 3) {
                // halfShareQfCeiling euros para os 2 primeiros filhos
                $tax2 = $tax2 - $children * $halfShareCeiling;
            } else {
                // halfShareQfCeiling euros para os 2 primeiros filhos, o dobro para os seguintes
                $tax2 = $tax2 - 2 * $halfShareCeiling - ($children - 2) * 2 * $halfShareCeiling;
            }
        } else {
            $tax2 = $tax1;
            $result2 = $result1;
        }
        // tomamos o maior imposto, com a alíquota e a parcela adicional correspondentes
        if ($tax1 > $tax2) {
            $tax = $tax1;
            $rate = $result1["rate"];
            $surcharge = $result1["surcharge"];
        } else {
            $surcharge = $tax2 - $tax1 + $result2["surcharge"];
            $tax = $tax2;
            $rate = $result2["rate"];
        }
        // cálculo de um possível desconto
        $discount = $this->getDiscount($married, $salary, $tax);
        $tax -= $discount;
        // cálculo de uma possível redução de imposto
        $reduction = $this->getReduction($married, $salary, $children, $tax);
        $tax -= $reduction;
        // resultado
        return [
            "tax" => (int) floor($tax),
            "surcharge" => (int) $surcharge,
            "discount" => (int) $discount,
            "reduction" => (int) $reduction,
            "rate" => $rate,
        ];
    }

Comentários

  • linha 9: a classe [Business] implementa a interface [InterfaceBusiness], ou seja, os métodos [calculateTax] e [executeBatchTaxes];
  • linha 12: o objeto do tipo [TaxAdminData], que encapsula os dados da administração tributária. Esses dados são necessários ao método de negócio [calculateTax];
  • Linhas 15–21: o construtor inicializa os dois atributos da classe:
    • o atributo [$dao], uma referência à camada [dao], é inicializado pela promoção do parâmetro do construtor. Isso é necessário para que a camada [business] saiba a quem recorrer quando precisar de dados externos. Observe que o tipo desse parâmetro é o da interface [InterfaceDao], o que permite à classe [Business] trabalhar com qualquer classe que implemente essa interface. O curso de PHP 7 também oferecia um setter [setDao]: ele não existe mais, pois a camada [dao] é injetada de uma vez por todas pelo construtor;
    • o atributo [$taxAdminData] é inicializado pela chamada ao método [getTaxAdminData] da camada [dao];
  • concluímos que, quando os métodos [calculateTax] e [executeBatchTaxes] são executados, os dois atributos [$dao] e [$taxAdminData] estão inicializados. O teste [$this->taxAdminData ??= $this->getTaxAdminData()] da versão 3 não é mais necessário;
  • linhas 26–77: este código vem do método [AbstractBaseTax::calculateTax] da versão 3. O mesmo vale para os métodos privados [calculateTax2], [getTaxableIncome], [getDiscount] e [getReduction], que não são reproduzidos aqui.

O método [Business::executeBatchTaxes] é o seguinte:

    // cálculo dos impostos em modo batch
    // --------------------------------------------------------------------------
    #[\Override]
    public function executeBatchTaxes(string $taxPayersFileName, string $resultsFileName, string $errorsFileName): void
    {
        // deixamos subir as exceções vindas da camada [dao]
        // recuperamos os dados dos contribuintes
        $taxPayersData = $this->dao->getTaxPayersData($taxPayersFileName, $errorsFileName);
        // calculamos o imposto de cada contribuinte
        $results = array_map(
            fn(TaxPayerData $taxPayerData): TaxPayerData => $taxPayerData->withResults(
                $this->calculateTax($taxPayerData->married, $taxPayerData->children, $taxPayerData->salary)
            ),
            $taxPayersData
        );
        // salvamento dos resultados
        $this->dao->saveResults($resultsFileName, $results);
    }
}

Comentários

  • Linha 188: o método deve chamar repetidamente o método [calculateTax] para cada contribuinte encontrado no arquivo de texto de nome [$taxPayersFileName] e gravar os resultados no arquivo de texto de nome [$resultsFileName]. Os eventuais erros não fatais encontrados são registrados no arquivo de texto de nome [$errorsFileName]. O método não lança nenhuma exceção por conta própria, mas deixa propagar as lançadas pela camada [dao];
  • Linha 192: os dados dos contribuintes são solicitados à camada [dao]. Essa camada retorna um array de elementos do tipo [TaxPayerData]. Se uma exceção ocorrer aqui, como ela não é capturada por um [catch], é propagada automaticamente ao código chamador, e o restante do método não é executado;
  • linhas 194–199: a função [array_map] aplica uma função a cada elemento do array [$taxPayersData] e retorna o array de resultados. A função aplicada é uma arrow function que calcula o imposto do contribuinte [$taxPayerData] e retorna uma cópia de [$taxPayerData] preenchida com os resultados do cálculo (linha 195). Observe que a arrow function usa [$this]: uma arrow function captura automaticamente as variáveis de seu contexto, inclusive [$this];
  • Linha 201: depois que o imposto foi calculado para todos os contribuintes, os resultados são gravados em um arquivo de texto. A camada [dao] realiza essa tarefa.

Em geral, a camada [business] é bastante simples de escrever, pois se comunica com a camada [dao], que cuida do acesso aos dados e do tratamento de erros associado.

11.5. O script principal

Vamos agora escrever o script da camada [3] da nossa arquitetura:

Image

O script principal é o seguinte: [main.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros e resultados das funções
declare(strict_types=1);

// namespace
namespace Application;

// inclusão das interfaces e classes
require_once __DIR__ . "/TaxException.php";
require_once __DIR__ . "/Utilities.php";
require_once __DIR__ . "/TaxAdminData.php";
require_once __DIR__ . "/TaxPayerData.php";
require_once __DIR__ . "/InterfaceDao.php";
require_once __DIR__ . "/TraitDao.php";
require_once __DIR__ . "/DaoTaxWithTaxAdminDataInJsonFile.php";
require_once __DIR__ . "/InterfaceBusiness.php";
require_once __DIR__ . "/Business.php";

// definição das constantes
const TAXPAYERSDATA_FILENAME = "taxpayersdata.txt";
const RESULTS_FILENAME = "results.txt";
const ERRORS_FILENAME = "errors.txt";
const TAXADMINDATA_FILENAME = "taxadmindata.json";

try {
    // criação da camada [dao]
    $dao = new DaoTaxWithTaxAdminDataInJsonFile(TAXADMINDATA_FILENAME);
    // criação da camada [business]
    $business = new Business($dao);
    // cálculo do imposto em modo batch
    $business->executeBatchTaxes(TAXPAYERSDATA_FILENAME, RESULTS_FILENAME, ERRORS_FILENAME);
    print "The results have been saved in the file [" . RESULTS_FILENAME . "]\n";
} catch (TaxException $ex) {
    // exibimos o erro
    print "Error no. {$ex->getCode()}: {$ex->getMessage()}\n";
}
// fim
print "Done\n";

Comentários

  • Linhas 10–18: carregam as classes, interfaces e traits da aplicação. Um trait deve ser carregado antes da classe que o usa;
  • linha 21: o nome do arquivo de dados dos contribuintes;
  • linha 22: o nome do arquivo de resultados;
  • linha 23: o nome do arquivo de erros;
  • linha 24: o nome do arquivo JSON que contém os dados da administração tributária;
  • linha 28: criação da camada [dao];
  • linha 30: criação da camada [business] com base na camada [dao];
  • linha 32: execução do método [executeBatchTaxes] da camada [business];
  • linhas 34–37: como vimos, as camadas [dao] e [business] podem lançar exceções. Elas são capturadas aqui.

11.6. Testes visuais

11.6.1. Teste nº 1

Execute o script [main.php] em uma janela de terminal aberta na pasta [version-04]:

1
2
3
> php main.php
The results have been saved in the file [results.txt]
Done

Com o arquivo de contribuintes [taxpayersdata.txt] da versão 3:

yes,2,55555
yes,2,50000
yes,3,50000
no,2,100000
no,3x,100000
no,3,100000
yes,3,100000
yes,5,100000x
yes,5,100000
no,0,100000
yes,2,30000
no,0,200000
yes,3,200000

é gerado o seguinte arquivo de erros [errors.txt]:

line [5] of the file [taxpayersdata.txt] is incorrect
line [8] of the file [taxpayersdata.txt] is incorrect

e o seguinte arquivo de resultados [results.txt]:

{"married":"yes","children":2,"salary":55555,"tax":2814,"surcharge":0,"discount":0,"reduction":0,"rate":0.14}
{"married":"yes","children":2,"salary":50000,"tax":1384,"surcharge":0,"discount":384,"reduction":347,"rate":0.14}
{"married":"yes","children":3,"salary":50000,"tax":0,"surcharge":0,"discount":720,"reduction":0,"rate":0.14}
{"married":"no","children":2,"salary":100000,"tax":19884,"surcharge":4480,"discount":0,"reduction":0,"rate":0.41}
{"married":"no","children":3,"salary":100000,"tax":16782,"surcharge":7176,"discount":0,"reduction":0,"rate":0.41}
{"married":"yes","children":3,"salary":100000,"tax":9200,"surcharge":2180,"discount":0,"reduction":0,"rate":0.3}
{"married":"yes","children":5,"salary":100000,"tax":4230,"surcharge":0,"discount":0,"reduction":0,"rate":0.14}
{"married":"no","children":0,"salary":100000,"tax":22986,"surcharge":0,"discount":0,"reduction":0,"rate":0.41}
{"married":"yes","children":2,"salary":30000,"tax":0,"surcharge":0,"discount":0,"reduction":0,"rate":0}
{"married":"no","children":0,"salary":200000,"tax":64210,"surcharge":7498,"discount":0,"reduction":0,"rate":0.45}
{"married":"yes","children":3,"salary":200000,"tax":42842,"surcharge":17283,"discount":0,"reduction":0,"rate":0.41}

Esses são os resultados da versão 3.

11.6.2. Teste nº 2

No script principal, atribuímos ao arquivo de contribuintes um nome de arquivo que não existe:

const TAXPAYERSDATA_FILENAME = "taxpayersdata2.txt";

Os resultados exibidos no console são os seguintes:

1
2
3
> php main.php
Error no. 12: Unable to open the taxpayers' declarations [taxpayersdata2.txt] for reading
Done

Apenas a mensagem da exceção lançada pela camada [dao] é exibida. No curso de PHP 7, a função [fopen] era chamada sobre o arquivo inexistente: o interpretador PHP exibia então um aviso antes da mensagem da exceção:

Warning: fopen(taxpayersdata2.txt): failed to open stream: No such file or directory in ...

O curso de PHP 7 suprimia essa mensagem instruindo o PHP a não exibir erros por meio da instrução [ini_set("display_errors", "0")]. Essa é a configuração correta para um servidor de produção (os erros são então gravados em um arquivo de log), mas, durante o desenvolvimento, é necessário ver todas as mensagens do PHP. Preferimos, portanto, não disparar o aviso: a camada [dao] usa a função [is_readable] para verificar se o arquivo pode ser lido antes de abri-lo.

11.7. Testes com [PHPUnit]

Os testes visuais são muito insuficientes:

  • geralmente nos limitamos a poucos testes;
  • podemos não prestar muita atenção durante essa verificação visual, e detalhes podem passar despercebidos.

No desenvolvimento profissional real, os testes são escritos como código e executados automaticamente, muitas vezes a cada alteração do código. O objetivo é tornar os testes o mais abrangentes possível. Para isso, usamos frameworks de teste.

Aqui, usaremos o [PHPUnit] [https://phpunit.de/], o framework de testes padrão do PHP. O curso de PHP 7 usava o framework [Codeception], escolhido porque se integrava ao IDE NetBeans — e que, aliás, usava o PHPUnit nos bastidores. Usaremos apenas uma pequena parte dos recursos do PHPUnit. A ideia é dispor de uma forma rápida, a cada nova versão do exercício de aplicação, de verificar se ela funciona. Testes bem-sucedidos dão ao desenvolvedor confiança no código que escreveu. Esse é um fator importante.

11.7.1. Instalando o [PHPUnit]

Como muitas bibliotecas PHP, o [PHPUnit] é instalado com o [Composer], o gerenciador de dependências do PHP, incluído no [Laragon]. A pasta [php8-oct-2026] que contém o código do curso inclui um arquivo chamado [composer.json] que lista as bibliotecas usadas pelo curso. O PHPUnit aparece ali na seção [require-dev], que contém as bibliotecas usadas exclusivamente no desenvolvimento:

1
2
3
    "require-dev": {
        "phpunit/phpunit": "^12.0"
    },

Se ainda não o fez, basta abrir um terminal na pasta [php8-oct-2026] e digitar o seguinte comando:

composer install

O [Composer] baixará então todas as bibliotecas listadas em [composer.json] para a pasta [vendor] dentro de [php8-oct-2026]. O PHPUnit é instalado ali junto com seu executável, [vendor/bin/phpunit]. Em um projeto que ainda não tenha o PHPUnit, ele seria adicionado com o comando [composer require --dev phpunit/phpunit], que o baixa e o registra na seção [require-dev] do arquivo [composer.json].

A versão 12 do PHPUnit exige o PHP 8.3 ou superior. Sua documentação está disponível em [https://docs.phpunit.de/].

11.7.2. O arquivo de configuração [phpunit.xml]

A pasta [php8-oct-2026] também contém o arquivo de configuração do PHPUnit, [phpunit.xml]. Quando o PHPUnit é iniciado a partir dessa pasta, ele usa automaticamente esse arquivo:

<?xml version="1.0" encoding="UTF-8"?>
<!-- configuração do PHPUnit para todos os testes do curso:
     php vendor/bin/phpunit scripts-console/tax/version-04/Tests -->
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
         colors="false"
         failOnDeprecation="true"
         failOnPhpunitDeprecation="true"
         failOnNotice="true"
         failOnWarning="true"
         displayDetailsOnTestsThatTriggerDeprecations="true"
         displayDetailsOnTestsThatTriggerNotices="true"
         displayDetailsOnTestsThatTriggerWarnings="true"
         cacheDirectory=".phpunit.cache">
    <source ignoreSuppressionOfDeprecations="true">
        <include>
            <directory>scripts-console</directory>
            <directory>scripts-web</directory>
        </include>
    </source>
</phpunit>

Comentários

  • Linha 5: o esquema XML, que descreve a sintaxe do arquivo. O [VS Code] o usa para validar o arquivo e sugerir os atributos possíveis;
  • Linha 6: nenhuma cor é usada na exibição dos resultados. Você pode usar [true] para exibir os testes bem-sucedidos em verde e os testes com falha em vermelho no terminal;
  • Linhas 7–10: um teste que dispara uma depreciação, uma nota ou um aviso do PHP é considerado uma falha, mesmo que suas asserções sejam verificadas. Essa é uma forma de impor um código PHP 8 limpo: por exemplo, usar um recurso obsoleto no PHP 8.5 faria os testes falharem;
  • linhas 11–13: nesses casos, o PHPUnit exibe os detalhes da mensagem do PHP;
  • linha 14: a pasta em que o PHPUnit armazena informações de uma execução para outra (por exemplo, os testes que falharam, para que sejam executados primeiro na vez seguinte);
  • linhas 15–20: as pastas que contêm o código-fonte testado. [ignoreSuppressionOfDeprecations] indica que uma depreciação é informada mesmo que tenha sido suprimida pelo operador [@].

11.7.3. Testes da camada [dao]

Os testes da versão 4 estão na pasta [version-04/Tests]. Uma classe de teste do PHPUnit:

  • estende a classe [PHPUnit\Framework\TestCase];
  • tem um nome terminado em [Test], em um arquivo de mesmo nome: é assim que o PHPUnit encontra as classes de teste em uma pasta;
  • tem métodos de teste públicos cujos nomes começam com [test];
  • pode ter um método chamado [setUp], executado antes de cada método de teste, e um método chamado [tearDown], executado depois de cada método de teste. Eles servem para montar o ambiente de teste e depois limpá-lo. Cada método de teste é, assim, executado em um ambiente novo, independente dos demais.

Em um método de teste, os resultados são verificados com métodos de asserção herdados de [TestCase], por exemplo:

Asserção
Verifica que
[assertSame($expected, $actual)]
os dois valores são idênticos ([===]: mesmo tipo e mesmo valor)
[assertEquals($expected, $actual)]
os dois valores são iguais ([==])
[assertEqualsWithDelta($expected, $actual, $delta)]
os dois números são iguais com tolerância de [$delta]
[assertTrue($actual)], [assertFalse($actual)], [assertNull($actual)]
o valor é [true], [false], [null]
[assertCount($n, $array)]
o array tem [$n] elementos
[assertStringContainsString($substring, $string)]
a string contém a substring
[expectException($class)]
o código a seguir lança uma exceção da classe especificada

Para construir os testes de uma versão do exercício de aplicação, usamos um ambiente idêntico ao do script principal [main.php] dessa versão: os mesmos arquivos são carregados e as mesmas camadas são construídas da mesma forma.

A classe de teste [DaoTest] é a seguinte: [Tests/DaoTest.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros e resultados das funções
declare(strict_types=1);

// namespace dos testes
namespace Application\Tests;

// as classes testadas
use Application\DaoTaxWithTaxAdminDataInJsonFile;
use Application\TaxException;
use Application\InterfaceDao;
use Application\TaxPayerData;
// as classes do PHPUnit
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\TestCase;

// carregamento das classes da camada [dao]
require_once __DIR__ . "/../TaxException.php";
require_once __DIR__ . "/../Utilities.php";
require_once __DIR__ . "/../TaxAdminData.php";
require_once __DIR__ . "/../TaxPayerData.php";
require_once __DIR__ . "/../InterfaceDao.php";
require_once __DIR__ . "/../TraitDao.php";
require_once __DIR__ . "/../DaoTaxWithTaxAdminDataInJsonFile.php";

final class DaoTest extends TestCase
{
    // a pasta da versão 4
    private const string ROOT = __DIR__ . "/..";
    // a camada [dao] testada
    private InterfaceDao $dao;
    // um arquivo temporário para os erros
    private string $errorsFilename;

    // executado antes de cada teste
    #[\Override]
    protected function setUp(): void
    {
        // criação da camada [dao]
        $this->dao = new DaoTaxWithTaxAdminDataInJsonFile(self::ROOT . "/taxadmindata.json");
        // um arquivo temporário
        $this->errorsFilename = tempnam(sys_get_temp_dir(), "errors");
    }

    // executado depois de cada teste
    #[\Override]
    protected function tearDown(): void
    {
        // exclusão do arquivo temporário
        unlink($this->errorsFilename);
    }

    // os dados da administração tributária
    public function testTaxAdminData(): void
    {
        $taxAdminData = $this->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);
    }

    // arquivos de dados do imposto incorretos
    public static function invalidFiles(): array
    {
        // [nome do arquivo, código de erro esperado]
        return [
            "non-existent file" => ["nonexistent.json", 1],
            "invalid JSON" => ["syntax.json", 2],
            "missing key" => ["missing-key.json", 4],
            "negative value" => ["negative-value.json", 6],
        ];
    }

    #[DataProvider("invalidFiles")]
    public function testInvalidTaxAdminData(string $file, int $code): void
    {
        // esperamos uma exceção [TaxException] com um código específico
        $this->expectException(TaxException::class);
        $this->expectExceptionCode($code);
        // construção de uma camada [dao] com um arquivo incorreto
        new DaoTaxWithTaxAdminDataInJsonFile(__DIR__ . "/data/$file");
    }

    // os dados dos contribuintes
    public function testTaxPayersData(): void
    {
        $taxPayersData = $this->dao->getTaxPayersData(self::ROOT . "/taxpayersdata.txt", $this->errorsFilename);
        // 11 contribuintes corretos
        $this->assertCount(11, $taxPayersData);
        $this->assertContainsOnlyInstancesOf(TaxPayerData::class, $taxPayersData);
        // o primeiro e o último
        $this->assertEquals(new TaxPayerData("yes", 2, 55555), $taxPayersData[0]);
        $this->assertEquals(new TaxPayerData("yes", 3, 200000), $taxPayersData[10]);
        // 2 linhas incorretas: linhas 5 e 8
        $errors = file($this->errorsFilename, FILE_IGNORE_NEW_LINES);
        $this->assertCount(2, $errors);
        $this->assertStringContainsString("line [5]", $errors[0]);
        $this->assertStringContainsString("line [8]", $errors[1]);
    }

    // um arquivo de contribuintes inexistente
    public function testNonExistentTaxPayersData(): void
    {
        $this->expectException(TaxException::class);
        $this->expectExceptionCode(12);
        $this->dao->getTaxPayersData(self::ROOT . "/nonexistent.txt", $this->errorsFilename);
    }
}

Comentários

  • linha 7: as classes de teste estão no namespace [Application\Tests], distinto do da aplicação;
  • Linhas 10–16: as classes usadas são importadas com a instrução [use]. As classes da aplicação estão no namespace [Application], e as do PHPUnit estão em [PHPUnit\Framework];
  • Linhas 19–25: carregam os arquivos da camada [dao], como em [main.php]. Os caminhos são relativos à pasta do arquivo de teste ([__DIR__]): os testes são executados independentemente da pasta a partir da qual o PHPUnit é iniciado e independentemente da localização da pasta [php8-oct-2026] no disco. O curso de PHP 7 usava caminhos absolutos ([C:/Data/...]) específicos da máquina do autor. As classes do PHPUnit, por sua vez, são carregadas automaticamente pelo carregador do [Composer], que é inicializado pelo PHPUnit;
  • linha 27: a classe de teste estende [TestCase];
  • linha 30: a pasta da versão 4, onde estão os arquivos de dados;
  • Linhas 38–44: antes de cada teste, a camada [dao] é construída como faz o [main.php], e um arquivo temporário é criado para os erros. A função [tempnam] cria um arquivo de nome único na pasta de arquivos temporários do sistema, retornada por [sys_get_temp_dir]. O curso de PHP 7 realizava essa tarefa no construtor da classe de teste: o construtor de [TestCase] não precisa mais ser redefinido a partir do PHPUnit 10;
  • linhas 48–52: após cada teste, o arquivo temporário é excluído;
  • linhas 55–73: teste dos dados da administração tributária. Verificamos que o conteúdo do objeto [TaxAdminData] retornado pela camada [dao] corresponde ao esperado. O método [assertSame] é usado: [assertSame(1551.0, ...)] verifica que o valor é o número real 1551.0; [assertSame(1551, ...)] falharia, pois o inteiro 1551 não é idêntico ao número real 1551.0. Para arrays, [assertSame] verifica que os dois arrays têm as mesmas chaves, na mesma ordem, com valores idênticos;
  • linhas 76–85: um provedor de dados (data provider). É um método público estático que retorna um array de conjuntos de dados. Cada conjunto é um array de argumentos a serem passados a um método de teste. A chave de cada conjunto (“arquivo inexistente”...) dá a ele um nome que aparecerá nos resultados dos testes;
  • linha 87: o atributo do PHP 8 [#[DataProvider]] indica que o método de teste [testInvalidTaxAdminData] deve ser executado uma vez para cada conjunto de dados do provedor [invalidFiles]. As versões do PHPUnit anteriores à 10 usavam, em vez disso, uma anotação em comentário: as anotações não são mais reconhecidas a partir do PHPUnit 12;
  • Linhas 88–95: verificam que uma camada construída com um arquivo de dados tributários incorreto lança uma exceção com o código de erro correto. Os métodos [expectException] e [expectExceptionCode] devem ser chamados antes do código que lança a exceção: o teste passa se a exceção for lançada; caso contrário, falha. Os arquivos incorretos estão na pasta [Tests/data]: um arquivo JSON malformado (vírgula ausente), um arquivo sem a chave [coupleDiscountCeiling] e um arquivo com um valor negativo;
  • Linhas 98–112: o teste da leitura dos dados dos contribuintes. O arquivo [taxpayersdata.txt] da versão 4 contém 11 linhas corretas e 2 linhas errôneas. Verificamos o número de contribuintes recuperados, seu tipo ([assertContainsOnlyInstancesOf]), o conteúdo do primeiro e do último registro e, em seguida, o conteúdo do arquivo de erros. Para comparar dois objetos [TaxPayerData], usamos [assertEquals]: dois objetos distintos nunca são idênticos ([===]), mas são iguais ([==]) se seus atributos forem iguais;
  • Linhas 115–120: um arquivo de contribuintes inexistente deve disparar uma exceção de código 12.

11.7.4. Executando os testes

Os testes são executados em um terminal aberto na pasta [php8-oct-2026], passando a pasta de testes ao PHPUnit:

> php vendor/bin/phpunit scripts-console/tax/version-04/Tests
PHPUnit 12.5.37 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.5.11
Configuration: .../php8-oct-2026/phpunit.xml

..................                                                18 / 18 (100%)

Time: 00:00.020, Memory: 16.00 MB

OK (18 tests, 52 assertions)
  • linha 5: o PHPUnit encontrou e usou o arquivo de configuração [phpunit.xml];
  • linha 7: um ponto por teste bem-sucedido. Os 18 testes são os das duas classes de teste [DaoTest] e [BusinessTest] (esta última é descrita no parágrafo seguinte): um teste executado com um provedor de dados conta como tantos testes quantos forem os conjuntos de dados;
  • linha 11: os resultados: todos os testes passaram.

A opção [--testdox] fornece uma exibição mais descritiva, na qual cada teste é descrito por uma frase composta pelo nome de seu método e pelo nome de seu conjunto de dados:

> php vendor/bin/phpunit --testdox scripts-console/tax/version-04/Tests
PHPUnit 12.5.37 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.5.11
Configuration: .../php8-oct-2026/phpunit.xml

..................                                                18 / 18 (100%)

Time: 00:00.006, Memory: 16.00 MB

Business (Application\Tests\Business)
 ✔ 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"

Dao (Application\Tests\Dao)
 ✔ Tax admin data
 ✔ Invalid tax admin data with data set "non-existent file"
 ✔ Invalid tax admin data with data set "invalid JSON"
 ✔ Invalid tax admin data with data set "missing key"
 ✔ Invalid tax admin data with data set "negative value"
 ✔ Tax payers data
 ✔ Non existent tax payers data

OK (18 tests, 52 assertions)

Vejamos agora um teste que falha. Na classe [BusinessTest], introduzimos um erro na redução esperada para o segundo contribuinte (346 em vez de 347). A execução dos testes produz então o seguinte resultado:

> php vendor/bin/phpunit scripts-console/tax/version-04/Tests
PHPUnit 12.5.37 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.5.11
Configuration: .../php8-oct-2026/phpunit.xml

.F................                                                18 / 18 (100%)

Time: 00:00.008, Memory: 16.00 MB

There was 1 failure:

1) Application\Tests\BusinessTest::testCalculateTax@couple, 2 children, 50000 with data ('yes', 2, 50000, 1385, [1384, 0, 384, 346, 0.14])
Failed asserting that two arrays are identical.
--- Expected
+++ Actual
@@ @@
     'tax' => 1384,
     'surcharge' => 0,
     'discount' => 384,
-    'reduction' => 346,
+    'reduction' => 347,
     'rate' => 0.14,
 ]

.../php8-oct-2026/scripts-console/tax/version-04/Tests/BusinessTest.php:84

FAILURES!
Tests: 18, Assertions: 52, Failures: 1.
  • linha 7: a letra F (Failure) indica o teste que falhou;
  • linha 13: o teste que falhou, junto com o nome e o conteúdo de seu conjunto de dados;
  • linhas 14–24: a asserção que falhou ([assertSame]) e a diferença entre os arrays esperado (-) e obtido (+);
  • linha 26: o arquivo e o número da linha da asserção que falhou;
  • linhas 28–29: o resumo.

Quando um teste nem chega a ser executado (por exemplo, porque um arquivo carregado por [require_once] não pode ser encontrado), o PHPUnit exibe o erro PHP correspondente, exatamente como a execução de um script PHP comum.

11.7.5. Testes da camada [business]

A classe de teste [BusinessTest] segue as mesmas regras de construção da classe [DaoTest]: [Tests/BusinessTest.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros e resultados das funções
declare(strict_types=1);

// namespace dos testes
namespace Application\Tests;

// as classes testadas
use Application\DaoTaxWithTaxAdminDataInJsonFile;
use Application\InterfaceBusiness;
use Application\Business;
// as classes do PHPUnit
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\TestCase;

// carregamento das classes das camadas [dao] e [business]
require_once __DIR__ . "/../TaxException.php";
require_once __DIR__ . "/../Utilities.php";
require_once __DIR__ . "/../TaxAdminData.php";
require_once __DIR__ . "/../TaxPayerData.php";
require_once __DIR__ . "/../InterfaceDao.php";
require_once __DIR__ . "/../TraitDao.php";
require_once __DIR__ . "/../DaoTaxWithTaxAdminDataInJsonFile.php";
require_once __DIR__ . "/../InterfaceBusiness.php";
require_once __DIR__ . "/../Business.php";

final class BusinessTest extends TestCase
{
    // a pasta da versão 4
    private const string ROOT = __DIR__ . "/..";
    // a camada [business] testada
    private InterfaceBusiness $business;

    // executado antes de cada teste
    #[\Override]
    protected function setUp(): void
    {
        // criação da camada [dao]
        $dao = new DaoTaxWithTaxAdminDataInJsonFile(self::ROOT . "/taxadmindata.json");
        // criação da camada [business]
        $this->business = new Business($dao);
    }

    // os contribuintes da tabela de valores oficiais
    public static function taxpayers(): array
    {
        // [married, children, salary, imposto oficial, resultados esperados do algoritmo]
        return [
            "couple, 2 children, 55555" => ["yes", 2, 55555, 2815,
                ["tax" => 2814, "surcharge" => 0, "discount" => 0, "reduction" => 0, "rate" => 0.14]],
            "couple, 2 children, 50000" => ["yes", 2, 50000, 1385,
                ["tax" => 1384, "surcharge" => 0, "discount" => 384, "reduction" => 347, "rate" => 0.14]],
            "couple, 3 children, 50000" => ["yes", 3, 50000, 0,
                ["tax" => 0, "surcharge" => 0, "discount" => 720, "reduction" => 0, "rate" => 0.14]],
            "single, 2 children, 100000" => ["no", 2, 100000, 19884,
                ["tax" => 19884, "surcharge" => 4480, "discount" => 0, "reduction" => 0, "rate" => 0.41]],
            "single, 3 children, 100000" => ["no", 3, 100000, 16782,
                ["tax" => 16782, "surcharge" => 7176, "discount" => 0, "reduction" => 0, "rate" => 0.41]],
            "couple, 3 children, 100000" => ["yes", 3, 100000, 9200,
                ["tax" => 9200, "surcharge" => 2180, "discount" => 0, "reduction" => 0, "rate" => 0.3]],
            "couple, 5 children, 100000" => ["yes", 5, 100000, 4230,
                ["tax" => 4230, "surcharge" => 0, "discount" => 0, "reduction" => 0, "rate" => 0.14]],
            "single, 0 children, 100000" => ["no", 0, 100000, 22986,
                ["tax" => 22986, "surcharge" => 0, "discount" => 0, "reduction" => 0, "rate" => 0.41]],
            "couple, 2 children, 30000" => ["yes", 2, 30000, 0,
                ["tax" => 0, "surcharge" => 0, "discount" => 0, "reduction" => 0, "rate" => 0.0]],
            "single, 0 children, 200000" => ["no", 0, 200000, 64211,
                ["tax" => 64210, "surcharge" => 7498, "discount" => 0, "reduction" => 0, "rate" => 0.45]],
            "couple, 3 children, 200000" => ["yes", 3, 200000, 42843,
                ["tax" => 42842, "surcharge" => 17283, "discount" => 0, "reduction" => 0, "rate" => 0.41]],
        ];
    }

    // um teste executado uma vez para cada contribuinte do data provider
    #[DataProvider("taxpayers")]
    public function testCalculateTax(string $married, int $children, int $salary, int $officialTax, array $expected): void
    {
        // cálculo do imposto
        $result = $this->business->calculateTax($married, $children, $salary);
        // o imposto é o do simulador oficial com margem de 1 euro
        $this->assertEqualsWithDelta($officialTax, $result["tax"], 1);
        // os resultados são exatamente os esperados (mesmas chaves, mesmos valores, mesmos tipos)
        $this->assertSame($expected, $result);
    }
}

Comentários

  • linhas 18–26: carregam os arquivos das camadas [dao] e [business]. O ambiente de teste é o mesmo de [main.php];
  • linhas 37–43: instanciação das camadas [dao] e [business], como em [main.php];
  • linhas 46–73: o provedor de dados: os onze contribuintes da tabela de valores oficiais. Cada conjunto de dados contém os dados do contribuinte, o valor do imposto gerado pelo simulador oficial da administração tributária [https://www3.impots.gouv.fr/simulateur/calcul_impot/2019/simplifie/index.htm] e os resultados esperados do algoritmo descrito no documento;
  • linha 76: o método [testCalculateTax] será executado onze vezes, uma por contribuinte. O curso de PHP 7 incluía originalmente onze métodos de teste quase idênticos, de [test1] a [test11]; o provedor de dados elimina essa duplicação;
  • linha 80: o cálculo do imposto é realizado pela camada [business];
  • linha 82: verificamos que o imposto calculado corresponde ao resultado do simulador oficial com tolerância de 1 euro. Vimos que problemas de arredondamento faziam o algoritmo do documento produzir resultados que diferiam dos oficiais em até 1 euro;
  • linha 84: verificamos que a tabela de resultados [tax, surcharge, discount, reduction, rate] é exatamente a esperada, inclusive quanto aos tipos de dados: inteiros para os valores monetários, um número real para a taxa. É por isso que a taxa do 9º contribuinte é escrita como 0.0 e não 0. Essa verificação precisa protege contra quaisquer alterações indesejadas no algoritmo em versões futuras.

Os resultados da execução desses testes são os mostrados no parágrafo anterior: todos os 11 testes da camada [business] passam.

11.7.6. PHPUnit no VS Code

A maneira mais fácil de executar os testes no [VS Code] é usar seu terminal integrado (menu Terminal / New Terminal): ele abre na pasta [php8-oct-2026] do projeto, e você digita ali o comando [php vendor/bin/phpunit scripts-console/tax/version-04/Tests]. A seta para cima do teclado recupera o último comando: executar novamente os testes após uma alteração de código exige apenas um toque de tecla.

Algumas opções úteis do comando [phpunit]:

  • [--testdox]: exibe os testes como frases;
  • [--filter testCalculateTax]: executa apenas os testes cujos nomes contêm o texto especificado;
  • [--stop-on-failure]: para na primeira falha.

Existem também extensões do [VS Code] que integram o PHPUnit ao explorador de testes do editor (por exemplo, a extensão “PHPUnit Test Explorer”): elas permitem executar um teste com um único clique e exibir os resultados ao lado do código. Na verdade, elas executam o mesmo comando [phpunit] que digitamos no terminal.

11.7.7. Testes das próximas versões

De agora em diante, os testes das camadas [dao] e [business] serão idênticos aos da versão 4. A única coisa que mudará é o ambiente de teste: os arquivos carregados e a forma como as camadas [dao] e [business] são construídas. Apresentaremos, portanto, apenas esse ambiente e os resultados dos testes.