Skip to content

8. Exercício prático – Versão 3

Vamos retomar o exercício que vimos anteriormente (versões 1 e 2) e resolvê-lo com código PHP que emprega classes. Colocaremos em prática o que aprendemos nos três capítulos anteriores:

  • uma classe (imutável) [readonly] para representar os dados da administração tributária;
  • uma interface, uma classe abstrata que a implementa parcialmente e uma classe derivada que a completa;
  • um único tipo de exceção, [TaxException], para relatar todos os erros da aplicação;
  • o atributo [#[\Override]] em todos os métodos que implementam um método de interface ou sobrescrevem um método da classe pai.

8.1. Estrutura de diretórios dos scripts

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

version-03
├── AbstractBaseTax.php
├── errors.txt
├── InterfaceTax.php
├── main.php
├── results.txt
├── taxadmindata.json
├── TaxAdminData.php
├── TaxException.php
├── taxpayersdata.txt
├── TaxWithTaxAdminDataInJsonFile.php
├── test-taxadmindata.php
└── Utilities.php

Cada classe ou interface está em um arquivo que leva o seu nome. Essa é uma convenção seguida universalmente em PHP (ela é inclusive exigida pelo padrão de carregamento automático PSR-4, que encontraremos com o [Composer]).

8.2. A exceção [TaxException]

Na versão 3, quando o construtor ou um método de uma classe encontra um erro, ele lança uma exceção [TaxException]:

<?php

declare(strict_types=1);

// namespace
namespace Application;

// a exceção lançada pelas classes da aplicação de cálculo do imposto
class TaxException extends \RuntimeException
{
    // sem código: o construtor herdado de [\RuntimeException] basta
    // __construct(string $message = "", int $code = 0, ?\Throwable $previous = null)
}

Comentários

  • Linha 6: a classe [TaxException] está no namespace [Application]. Todas as classes e interfaces da aplicação de cálculo de impostos ficarão nesse namespace;
  • linha 9: a classe [TaxException] estende a classe predefinida do PHP [RuntimeException]. Como vimos no capítulo sobre exceções, uma exceção é definida principalmente por seu tipo: é o tipo que permite capturá-la com uma cláusula [catch (TaxException $ex)];
  • Linhas 11–12: o curso de PHP 7 definia um construtor [__construct(string $message, int $code = 0)] que simplesmente chamava o construtor da classe pai. Isso é desnecessário: a classe herda o construtor de [RuntimeException], que aceita uma mensagem, um código de erro e uma eventual exceção anterior. Usaremos este último parâmetro para encapsular uma exceção de baixo nível (uma [JsonException], por exemplo) dentro de uma [TaxException].

8.3. A classe [TaxAdminData]

Na versão 2, os dados da administração tributária eram consolidados:

  • primeiro em um arquivo JSON;
  • depois, a partir desse arquivo JSON, em um array associativo.

Havíamos notado uma falha nessa solução: nada garante que o array associativo contenha todas as chaves esperadas ou que os valores associados sejam números. Na versão 3, os dados da administração tributária continuam no arquivo [taxadmindata.json] , mas com nomes de atributos diferentes, escritos segundo a convenção camelCase para nomes de atributos de classe:

{
    "limits": [9964, 27519, 73779, 156244, 0],
    "coeffR": [0, 0.14, 0.3, 0.41, 0.45],
    "coeffN": [0, 1394.96, 5798, 13913.69, 20163.45],
    "halfShareQfCeiling": 1551,
    "singleIncomeCeilingForReduction": 21037,
    "coupleIncomeCeilingForReduction": 42074,
    "halfShareReductionValue": 3797,
    "singleDiscountCeiling": 1196,
    "coupleDiscountCeiling": 1970,
    "coupleTaxCeilingForDiscount": 2627,
    "singleTaxCeilingForDiscount": 1595,
    "tenPercentAllowanceMax": 12502,
    "tenPercentAllowanceMin": 437
}

Na versão 2, esse arquivo servia para inicializar um array associativo. Na versão 3, ele inicializará um objeto da seguinte classe: [TaxAdminData]:

<?php

declare(strict_types=1);

// namespace
namespace Application;

// os dados da administração tributária: um objeto imutável
final readonly class TaxAdminData
{
    // os nomes dos arrays e das constantes esperados nos dados
    private const array ARRAYS = ["limits", "coeffR", "coeffN"];
    private const array CONSTANTS = [
        "halfShareQfCeiling",
        "singleIncomeCeilingForReduction",
        "coupleIncomeCeilingForReduction",
        "halfShareReductionValue",
        "singleDiscountCeiling",
        "coupleDiscountCeiling",
        "coupleTaxCeilingForDiscount",
        "singleTaxCeilingForDiscount",
        "tenPercentAllowanceMax",
        "tenPercentAllowanceMin",
    ];

    // construtor privado: é preciso passar pelos métodos [from...]
    private function __construct(
        // faixas de tributação
        public array $limits,
        public array $coeffR,
        public array $coeffN,
        // constantes de cálculo do imposto
        public float $halfShareQfCeiling,
        public float $singleIncomeCeilingForReduction,
        public float $coupleIncomeCeilingForReduction,
        public float $halfShareReductionValue,
        public float $singleDiscountCeiling,
        public float $coupleDiscountCeiling,
        public float $coupleTaxCeilingForDiscount,
        public float $singleTaxCeilingForDiscount,
        public float $tenPercentAllowanceMax,
        public float $tenPercentAllowanceMin,
    ) {
    }

    // construção a partir de um arquivo JSON
    public static function fromJsonFile(string $taxAdminDataFilename): self
    {
        // recuperamos o conteúdo do arquivo de dados do imposto
        $fileContents = is_readable($taxAdminDataFilename) ? file_get_contents($taxAdminDataFilename) : false;
        // erro?
        if ($fileContents === false) {
            throw new TaxException("The data file [$taxAdminDataFilename] does not exist", 1);
        }
        // decodificamos o JSON em um array associativo
        try {
            $data = json_decode($fileContents, true, flags: JSON_THROW_ON_ERROR);
        } catch (\JsonException $ex) {
            throw new TaxException("The JSON data file [$taxAdminDataFilename] could not be processed correctly", 2, $ex);
        }
        // o JSON deve ser um objeto {...}
        if (!is_array($data)) {
            throw new TaxException("The JSON data file [$taxAdminDataFilename] does not contain a JSON object", 3);
        }
        // construção do objeto a partir do array associativo
        return self::fromArray($data);
    }

    // construção a partir de um array associativo [nome => valor]
    public static function fromArray(array $data): self
    {
        // as chaves presentes devem ser exatamente as esperadas
        $expected = [...self::ARRAYS, ...self::CONSTANTS];
        $missing = array_first(array_diff($expected, array_keys($data)));
        if ($missing !== null) {
            throw new TaxException("The attribute [$missing] of [TaxAdminData] has not been initialized", 4);
        }
        $unknown = array_first(array_diff(array_keys($data), $expected));
        if ($unknown !== null) {
            throw new TaxException("The attribute [$unknown] does not exist in [TaxAdminData]", 5);
        }
        // verificamos e convertemos cada valor
        $values = [];
        foreach (self::ARRAYS as $key) {
            // um array não vazio de reais >= 0
            if (!is_array($data[$key]) || !array_is_list($data[$key]) || count($data[$key]) === 0) {
                throw new TaxException("The value of attribute [$key] is invalid", 6);
            }
            $values[$key] = array_map(fn(mixed $value): float => self::check($key, $value), $data[$key]);
        }
        // os três arrays devem ter o mesmo tamanho
        $size = count($values["limits"]);
        if (count($values["coeffR"]) !== $size || count($values["coeffN"]) !== $size) {
            throw new TaxException("The arrays [limits, coeffR, coeffN] do not have the same size", 7);
        }
        foreach (self::CONSTANTS as $key) {
            // um real >= 0
            $values[$key] = self::check($key, $data[$key]);
        }
        // construção do objeto: as chaves do array tornam-se argumentos nomeados
        return new self(...$values);
    }

    // verifica se um valor é um número real positivo ou zero e o retorna como [float]
    private static function check(string $key, mixed $value): float
    {
        // aceitamos 1551, 1551.78, "1551", mas não "xx", true, null, -3...
        if ((is_int($value) || is_float($value) || (is_string($value) && is_numeric($value)))
            && (float) $value >= 0) {
            return (float) $value;
        }
        throw new TaxException("The value of attribute [$key] is invalid", 6);
    }

    // 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: a classe é [readonly]: todos os seus atributos são somente leitura. Depois de criado, um objeto [TaxAdminData] não pode mais ser modificado: ele pode ser compartilhado com segurança entre todas as partes da aplicação. Ela também é [final]: não pode ser derivada;
  • linhas 12–24: duas constantes de classe privadas listam os nomes dos atributos esperados nos dados. A partir do PHP 8.3, uma constante de classe pode ser tipada (aqui, [array]);
  • linhas 27–43: o construtor usa a promoção de parâmetros: cada parâmetro se torna um atributo público com o mesmo nome e o mesmo tipo. Os atributos têm os mesmos nomes das chaves do arquivo JSON. Esse é um ponto importante que simplifica bastante a escrita do código, como veremos. As faixas de tributação são arrays ([array]), e as constantes de cálculo são números reais ([float]). No PHP 7, os atributos não podiam ser tipados (como observado no curso de PHP 7); eles podem ser tipados a partir do PHP 7.4;
  • Linha 27: o construtor é private; [new TaxAdminData(...)] não pode ser escrito fora da classe. Um objeto [TaxAdminData] só pode ser obtido por meio dos métodos estáticos [fromJsonFile] e [fromArray], que verificam a validade dos dados. Isso garante que todo objeto [TaxAdminData] contenha dados válidos. Em PHP, uma classe só pode ter um construtor. Os métodos estáticos que constroem um objeto, às vezes chamados de “construtores nomeados”, permitem várias maneiras de construir um objeto. O curso de PHP 7 usava métodos de instância [setFromJsonFile] chamados em um objeto vazio: [(new TaxAdminData())->setFromJsonFile(...)]. Isso é impossível com um objeto imutável;
  • Linhas 47–67: o método [fromJsonFile] constrói um objeto [TaxAdminData] a partir do arquivo JSON, cujo nome lhe é passado. Seu tipo de retorno, [self], refere-se à própria classe;
  • linhas 50–53: o conteúdo do arquivo é lido. Se isso não for possível, uma exceção [TaxException] é lançada. Essa exceção se propagará até o script principal;
  • linhas 56–60: o conteúdo do arquivo, em JSON, é decodificado. Com a opção [JSON_THROW_ON_ERROR] (PHP 7.3), a função [json_decode] lança uma exceção [JsonException] quando o JSON é inválido, em vez de retornar silenciosamente [null]. Observe o argumento nomeado [flags:], que evita ter de atribuir um valor ao terceiro parâmetro [depth] de [json_decode]. A exceção [JsonException] é encapsulada em uma [TaxException]: o código chamador só precisa tratar um tipo de exceção, mas pode determinar a causa original usando [$ex->getPrevious()];
  • linhas 62–64: um arquivo contendo, por exemplo, apenas o número 12 é um JSON válido; é preciso verificar que um array foi de fato obtido;
  • linha 66: o restante do trabalho é delegado ao método [fromArray]. Esse método é público: ele poderá ser usado em uma versão futura em que os dados da administração tributária venham de um banco de dados;
  • Linhas 73–81: verificamos que as chaves do array [$data] são exatamente os nomes esperados. [[...self::ARRAYS, ...self::CONSTANTS]] cria um array contendo os elementos de ambos os arrays. A função [array_diff] retorna os elementos do primeiro array que estão ausentes do segundo, e a função [array_first] (PHP 8.5) retorna o primeiro elemento de um array ou [null] se o array estiver vazio. Isso detecta uma chave ausente seguida de uma chave desconhecida. Esse é o erro mais comum: um erro de digitação em um nome de atributo no arquivo [taxadmindata.json]. No curso de PHP 7, o laço [$this->$key = $value] criava silenciosamente um atributo dinâmico com o nome incorreto. Desde o PHP 8.2, a criação de atributos dinâmicos está obsoleta e é proibida dentro de uma classe [readonly];
  • linhas 84–90: cada um dos três arrays deve ser uma lista não vazia (função [array_is_list], PHP 8.1) cujos elementos são todos números reais positivos ou nulos. A função [array_map] aplica o método [check] a cada elemento;
  • linhas 92–95: os três arrays de faixas de tributação devem ter o mesmo tamanho;
  • linhas 96–99: cada uma das constantes de cálculo deve ser um número real positivo ou nulo;
  • Linha 101: o array [$values] usa como chaves os nomes dos parâmetros do construtor. O operador [...], quando aplicado a um array com chaves string, converte cada elemento em um argumento nomeado (PHP 8.1): essa linha equivale a [new self(limits: $values["limits"], coeffR: $values["coeffR"], ...)]. É aqui que a escolha de nomes idênticos para as chaves JSON e os atributos da classe simplifica o código;
  • Linhas 105–113: o método [check] verifica se um valor [$value] de tipo desconhecido ([mixed]) é um número positivo ou nulo. Conforme as informações do arquivo JSON, o valor lido pode ser um inteiro (1551), um número de ponto flutuante (1551.78), uma string conversível em número ("1551"), uma string não conversível ("xx"), um booleano... A função [is_numeric] retorna [true] para uma string que representa um número. O curso de PHP 7 realizava essa verificação com uma expressão regular e retornava um objeto [stdClass] indicando se havia ocorrido um erro. Aqui, um erro dispara uma exceção, e o método simplesmente retorna o número na forma de um [float];
  • Linha 116: o método [__toString] retorna a string JSON contendo os atributos do objeto. A função [get_object_vars] retorna um array associativo [attribute name => value].

8.3.1. Por que não há mais getters e setters?

O curso de PHP 7 declarava os atributos como privados e escrevia um getter e um setter para cada um (26 métodos), gerados automaticamente pelo IDE NetBeans. Os setters eram “fluentes”: retornavam o objeto [$this], o que permitia chamadas encadeadas como [$data->setLimits($limits)->setCoeffR($coeffR)].

Com o PHP 8, esse código não é mais necessário:

  • os getters serviam para ler atributos privados. Os atributos [readonly] podem ser tornados públicos com segurança, já que não podem ser modificados: escrevemos [$taxAdminData->halfShareQfCeiling] em vez de [$taxAdminData->getHalfShareQfCeiling()];
  • os setters serviam para inicializar o objeto e permitiam validar os valores. Um objeto imutável é inicializado de uma vez por todas pelo seu construtor, e a validação é feita pelos métodos [fromJsonFile] e [fromArray];
  • Os atributos tipados garantem o tipo dos valores. O curso de PHP 7 observava que a instrução [$this->halfShareQfCeiling = 'abcd'] era possível: com atributos [float] e [declare(strict_types=1)], ela causa um erro [TypeError].

O script [test-taxadmindata.php] verifica o funcionamento da classe [TaxAdminData]:

<?php

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

// namespace
namespace Application;

// inclusão das classes
require_once __DIR__ . "/TaxException.php";
require_once __DIR__ . "/TaxAdminData.php";

// um objeto válido
$taxAdminData = TaxAdminData::fromJsonFile("taxadmindata.json");
print "$taxAdminData\n";
print "halfShareQfCeiling=" . $taxAdminData->halfShareQfCeiling . "\n";
// o objeto é imutável
try {
    $taxAdminData->halfShareQfCeiling = 2000;
} catch (\Error $ex) {
    print $ex::class . ": " . $ex->getMessage() . "\n";
}
// o construtor é privado
try {
    $taxAdminData = new TaxAdminData([], [], []);
} catch (\Error $ex) {
    print $ex::class . ": " . $ex->getMessage() . "\n";
}

// dados incorretos
$valid = json_decode(file_get_contents("taxadmindata.json"), true, flags: JSON_THROW_ON_ERROR);
$tests = [
    // arquivo inexistente
    fn() => TaxAdminData::fromJsonFile("xx.json"),
    // arquivo que não é JSON
    fn() => TaxAdminData::fromJsonFile("taxpayersdata.txt"),
    // chave ausente
    fn() => TaxAdminData::fromArray(array_diff_key($valid, ["halfShareQfCeiling" => 0])),
    // chave desconhecida (erro de digitação)
    fn() => TaxAdminData::fromArray(["halfShareQFCeiling" => 1551] + $valid),
    // valor não numérico
    fn() => TaxAdminData::fromArray(["halfShareQfCeiling" => "xx"] + $valid),
    // valor negativo em um array
    fn() => TaxAdminData::fromArray(["coeffR" => [0, 0.14, -0.3, 0.41, 0.45]] + $valid),
    // arrays de tamanhos diferentes
    fn() => TaxAdminData::fromArray(["limits" => [9964, 27519, 73779, 0]] + $valid),
];
foreach ($tests as $test) {
    try {
        $test();
    } catch (TaxException $ex) {
        print "TaxException no. {$ex->getCode()}: {$ex->getMessage()}\n";
    }
}
// um valor "1551" é aceito e convertido em real
$taxAdminData = TaxAdminData::fromArray(["halfShareQfCeiling" => "1551"] + $valid);
var_dump($taxAdminData->halfShareQfCeiling);

Comentários

  • linha 14: construção de um objeto [TaxAdminData] válido a partir do arquivo [taxadmindata.json];
  • linha 15: o objeto é inserido em uma string: seu método [__toString] é chamado;
  • linha 19: tentativa de modificar um atributo somente leitura;
  • linha 25: tentativa de usar o construtor privado;
  • linha 31: o array associativo de dados válidos;
  • linhas 32–47: um array de arrow functions, cada uma construindo um objeto [TaxAdminData] a partir de dados inválidos. Os dados inválidos são obtidos modificando-se uma cópia do array [$valid]. Ao aplicar o operador [+] a dois arrays, os elementos do array da esquerda têm precedência em caso de chave comum. A função [array_diff_key] remove do primeiro array as chaves presentes no segundo;
  • linhas 48–54: cada função é executada e a exceção esperada é exibida;
  • linha 56: uma string numérica é aceita e convertida em um número real.

Resultados:

> php test-taxadmindata.php
{"limits":[9964,27519,73779,156244,0],"coeffR":[0,0.14,0.3,0.41,0.45],"coeffN":[0,1394.96,5798,13913.69,20163.45],"halfShareQfCeiling":1551,"singleIncomeCeilingForReduction":21037,"coupleIncomeCeilingForReduction":42074,"halfShareReductionValue":3797,"singleDiscountCeiling":1196,"coupleDiscountCeiling":1970,"coupleTaxCeilingForDiscount":2627,"singleTaxCeilingForDiscount":1595,"tenPercentAllowanceMax":12502,"tenPercentAllowanceMin":437}
halfShareQfCeiling=1551
Error: Cannot modify readonly property Application\TaxAdminData::$halfShareQfCeiling
Error: Call to private Application\TaxAdminData::__construct() from global scope
TaxException no. 1: The data file [xx.json] does not exist
TaxException no. 2: The JSON data file [taxpayersdata.txt] could not be processed correctly
TaxException no. 4: The attribute [halfShareQfCeiling] of [TaxAdminData] has not been initialized
TaxException no. 5: The attribute [halfShareQFCeiling] does not exist in [TaxAdminData]
TaxException no. 6: The value of attribute [halfShareQfCeiling] is invalid
TaxException no. 6: The value of attribute [coeffR] is invalid
TaxException no. 7: The arrays [limits, coeffR, coeffN] do not have the same size
float(1551)
  • linha 2: a string JSON do objeto. Observe que os números reais sem parte decimal (1551.0) são escritos sem ela (1551) pela função [json_encode];
  • Linhas 4–5: os dois erros [Error] causados pela modificação de um atributo [readonly] e pela chamada de um construtor privado. São erros de programação, não erros de dados: eles não são convertidos em [TaxException];
  • Linhas 6–12: todos os dados incorretos são detectados, cada um com uma mensagem e um código de erro diferentes;
  • linha 13: a string "1551" foi convertida em um número de ponto flutuante.

8.4. A interface [InterfaceTax]

Vamos agora definir a seguinte interface [InterfaceTax]: [InterfaceTax.php]:

<?php

declare(strict_types=1);

// namespace
namespace Application;

interface InterfaceTax
{
    // recupera os dados da administração tributária usados para calcular o imposto
    // pode lançar a exceção TaxException
    public function getTaxAdminData(): TaxAdminData;

    // a interface sabe calcular um imposto
    public function calculateTax(string $married, int $children, int $salary): array;

    // a interface sabe processar dados em arquivos de texto
    // $taxPayersFileName: arquivo de dados dos contribuintes no formato estado civil, número de filhos, salário anual
    // $resultsFileName: arquivo de resultados no formato estado civil, número de filhos, salário anual, valor do imposto...
    // $errorsFileName: arquivo dos erros encontrados
    // pode lançar a exceção TaxException
    public function executeBatchTaxes(string $taxPayersFileName, string $resultsFileName, string $errorsFileName): void;
}

Comentários

  • linha 8: a interface de cálculo de impostos. Ela também está no namespace [Application];
  • linha 12: o método [getTaxAdminData] recuperará os dados da administração tributária em um objeto do tipo [TaxAdminData], que acabamos de apresentar. Como esses dados podem estar armazenados em um arquivo, em um banco de dados ou até mesmo na rede, o método [getTaxAdminData] pode falhar ao recuperá-los. Nesse caso, ele lançará uma exceção do tipo [TaxException]. Essa é a maneira padrão, na programação orientada a objetos, de sinalizar um erro encontrado em um método ou em um construtor;
  • linha 15: o método [calculateTax] calculará o imposto de um contribuinte;
  • linha 22: o método [executeBatchTaxes] calcula o imposto de vários contribuintes;
    • [$taxPayersFileName] é o nome do arquivo de texto que contém os dados dos contribuintes;
    • [$resultsFileName] é o nome do arquivo de texto que contém os valores dos impostos desses contribuintes;
    • [$errorsFileName] é o nome do arquivo de texto que contém os erros encontrados durante o processamento desses arquivos.

O conteúdo do arquivo de texto de contribuintes [taxpayersdata.txt] é o seguinte:

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

Observe que as linhas 5 e 8 contêm entradas incorretas. As outras onze linhas correspondem aos onze contribuintes listados na tabela de valores oficiais.

8.5. A classe [Utilities]

Definimos também uma classe chamada [Utilities] em um arquivo chamado [Utilities.php]:

<?php

declare(strict_types=1);

// namespace
namespace Application;

// uma classe de funções utilitárias: não pode ser instanciada nem derivada
final class Utilities
{
    // construtor privado: a classe não pode ser instanciada
    private function __construct()
    {
    }

    public static function cutNewLineChar(string $line): string
    {
        // removemos a marca de fim de linha de $line, se existir
        // (\r\n no Windows, \n no Unix)
        return rtrim($line, "\r\n");
    }
}

Comentários

  • Linha 9: a classe [Utilities] também está no namespace [Application]. Ela contém apenas métodos estáticos: não há razão para instanciá-la ou derivá-la. O curso de PHP 7 a declarava abstrata para impedir sua instanciação, lamentando que o PHP se recusasse a declará-la ao mesmo tempo [final] e [abstract]. Isso continua valendo. A prática atual é declará-la como [final] (não derivável) e dar-lhe um construtor privado (que não pode ser instanciado de fora);
  • linha 16: o método [cutNewLineChar] remove quaisquer caracteres de fim de linha do texto passado a ele como parâmetro. É um método estático, ou seja, será chamado na forma [Utilities::cutNewLineChar($line)]. Seu código é o mesmo da função de mesmo nome da versão 2.

8.6. A classe abstrata [AbstractBaseTax]

A interface [InterfaceTax] será implementada pela seguinte classe abstrata [AbstractBaseTax] [AbstractBaseTax.php]:

<?php

declare(strict_types=1);

// namespace
namespace Application;

// uma classe abstrata que implementa a interface [InterfaceTax]
abstract class AbstractBaseTax implements InterfaceTax
{
    // os dados da administração tributária
    private ?TaxAdminData $taxAdminData = null;

    // dados necessários para calcular o imposto: as classes derivadas sabem onde encontrá-los
    #[\Override]
    abstract public function getTaxAdminData(): TaxAdminData;

    // 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
        //
        // recuperamos os dados da administração tributária, se ainda não foi feito
        $this->taxAdminData ??= $this->getTaxAdminData();
        // 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 [AbstractBaseTax] implementa a interface [InterfaceTax];
  • Linha 12: os dados da administração tributária serão armazenados no atributo privado [$taxAdminData]. Seu tipo, [?TaxAdminData], significa “um objeto [TaxAdminData] ou o valor [null]”. Seu valor inicial é [null];
  • linha 16: o método [getTaxAdminData] da interface. Ainda não sabemos como defini-lo: vimos um caso em que os dados da administração tributária eram recuperados de um arquivo JSON (versão 2). Veremos outro caso em que os dados serão recuperados de um banco de dados. Caberá às classes derivadas definir o conteúdo do método [getTaxAdminData]. O método é, portanto, declarado abstrato, o que obriga a própria classe a ser declarada abstrata. Essa declaração é opcional: uma classe abstrata que implementa uma interface não é obrigada a redeclarar os métodos que não implementa. No entanto, ela torna o código mais legível. O atributo [#[\Override]] (PHP 8.3) indica que o método pertence a uma interface ou a uma classe pai: se o nome estiver incorreto, o PHP sinaliza o erro;
  • Linhas 21–73: a função de cálculo de impostos já encontrada nas versões 1 e 2. Seus parâmetros mudaram: a versão 2 recebia o array associativo [$taxAdminData] como primeiro parâmetro, enquanto a versão 3 usa o atributo [$this->taxAdminData]. A primeira diferença entre essas duas soluções é uma diferença na visibilidade dos dados tributários:
    • na versão 2, o array associativo [$taxAdminData] não tinha visibilidade global. Ele era, portanto, passado como parâmetro a todas as funções de cálculo de impostos;
    • na versão 3, o atributo [$this->taxAdminData] é visível em todos os métodos da classe. Ele, portanto, não é mais passado como parâmetro;
  • Uma segunda diferença decorre do fato de que a versão 3 substitui funções por métodos de classe. Cada chamada de método agora é feita com a expressão [$this->method(...)] (linha 31, linha 61);
  • Linha 29: uma terceira diferença é que, quando o método [calculateTax] começa seu trabalho, ele não sabe se o atributo [$taxAdminData] de que precisa foi inicializado. Na verdade, a classe não tem nenhum construtor que o inicialize. Cabe, portanto, ao método [calculateTax] fazê-lo usando o método [getTaxAdminData]. O operador [??=] (PHP 7.4) atribui o valor da direita à variável da esquerda somente se a variável for igual a [null]. A linha equivale a [if ($this->taxAdminData === null) { $this->taxAdminData = $this->getTaxAdminData(); }];
  • Linha 38: os dados da administração tributária são lidos diretamente dos atributos públicos somente leitura do objeto [TaxAdminData];
  • Além dessas diferenças, o método de cálculo de impostos permanece o mesmo das versões anteriores.

Os métodos privados para calcular o imposto são os seguintes:

    // --------------------------------------------------------------------------
    private function calculateTax2(string $married, int $children, float $salary): array
    {
        // número de partes
        $nbShares = match ($married) {
            "yes" => $children / 2 + 2,
            "no" => $children / 2 + 1,
        };
        // 1 parte por filho a partir do 3º
        if ($children >= 3) {
            // mais meia parte para cada filho a partir do 3º
            $nbShares += 0.5 * ($children - 2);
        }
        // renda tributável
        $taxableIncome = $this->getTaxableIncome($salary);
        // parcela adicional
        $surcharge = floor($taxableIncome - 0.9 * $salary);
        // para problemas de arredondamento
        if ($surcharge < 0) {
            $surcharge = 0;
        }
        // quociente familiar
        $quotient = $taxableIncome / $nbShares;
        // as faixas de tributação (cópias dos arrays do objeto)
        $limits = $this->taxAdminData->limits;
        $coeffR = $this->taxAdminData->coeffR;
        $coeffN = $this->taxAdminData->coeffN;
        // é colocado no final do array limits para interromper o laço seguinte
        $limits[count($limits) - 1] = $quotient;
        // cálculo do imposto
        $i = 0;
        while ($quotient > $limits[$i]) {
            $i++;
        }
        // agora podemos calcular o imposto
        $tax = floor($taxableIncome * $coeffR[$i] - $nbShares * $coeffN[$i]);
        // resultado
        return ["tax" => $tax, "surcharge" => $surcharge, "rate" => $coeffR[$i]];
    }

    // taxableIncome=annualSalary-allowance
    // a dedução tem um mínimo e um máximo
    private function getTaxableIncome(float $salary): float
    {
        // dedução de 10% do salário, limitada por um mínimo e um máximo
        $allowance = 0.1 * $salary;
        $allowance = min($allowance, $this->taxAdminData->tenPercentAllowanceMax);
        $allowance = max($allowance, $this->taxAdminData->tenPercentAllowanceMin);
        // renda tributável
        $taxableIncome = $salary - $allowance;
        // resultado
        return floor($taxableIncome);
    }

    // calcula um possível desconto
    private function getDiscount(string $married, float $salary, float $taxes): float
    {
        // no início, um desconto zero
        $discount = 0;
        // valor máximo do imposto para obter o desconto
        $taxCeilingForDiscount = $married === "yes"
            ? $this->taxAdminData->coupleTaxCeilingForDiscount
            : $this->taxAdminData->singleTaxCeilingForDiscount;
        if ($taxes < $taxCeilingForDiscount) {
            // valor máximo do desconto
            $discountCeiling = $married === "yes"
                ? $this->taxAdminData->coupleDiscountCeiling
                : $this->taxAdminData->singleDiscountCeiling;
            // desconto teórico
            $discount = $discountCeiling - 0.75 * $taxes;
            // o desconto não pode exceder o valor do imposto
            if ($discount > $taxes) {
                $discount = $taxes;
            }
            // nenhum desconto < 0
            if ($discount < 0) {
                $discount = 0;
            }
        }
        // resultado
        return ceil($discount);
    }

    // calcula uma possível redução
    private function getReduction(string $married, float $salary, int $children, float $taxes): float
    {
        // o teto de renda para ter direito à redução de 20%
        $incomeCeilingForReduction = $married === "yes"
            ? $this->taxAdminData->coupleIncomeCeilingForReduction
            : $this->taxAdminData->singleIncomeCeilingForReduction;
        $incomeCeilingForReduction += $children * $this->taxAdminData->halfShareReductionValue;
        if ($children > 2) {
            $incomeCeilingForReduction += ($children - 2) * $this->taxAdminData->halfShareReductionValue;
        }
        // renda tributável
        $taxableIncome = $this->getTaxableIncome($salary);
        // redução
        $reduction = 0;
        if ($taxableIncome < $incomeCeilingForReduction) {
            // redução de 20%
            $reduction = 0.2 * $taxes;
        }
        // resultado
        return ceil($reduction);
    }

Comentários

  • Linhas 80–83: a expressão [match] (PHP 8.0) é uma substituta melhor para o [if / else] da versão 2. Ela compara o valor [$married] com os valores de seus ramos usando o operador de igualdade [===] e retorna o valor do ramo correspondente. Se nenhum ramo corresponder, ela lança um erro [UnhandledMatchError]: um estado civil diferente de “yes” ou “no” não passará despercebido;
  • linhas 100–102: as tabelas de faixas de tributação são copiadas para variáveis locais. Em PHP, atribuir uma tabela cria uma cópia: a modificação de [$limits] na linha 104 não afeta o atributo [readonly] do objeto [TaxAdminData] (o que, aliás, seria um erro);
  • Linhas 122–123: as funções [min] e [max] substituem os dois [if] da versão 2: a dedução não pode exceder [tenPercentAllowanceMax] nem ser inferior a [tenPercentAllowanceMin];
  • o restante do código é o mesmo da versão 2, em que a expressão [$taxAdminData["COUPLE_DISCOUNT_CEILING"]] se tornou [$this->taxAdminData->coupleDiscountCeiling]. Um erro de digitação em um nome de atributo agora é sinalizado pelo editor [VS Code] (extensão [PHP Intelephense]) assim que o código é escrito, o que não acontecia com um erro de digitação em uma chave de array.

O método [executeBatchTaxes] é o seguinte:

    // cálculo do imposto em modo batch
    // --------------------------------------------------------------------------
    #[\Override]
    public function executeBatchTaxes(string $taxPayersFileName, string $resultsFileName, string $errorsFileName): void
    {
        // os três arquivos ainda não estão abertos
        $errors = $results = $data = false;
        // vários erros podem ocorrer assim que arquivos são manipulados
        try {
            // abertura do arquivo de erros
            $errors = fopen($errorsFileName, "w");
            if ($errors === false) {
                throw new TaxException("Unable to create the errors file [$errorsFileName]", 10);
            }
            // abertura do arquivo de resultados
            $results = fopen($resultsFileName, "w");
            if ($results === false) {
                throw new TaxException("Unable to create the results file [$resultsFileName]", 11);
            }
            // abertura do arquivo de dados dos contribuintes
            $data = is_readable($taxPayersFileName) ? fopen($taxPayersFileName, "r") : false;
            if ($data === false) {
                throw new TaxException("Unable to open the taxpayers' declarations [$taxPayersFileName] for reading", 12);
            }
            // 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
            $nbErrors = 0;    // número de erros encontrados
            while (($line = fgets($data, 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(",", $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) {
                    fputs($errors, "line [$num] of the file [$taxPayersFileName] is incorrect\n");
                    $nbErrors++;
                    continue;
                }
                // calculamos o imposto
                $result = $this->calculateTax($married, (int) $children, (int) $salary);
                // escrevemos o resultado no arquivo de resultados
                $result = ["married" => $married, "children" => (int) $children, "salary" => (int) $salary] + $result;
                fputs($results, json_encode($result, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR) . "\n");
            }
            // erros?
            if ($nbErrors > 0) {
                throw new TaxException("There were $nbErrors incorrect line(s): see the file [$errorsFileName]", 15);
            }
        } finally {
            // fechamos os arquivos que foram abertos
            foreach ([$data, $results, $errors] as $file) {
                if ($file !== false) {
                    fclose($file);
                }
            }
        }
    }

Comentários sobre o código

  • Linha 185: o método recebe três parâmetros:
    • [$taxPayersFileName]: o nome do arquivo de texto que contém os dados dos contribuintes. Cada linha de texto contém os dados de um contribuinte no seguinte formato: estado civil (yes/no), número de filhos, salário anual; por exemplo, [yes,2,55555];
    • [$resultsFileName]: o nome do arquivo de texto que conterá os resultados. Cada linha de texto será a string JSON que representa os resultados de um contribuinte, por exemplo, [{"married":"yes","children":2,"salary":50000,"tax":1384,"surcharge":0,"discount":384,"reduction":347,"rate":0.14}];
    • [$errorsFileName]: o nome do arquivo de texto que contém os erros, por exemplo, [line [5] of the file [taxpayersdata.txt] is incorrect];
  • linha 188: as variáveis dos três arquivos são inicializadas com [false] (arquivo não aberto). Isso permitirá determinar, na cláusula [finally], quais arquivos foram abertos;
  • linha 190: como várias operações podem lançar uma exceção, uma estrutura [try / finally] envolve todo o código do método;
  • linhas 192–204: os três arquivos são abertos. Uma exceção é lançada assim que uma operação de abertura falha, com um código de erro diferente para cada caso;
  • Linha 210: as linhas do arquivo [$data] são lidas uma a uma em blocos de até 100 caracteres (todas as linhas têm menos de 100 caracteres);
  • Linha 214: o método estático [Utilities::cutNewLineChar] é usado para remover eventuais caracteres de fim de linha;
  • Linhas 216–218: as linhas vazias (por exemplo, no final do arquivo) são ignoradas;
  • linha 220: a linha é dividida na vírgula, e os espaços em torno de cada campo são removidos. [trim(...)] é a sintaxe das “first-class callables” (PHP 8.1): ela se refere à própria função [trim], sem chamá-la;
  • linha 221: a linha deve ter exatamente três campos. O curso de PHP 7 escrevia diretamente [list($married, $children, $salary) = explode(",", $line)]: com uma linha que tenha apenas dois campos, o PHP 8 emite o aviso “Undefined array key 2”;
  • Linhas 227–229: verifica-se a validade dos três elementos: o estado civil deve ser “yes” ou “no”, e o número de filhos e o salário devem ser inteiros positivos ou nulos (uma sequência de dígitos, expressão regular [/^\d+$/]). O terceiro parâmetro [true] de [in_array] exige uma comparação estrita [===];
  • linhas 232–236: nenhuma exceção é lançada se a linha for inválida; em vez disso, uma mensagem de erro é escrita no arquivo de texto [$errors], e o programa passa para a linha seguinte;
  • linha 238: se a linha lida for válida, o imposto é calculado. O resultado é retornado como um array associativo [tax, surcharge, discount, reduction, rate];
  • linha 240: as chaves [married, children, salary] são adicionadas ao início do resultado;
  • linha 241: o resultado é escrito no arquivo de texto [$results] na forma de sua string JSON. A opção [JSON_THROW_ON_ERROR] faz a função [json_encode] lançar uma exceção [JsonException] em vez de retornar [false] se a codificação falhar;
  • linhas 244–246: ao final do processamento do arquivo [$data], verifica-se o número de linhas errôneas encontradas. Se houver pelo menos uma, uma exceção é lançada;
  • linhas 247–254: independentemente de como a execução do método termina (normalmente ou por uma exceção), a cláusula [finally] é executada: os arquivos que foram abertos são fechados. O curso de PHP 7 usava uma estrutura [try / catch / finally] cuja cláusula [catch] simplesmente relançava a exceção. Isso é desnecessário: uma estrutura [try / finally] sem [catch] permite que a exceção se propague depois que a cláusula [finally] for executada. Além disso, o curso de PHP 7 fechava os três arquivos sem verificar se haviam sido abertos: no PHP 8, [fclose(false)] causa um erro [TypeError].

8.7. A classe [TaxWithTaxAdminDataInJsonFile]

A classe abstrata [AbstractBaseTax] não implementa o método [getTaxAdminData] da interface [InterfaceTax]. Precisamos, portanto, defini-lo em uma classe derivada. Fazemos isso na seguinte classe derivada, [TaxWithTaxAdminDataInJsonFile]:

<?php

declare(strict_types=1);

// namespace
namespace Application;

// uma classe que obtém os dados da administração tributária de um arquivo JSON
class TaxWithTaxAdminDataInJsonFile extends AbstractBaseTax
{
    // os dados da administração tributária
    private readonly TaxAdminData $taxAdminData;

    // o construtor
    public function __construct(string $jsonFileName)
    {
        // inicializamos $this->taxAdminData a partir do arquivo JSON
        // pode lançar uma exceção TaxException
        $this->taxAdminData = TaxAdminData::fromJsonFile($jsonFileName);
    }

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

Comentários

  • Linha 9: a classe [TaxWithTaxAdminDataInJsonFile] estende a classe abstrata [AbstractBaseTax]. Ela deve definir o método [getTaxAdminData], que sua classe pai não definiu;
  • Linha 12: o atributo [$taxAdminData] conterá os dados da administração tributária. Ele é somente leitura: é inicializado de uma vez por todas pelo construtor. Observe que a classe pai também tem um atributo privado [$taxAdminData]: os dois atributos são distintos, pois um atributo privado só é visível dentro da classe que o declara;
  • linhas 15–20: o construtor recebe como único parâmetro o nome do arquivo JSON que contém os dados tributários;
  • linha 19: um objeto do tipo [TaxAdminData] é criado a partir do arquivo JSON. Essa operação pode lançar uma exceção do tipo [TaxException]. Essa exceção se propagará até o script principal [main.php];
  • Linhas 23–27: é fornecido um corpo para o método [getTaxAdminData], que a classe pai não havia definido. Aqui, basta garantir que o atributo [$this->taxAdminData] seja inicializado pelo construtor.

8.8. O script [main.php]

Essas classes e interfaces são usadas pelo seguinte script, [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__ . "/TaxAdminData.php";
require_once __DIR__ . "/Utilities.php";
require_once __DIR__ . "/InterfaceTax.php";
require_once __DIR__ . "/AbstractBaseTax.php";
require_once __DIR__ . "/TaxWithTaxAdminDataInJsonFile.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 {
    // criamos um objeto [TaxWithTaxAdminDataInJsonFile]
    $tax = new TaxWithTaxAdminDataInJsonFile(TAXADMINDATA_FILENAME);
    // executamos o batch de cálculo do imposto
    $tax->executeBatchTaxes(TAXPAYERSDATA_FILENAME, RESULTS_FILENAME, ERRORS_FILENAME);
} catch (TaxException $ex) {
    // exibimos o erro
    print "Error no. {$ex->getCode()}: {$ex->getMessage()}\n";
}
// fim
print "Done\n";

Comentários

  • linha 4: exige-se a adesão estrita aos tipos dos parâmetros das funções;
  • Linha 7: o script [main.php] também está no namespace [Application];
  • Linhas 10–15: os arquivos de classes e interfaces usados pelo script são carregados. Observe que aqui não usamos uma instrução [use] para declarar os nomes completos das classes usadas pelo script. Isso é desnecessário porque o script e as classes estão no mesmo namespace, [Application]. Observe também a ordem de carregamento: uma classe pai ou uma interface deve ser carregada antes da classe que deriva dela ou a implementa;
  • linhas 18–21: os nomes dos arquivos usados no script. Esses nomes são relativos: os arquivos são procurados no diretório atual, aquele a partir do qual o script é executado;
  • linha 25: um objeto [TaxWithTaxAdminDataInJsonFile] é criado. Isso pode lançar uma exceção se o arquivo JSON estiver ausente ou incorreto;
  • linha 27: o método [executeBatchTaxes] é chamado, o qual calculará os impostos de todos os contribuintes do arquivo [TAXPAYERSDATA_FILENAME]. Os resultados serão escritos no arquivo [RESULTS_FILENAME], e os eventuais erros serão escritos no arquivo [ERRORS_FILENAME];
  • Linhas 28–31: se ocorrer um erro, o código e a mensagem de erro são exibidos. A expressão [{$ex->getCode()}] permite inserir o resultado de uma chamada de método em uma string.

8.9. Resultados

Execute o script em um terminal aberto na pasta [version-03]:

1
2
3
> php main.php
Error no. 15: There were 2 incorrect line(s): see the file [errors.txt]
Done

Com o arquivo de contribuintes [taxpayersdata.txt] mostrado acima, é 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}

Os impostos calculados para as onze linhas corretas (2814, 1384, 0, 19884, 16782, 9200, 4230, 22986, 0, 64210, 42842) são os das versões 1 e 2.

8.10. Conclusão

A versão 3 tem a mesma funcionalidade da versão 2, mas está mais bem equipada para tratar erros: dados tributários incompletos ou incorretos, linhas errôneas no arquivo de contribuintes ou arquivos ausentes. Cada erro é sinalizado por uma exceção [TaxException] que inclui uma mensagem e um código específico.

No entanto, a classe [AbstractBaseTax] combina dois tipos de código: o cálculo de impostos, de um lado, e a leitura e escrita de arquivos, de outro. Nos próximos capítulos, veremos como separar essas duas responsabilidades em camadas diferentes.