Skip to content

8. Praktische Übung – Version 3

Wir greifen die zuvor behandelte Übung (Versionen 1 und 2) wieder auf und lösen sie mit PHP-Code, der Klassen verwendet. Dabei wenden wir an, was wir in den vorherigen drei Kapiteln gelernt haben:

  • eine (unveränderliche) Klasse [readonly] zur Darstellung der Daten der Steuerverwaltung;
  • eine Schnittstelle, eine abstrakte Klasse, die sie teilweise implementiert, und eine abgeleitete Klasse, die sie vervollständigt;
  • ein einziger Ausnahmetyp, [TaxException], um alle Anwendungsfehler zu melden;
  • das Attribut [#[\Override]] bei allen Methoden, die eine Schnittstellenmethode implementieren oder eine Methode der Elternklasse überschreiben.

8.1. Die Verzeichnisstruktur der Skripte

Version 3 befindet sich im Ordner [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

Jede Klasse und jede Schnittstelle befindet sich in einer Datei, die ihren Namen trägt. Diese Konvention wird in PHP allgemein befolgt (sie ist sogar durch den Standard PSR-4 für das automatische Laden vorgeschrieben, dem wir bei [Composer] begegnen werden).

8.2. Die Ausnahme [TaxException]

In Version 3 löst ein Klassenkonstruktor oder eine Methode, die auf einen Fehler stößt, eine Ausnahme [TaxException] aus:

<?php

declare(strict_types=1);

// Namespace
namespace Application;

// die Exception, die von den Klassen der Anwendung zur Steuerberechnung geworfen wird
class TaxException extends \RuntimeException
{
    // kein Code: der von [\RuntimeException] geerbte Konstruktor genügt
    // __construct(string $message = "", int $code = 0, ?\Throwable $previous = null)
}

Kommentare

  • Zeile 6: Die Klasse [TaxException] befindet sich im Namespace [Application]. Alle Klassen und Schnittstellen der Steuerberechnungsanwendung liegen in diesem Namespace;
  • Zeile 9: Die Klasse [TaxException] erweitert die vordefinierte PHP-Klasse [RuntimeException]. Wie wir im Kapitel über Ausnahmen gesehen haben, wird eine Ausnahme in erster Linie durch ihren Typ definiert: Der Typ ermöglicht es, sie mit einer Klausel [catch (TaxException $ex)] abzufangen;
  • Zeilen 11–12: Im PHP-7-Kurs wurde ein Konstruktor [__construct(string $message, int $code = 0)] definiert, der lediglich den Konstruktor der Elternklasse aufrief. Das ist unnötig: Die Klasse erbt den Konstruktor von [RuntimeException], der eine Meldung, einen Fehlercode und eine eventuelle vorherige Ausnahme akzeptiert. Diesen letzten Parameter verwenden wir, um eine Low-Level-Ausnahme (zum Beispiel eine [JsonException], ) in einer [TaxException] zu kapseln.

8.3. Die Klasse [TaxAdminData]

In Version 2 wurden die Daten der Steuerverwaltung zusammengeführt:

  • zunächst in einer JSON-Datei;
  • dann aus dieser JSON-Datei in ein assoziatives Array.

Wir hatten einen Mangel dieser Lösung festgestellt: Es gibt keine Garantie, dass das assoziative Array alle erwarteten Schlüssel enthält oder dass die zugehörigen Werte Zahlen sind. In Version 3 liegen die Daten der Steuerbehörde weiterhin in der Datei [taxadmindata.json] vor, jedoch mit anderen Attributnamen, die nach der camelCase-Konvention für Attributnamen von Klassen geschrieben sind:

{
    "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
}

In Version 2 wurde diese Datei verwendet, um ein assoziatives Array zu initialisieren. In Version 3 initialisiert sie ein Objekt der folgenden Klasse: [TaxAdminData]:

<?php

declare(strict_types=1);

// Namespace
namespace Application;

// die Daten der Steuerverwaltung: ein unveränderliches Objekt
final readonly class TaxAdminData
{
    // die Namen der in den Daten erwarteten Arrays und Konstanten
    private const array ARRAYS = ["limits", "coeffR", "coeffN"];
    private const array CONSTANTS = [
        "halfShareQfCeiling",
        "singleIncomeCeilingForReduction",
        "coupleIncomeCeilingForReduction",
        "halfShareReductionValue",
        "singleDiscountCeiling",
        "coupleDiscountCeiling",
        "coupleTaxCeilingForDiscount",
        "singleTaxCeilingForDiscount",
        "tenPercentAllowanceMax",
        "tenPercentAllowanceMin",
    ];

    // privater Konstruktor: man muss über die [from...]-Methoden gehen
    private function __construct(
        // Steuerstufen
        public array $limits,
        public array $coeffR,
        public array $coeffN,
        // Konstanten der Steuerberechnung
        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,
    ) {
    }

    // Erzeugung aus einer JSON-Datei
    public static function fromJsonFile(string $taxAdminDataFilename): self
    {
        // wir rufen den Inhalt der Steuerdatendatei ab
        $fileContents = is_readable($taxAdminDataFilename) ? file_get_contents($taxAdminDataFilename) : false;
        // Fehler?
        if ($fileContents === false) {
            throw new TaxException("The data file [$taxAdminDataFilename] does not exist", 1);
        }
        // wir dekodieren das JSON in ein assoziatives Array
        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);
        }
        // das JSON muss ein Objekt {...} sein
        if (!is_array($data)) {
            throw new TaxException("The JSON data file [$taxAdminDataFilename] does not contain a JSON object", 3);
        }
        // Aufbau des Objekts aus dem assoziativen Array
        return self::fromArray($data);
    }

    // Erzeugung aus einem assoziativen Array [name => value]
    public static function fromArray(array $data): self
    {
        // die vorhandenen Schlüssel müssen genau die erwarteten sein
        $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);
        }
        // wir prüfen und konvertieren jeden Wert
        $values = [];
        foreach (self::ARRAYS as $key) {
            // ein nicht leeres Array von reellen Zahlen >= 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]);
        }
        // die drei Arrays müssen dieselbe Größe haben
        $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) {
            // eine reelle Zahl >= 0
            $values[$key] = self::check($key, $data[$key]);
        }
        // Aufbau des Objekts: die Schlüssel des Arrays werden zu benannten Argumenten
        return new self(...$values);
    }

    // prüft, ob ein Wert eine positive oder null reelle Zahl ist, und gibt ihn als [float] zurück
    private static function check(string $key, mixed $value): float
    {
        // wir akzeptieren 1551, 1551.78, "1551", aber nicht "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);
    }

    // JSON-String des Objekts
    public function __toString(): string
    {
        return json_encode(get_object_vars($this), JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
    }
}

Kommentare

  • Zeile 9: Die Klasse ist [readonly]: Alle ihre Attribute sind schreibgeschützt. Einmal erzeugt, kann ein Objekt [TaxAdminData] nicht mehr verändert werden: Es kann gefahrlos von allen Teilen der Anwendung gemeinsam genutzt werden. Sie ist außerdem [final]: Von ihr kann nicht abgeleitet werden;
  • Zeilen 12–24: Zwei private Klassenkonstanten listen die Namen der in den Daten erwarteten Attribute auf. Ab PHP 8.3 kann eine Klassenkonstante typisiert sein (hier [array]);
  • Zeilen 27–43: Der Konstruktor verwendet Parameter-Promotion: Jeder Parameter wird zu einem öffentlichen Attribut mit demselben Namen und Typ. Die Attribute haben dieselben Namen wie die Schlüssel in der JSON-Datei. Das ist ein wichtiger Punkt, der das Schreiben des Codes erheblich vereinfacht, wie wir sehen werden. Die Steuerstufen sind Arrays ([array]), die Berechnungskonstanten reelle Zahlen ([float]). In PHP 7 konnten Attribute nicht typisiert werden (wie im PHP-7-Kurs angemerkt); ab PHP 7.4 können sie es;
  • Zeile 27: Der Konstruktor ist private; [new TaxAdminData(...)] kann außerhalb der Klasse nicht geschrieben werden. Ein Objekt [TaxAdminData] lässt sich nur über die statischen Methoden [fromJsonFile] und [fromArray] erhalten, die die Gültigkeit der Daten prüfen. So ist sichergestellt, dass jedes Objekt [TaxAdminData] gültige Daten enthält. In PHP kann eine Klasse nur einen Konstruktor haben. Statische Methoden, die ein Objekt konstruieren – manchmal „benannte Konstruktoren“ genannt –, ermöglichen mehrere Arten, ein Objekt zu konstruieren. Der PHP-7-Kurs verwendete Instanzmethoden [setFromJsonFile] , die auf einem leeren Objekt aufgerufen wurden: [(new TaxAdminData())->setFromJsonFile(...)]. Bei einem unveränderlichen Objekt ist das unmöglich;
  • Zeilen 47–67: Die Methode [fromJsonFile] konstruiert ein Objekt [TaxAdminData] aus der JSON-Datei, deren Name ihr übergeben wird. Ihr Rückgabetyp [self], bezeichnet die Klasse selbst;
  • Zeilen 50–53: Der Inhalt der Datei wird gelesen. Ist das nicht möglich, wird eine Ausnahme [TaxException] ausgelöst. Diese Ausnahme wird bis zum Hauptskript weitergereicht;
  • Zeilen 56–60: Der Inhalt der Datei, JSON, wird dekodiert. Mit der Option [JSON_THROW_ON_ERROR] (PHP 7.3) löst die Funktion [json_decode] bei ungültigem JSON eine Ausnahme [JsonException] aus, anstatt stillschweigend [null] zurückzugeben. Beachten Sie das benannte Argument [flags:], mit dem man vermeidet, dem dritten Parameter [depth] von [json_decode] einen Wert zuweisen zu müssen. Die Ausnahme [JsonException] wird in einer [TaxException] gekapselt: Der aufrufende Code muss nur einen Ausnahmetyp behandeln, kann aber die ursprüngliche Ursache mit [$ex->getPrevious()] ermitteln;
  • Zeilen 62–64: Eine Datei, die zum Beispiel nur die Zahl 12 enthält, ist gültiges JSON; man muss prüfen, dass tatsächlich ein Array erhalten wurde;
  • Zeile 66: Die restliche Arbeit wird an die Methode [fromArray] delegiert. Diese Methode ist öffentlich: Sie kann in einer künftigen Version verwendet werden, in der die Daten der Steuerverwaltung aus einer Datenbank stammen;
  • Zeilen 73–81: Wir prüfen, dass die Schlüssel des Arrays [$data] genau den erwarteten Namen entsprechen. [[...self::ARRAYS, ...self::CONSTANTS]] erzeugt ein Array, das die Elemente beider Arrays enthält. Die Funktion [array_diff] liefert die Elemente des ersten Arrays, die im zweiten fehlen, und die Funktion [array_first] (PHP 8.5) liefert das erste Element eines Arrays oder [null] , wenn das Array leer ist. So wird erst ein fehlender, dann ein unbekannter Schlüssel erkannt. Das ist der häufigste Fehler: ein Tippfehler in einem Attributnamen in der Datei [taxadmindata.json]. Im PHP-7-Kurs erzeugte die Schleife [$this->$key = $value] stillschweigend ein dynamisches Attribut mit dem falschen Namen. Seit PHP 8.2 ist das Erzeugen dynamischer Attribute veraltet, und in einer Klasse [readonly] ist es verboten;
  • Zeilen 84–90: Jedes der drei Arrays muss eine nicht leere Liste sein (Funktion [array_is_list], PHP 8.1), deren Elemente alle positive reelle Zahlen oder null sind. Die Funktion [array_map] wendet die Methode [check] auf jedes Element an;
  • Zeilen 92–95: Die drei Arrays der Steuerstufen müssen gleich groß sein;
  • Zeilen 96–99: Jede der Berechnungskonstanten muss eine positive reelle Zahl oder null sein;
  • Zeile 101: Das Array [$values] verwendet die Namen der Konstruktorparameter als Schlüssel. Der Operator [...], auf ein Array mit String-Schlüsseln angewendet, wandelt jedes Element in ein benanntes Argument um (PHP 8.1): Diese Zeile entspricht [new self(limits: $values["limits"], coeffR: $values["coeffR"], ...)]. Hier vereinfacht die Wahl identischer Namen für die JSON-Schlüssel und die Klassenattribute den Code;
  • Zeilen 105–113: Die Methode [check] prüft, ob ein Wert [$value] unbekannten Typs ([mixed]) eine positive Zahl oder null ist. Je nach Inhalt der JSON-Datei kann der gelesene Wert eine ganze Zahl (1551), eine Gleitkommazahl (1551.78), eine in eine Zahl umwandelbare Zeichenkette ("1551"), eine nicht umwandelbare Zeichenkette ("xx"), ein Boolescher Wert ... sein. Die Funktion [is_numeric] liefert [true] für eine Zeichenkette, die eine Zahl darstellt. Der PHP-7-Kurs führte diese Prüfung mit einem regulären Ausdruck durch und gab ein Objekt [stdClass] zurück, das anzeigte, ob ein Fehler aufgetreten war. Hier löst ein Fehler eine Ausnahme aus, und die Methode gibt einfach die Zahl als [float] zurück;
  • Zeile 116: Die Methode [__toString] liefert die JSON-Zeichenkette mit den Attributen des Objekts. Die Funktion [get_object_vars] liefert ein assoziatives Array [Attributname => Wert].

8.3.1. Warum gibt es keine Getter und Setter mehr?

Der PHP-7-Kurs deklarierte die Attribute als privat und schrieb für jedes einen Getter und einen Setter (26 Methoden), die von der IDE NetBeans automatisch erzeugt wurden. Die Setter waren „fluent“: Sie gaben das Objekt [$this] zurück, was verkettete Aufrufe wie [$data->setLimits($limits)->setCoeffR($coeffR)] ermöglichte.

Mit PHP 8 ist dieser Code nicht mehr nötig:

  • Die Getter dienten dazu, private Attribute zu lesen. Die Attribute [readonly] können gefahrlos öffentlich gemacht werden, da sie nicht verändert werden können: Wir schreiben [$taxAdminData->halfShareQfCeiling] statt [$taxAdminData->getHalfShareQfCeiling()];
  • Die Setter dienten dazu, das Objekt zu initialisieren, und erlaubten die Validierung von Werten. Ein unveränderliches Objekt wird einmalig durch seinen Konstruktor initialisiert, und die Validierung übernehmen die Methoden [fromJsonFile] und [fromArray];
  • Typisierte Attribute garantieren den Typ der Werte. Der PHP-7-Kurs hatte festgestellt, dass die Anweisung [$this->halfShareQfCeiling = 'abcd'] möglich war: Mit Attributen vom Typ [float] und [declare(strict_types=1)] führt sie zu einem Fehler [TypeError].

Das Skript [test-taxadmindata.php] prüft die Funktionalität der Klasse [TaxAdminData]:

<?php

// strikte Einhaltung der deklarierten Typen der Funktionsparameter und -ergebnisse
declare(strict_types=1);

// Namespace
namespace Application;

// Einbindung der Klassen
require_once __DIR__ . "/TaxException.php";
require_once __DIR__ . "/TaxAdminData.php";

// ein gültiges Objekt
$taxAdminData = TaxAdminData::fromJsonFile("taxadmindata.json");
print "$taxAdminData\n";
print "halfShareQfCeiling=" . $taxAdminData->halfShareQfCeiling . "\n";
// das Objekt ist unveränderlich
try {
    $taxAdminData->halfShareQfCeiling = 2000;
} catch (\Error $ex) {
    print $ex::class . ": " . $ex->getMessage() . "\n";
}
// der Konstruktor ist privat
try {
    $taxAdminData = new TaxAdminData([], [], []);
} catch (\Error $ex) {
    print $ex::class . ": " . $ex->getMessage() . "\n";
}

// fehlerhafte Daten
$valid = json_decode(file_get_contents("taxadmindata.json"), true, flags: JSON_THROW_ON_ERROR);
$tests = [
    // nicht existierende Datei
    fn() => TaxAdminData::fromJsonFile("xx.json"),
    // Datei, die kein JSON ist
    fn() => TaxAdminData::fromJsonFile("taxpayersdata.txt"),
    // fehlender Schlüssel
    fn() => TaxAdminData::fromArray(array_diff_key($valid, ["halfShareQfCeiling" => 0])),
    // unbekannter Schlüssel (Tippfehler)
    fn() => TaxAdminData::fromArray(["halfShareQFCeiling" => 1551] + $valid),
    // nicht numerischer Wert
    fn() => TaxAdminData::fromArray(["halfShareQfCeiling" => "xx"] + $valid),
    // negativer Wert in einem Array
    fn() => TaxAdminData::fromArray(["coeffR" => [0, 0.14, -0.3, 0.41, 0.45]] + $valid),
    // Arrays unterschiedlicher Größe
    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";
    }
}
// ein Wert "1551" wird akzeptiert und in eine reelle Zahl umgewandelt
$taxAdminData = TaxAdminData::fromArray(["halfShareQfCeiling" => "1551"] + $valid);
var_dump($taxAdminData->halfShareQfCeiling);

Kommentare

  • Zeile 14: Konstruktion eines gültigen Objekts [TaxAdminData] aus der Datei [taxadmindata.json];
  • Zeile 15: Das Objekt wird in eine Zeichenkette eingefügt: Seine Methode [__toString] wird aufgerufen;
  • Zeile 19: Versuch, ein schreibgeschütztes Attribut zu ändern;
  • Zeile 25: Versuch, den privaten Konstruktor zu verwenden;
  • Zeile 31: das assoziative Array mit den gültigen Daten;
  • Zeilen 32–47: ein Array von Pfeilfunktionen, von denen jede ein Objekt [TaxAdminData] aus ungültigen Daten konstruiert. Die ungültigen Daten entstehen durch Änderung einer Kopie des Arrays [$valid]. Wendet man den Operator [+] auf zwei Arrays an, haben bei gemeinsamem Schlüssel die Elemente des linken Arrays Vorrang. Die Funktion [array_diff_key] entfernt aus dem ersten Array die Schlüssel, die im zweiten vorhanden sind;
  • Zeilen 48–54: Jede Funktion wird ausgeführt, und die erwartete Ausnahme wird angezeigt;
  • Zeile 56: Eine numerische Zeichenkette wird akzeptiert und in eine reelle Zahl umgewandelt.

Ergebnisse:

> 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)
  • Zeile 2: die JSON-Zeichenkette des Objekts. Beachten Sie, dass reelle Zahlen ohne Nachkommaanteil (1551.0) von der Funktion [json_encode] ohne diesen geschrieben werden (1551);
  • Zeilen 4–5: Die beiden Fehler [Error], die durch die Änderung eines Attributs [readonly] und durch den Aufruf eines privaten Konstruktors verursacht wurden. Das sind Programmierfehler, keine Datenfehler: Sie werden nicht in [TaxException] umgewandelt;
  • Zeilen 6–12: Alle fehlerhaften Daten werden erkannt, jeweils mit einer anderen Meldung und einem anderen Fehlercode;
  • Zeile 13: Die Zeichenkette "1551" wurde in eine Gleitkommazahl umgewandelt.

8.4. Die Schnittstelle [InterfaceTax]

Wir definieren nun die folgende Schnittstelle [InterfaceTax]: [InterfaceTax.php]:

<?php

declare(strict_types=1);

// Namespace
namespace Application;

interface InterfaceTax
{
    // ruft die Daten der Steuerverwaltung ab, die zur Steuerberechnung dienen
    // kann die Exception TaxException werfen
    public function getTaxAdminData(): TaxAdminData;

    // die Schnittstelle kann eine Steuer berechnen
    public function calculateTax(string $married, int $children, int $salary): array;

    // die Schnittstelle kann Daten in Textdateien verarbeiten
    // $taxPayersFileName: Datei mit den Steuerpflichtigendaten in der Form Familienstand, Anzahl der Kinder, Jahresgehalt
    // $resultsFileName: Ergebnisdatei in der Form Familienstand, Anzahl der Kinder, Jahresgehalt, Steuerbetrag...
    // $errorsFileName: Datei der aufgetretenen Fehler
    // kann die Exception TaxException werfen
    public function executeBatchTaxes(string $taxPayersFileName, string $resultsFileName, string $errorsFileName): void;
}

Kommentare

  • Zeile 8: die Schnittstelle zur Steuerberechnung. Sie befindet sich ebenfalls im Namespace [Application];
  • Zeile 12: Die Methode [getTaxAdminData] ruft die Daten der Steuerbehörde in ein Objekt vom Typ [TaxAdminData] ab, das wir soeben eingeführt haben. Da diese Daten in einer Datei, einer Datenbank oder sogar im Netzwerk gespeichert sein können, kann die Methode [getTaxAdminData] beim Abrufen der Daten scheitern. In diesem Fall löst sie eine Ausnahme vom Typ [TaxException] aus. Das ist das Standardverfahren der objektorientierten Programmierung, um einen Fehler zu melden, der in einer Methode oder einem Konstruktor aufgetreten ist;
  • Zeile 15: Die Methode [calculateTax] berechnet die Steuer eines Steuerpflichtigen;
  • Zeile 22: Die Methode [executeBatchTaxes] berechnet die Steuer für mehrere Steuerpflichtige;
    • [$taxPayersFileName] ist der Name der Textdatei mit den Daten der Steuerpflichtigen;
    • [$resultsFileName] ist der Name der Textdatei mit den Steuerbeträgen dieser Steuerpflichtigen;
    • [$errorsFileName] ist der Name der Textdatei mit den Fehlern, die bei der Verarbeitung dieser Dateien aufgetreten sind.

Der Inhalt der Textdatei der Steuerpflichtigen [taxpayersdata.txt] lautet wie folgt:

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

Beachten Sie, dass die Zeilen 5 und 8 fehlerhafte Einträge enthalten. Die anderen elf Zeilen entsprechen den elf Steuerpflichtigen aus der Tabelle der offiziellen Zahlen.

8.5. Die Klasse [Utilities]

Wir definieren außerdem eine Klasse namens [Utilities] in einer Datei namens [Utilities.php]:

<?php

declare(strict_types=1);

// Namespace
namespace Application;

// eine Klasse mit Hilfsfunktionen: sie kann weder instanziiert noch abgeleitet werden
final class Utilities
{
    // privater Konstruktor: die Klasse kann nicht instanziiert werden
    private function __construct()
    {
    }

    public static function cutNewLineChar(string $line): string
    {
        // wir entfernen das Zeilenende-Zeichen von $line, falls vorhanden
        // (\r\n unter Windows, \n unter Unix)
        return rtrim($line, "\r\n");
    }
}

Kommentare

  • Zeile 9: Die Klasse [Utilities] befindet sich ebenfalls im Namespace [Application]. Sie enthält nur statische Methoden: Es gibt keinen Grund, sie zu instanziieren oder von ihr abzuleiten. Der PHP-7-Kurs deklarierte sie als abstrakt, um ihre Instanziierung zu verhindern, und bedauerte, dass PHP es ablehnte, sie sowohl als [final] als auch als [abstract] zu deklarieren. Daran hat sich nichts geändert. Üblich ist heute, sie als [final] (nicht ableitbar) zu deklarieren und ihr einen privaten Konstruktor zu geben (der von außen nicht aufgerufen und damit nicht instanziiert werden kann);
  • Zeile 16: Die Methode [cutNewLineChar] entfernt alle Zeilenendzeichen aus dem als Parameter übergebenen Text. Es ist eine statische Methode, sie wird also in der Form [Utilities::cutNewLineChar($line)] aufgerufen. Ihr Code ist derselbe wie der der gleichnamigen Funktion in Version 2.

8.6. Die abstrakte Klasse [AbstractBaseTax]

Die Schnittstelle [InterfaceTax] wird von der folgenden abstrakten Klasse [AbstractBaseTax] [AbstractBaseTax.php] implementiert:

<?php

declare(strict_types=1);

// Namespace
namespace Application;

// eine abstrakte Klasse, die die Schnittstelle [InterfaceTax] implementiert
abstract class AbstractBaseTax implements InterfaceTax
{
    // die Daten der Steuerverwaltung
    private ?TaxAdminData $taxAdminData = null;

    // zur Steuerberechnung benötigte Daten: die abgeleiteten Klassen wissen, wo sie zu finden sind
    #[\Override]
    abstract public function getTaxAdminData(): TaxAdminData;

    // Steuerberechnung
    // --------------------------------------------------------------------------
    #[\Override]
    public function calculateTax(string $married, int $children, int $salary): array
    {
        // $married: ja, nein
        // $children: Anzahl der Kinder
        // $salary: Jahresgehalt
        // $this->taxAdminData: Daten der Steuerverwaltung
        //
        // wir rufen die Daten der Steuerverwaltung ab, falls dies noch nicht geschehen ist
        $this->taxAdminData ??= $this->getTaxAdminData();
        // Berechnung der Steuer mit Kindern
        $result1 = $this->calculateTax2($married, $children, $salary);
        $tax1 = $result1["tax"];
        // Berechnung der Steuer ohne die Kinder
        if ($children !== 0) {
            $result2 = $this->calculateTax2($married, 0, $salary);
            $tax2 = $result2["tax"];
            // Anwendung der Obergrenze des Familienquotienten
            $halfShareCeiling = $this->taxAdminData->halfShareQfCeiling;
            if ($children < 3) {
                // halfShareQfCeiling Euro für die ersten 2 Kinder
                $tax2 = $tax2 - $children * $halfShareCeiling;
            } else {
                // halfShareQfCeiling Euro für die ersten 2 Kinder, doppelt für die weiteren
                $tax2 = $tax2 - 2 * $halfShareCeiling - ($children - 2) * 2 * $halfShareCeiling;
            }
        } else {
            $tax2 = $tax1;
            $result2 = $result1;
        }
        // wir nehmen die höhere Steuer mit dem dazugehörigen Satz und Zuschlag
        if ($tax1 > $tax2) {
            $tax = $tax1;
            $rate = $result1["rate"];
            $surcharge = $result1["surcharge"];
        } else {
            $surcharge = $tax2 - $tax1 + $result2["surcharge"];
            $tax = $tax2;
            $rate = $result2["rate"];
        }
        // Berechnung einer eventuellen Ermäßigung
        $discount = $this->getDiscount($married, $salary, $tax);
        $tax -= $discount;
        // Berechnung einer eventuellen Steuerminderung
        $reduction = $this->getReduction($married, $salary, $children, $tax);
        $tax -= $reduction;
        // Ergebnis
        return [
            "tax" => (int) floor($tax),
            "surcharge" => (int) $surcharge,
            "discount" => (int) $discount,
            "reduction" => (int) $reduction,
            "rate" => $rate,
        ];
    }

Kommentare

  • Zeile 9: Die Klasse [AbstractBaseTax] implementiert die Schnittstelle [InterfaceTax];
  • Zeile 12: Die Daten der Steuerbehörde werden im privaten Attribut [$taxAdminData] gespeichert. Sein Typ [?TaxAdminData], bedeutet „ein Objekt [TaxAdminData] oder der Wert [null]“. Sein Anfangswert ist [null];
  • Zeile 16: die Methode [getTaxAdminData] der Schnittstelle. Wir wissen noch nicht, wie sie zu definieren ist: Wir haben einen Fall gesehen, in dem die Daten der Steuerbehörde aus einer JSON-Datei abgerufen wurden (Version 2). Wir werden einen weiteren Fall sehen, in dem die Daten aus einer Datenbank abgerufen werden. Es ist Aufgabe der abgeleiteten Klassen, den Inhalt der Methode [getTaxAdminData] zu definieren. Die Methode wird daher als abstrakt deklariert, was verlangt, dass die Klasse selbst als abstrakt deklariert wird. Diese Deklaration ist optional: Eine abstrakte Klasse, die eine Schnittstelle implementiert, muss die Methoden, die sie nicht implementiert, nicht erneut deklarieren. Sie macht den Code jedoch lesbarer. Das Attribut [#[\Override]] (PHP 8.3) zeigt an, dass die Methode zu einer Schnittstelle oder einer Elternklasse gehört: Ist der Name falsch, meldet PHP den Fehler;
  • Zeilen 21–73: Die Steuerberechnungsfunktion, der wir bereits in den Versionen 1 und 2 begegnet sind. Ihre Parameter haben sich geändert: Version 2 nahm das assoziative Array [$taxAdminData] als ersten Parameter entgegen, während Version 3 das Attribut [$this->taxAdminData] verwendet. Der erste Unterschied zwischen diesen beiden Lösungen betrifft die Sichtbarkeit der Steuerdaten:
    • In Version 2 hatte das assoziative Array [$taxAdminData] keine globale Sichtbarkeit. Es wurde daher als Parameter an alle Steuerberechnungsfunktionen übergeben;
    • In Version 3 ist das Attribut [$this->taxAdminData] in allen Methoden der Klasse sichtbar. Es wird daher nicht mehr als Parameter übergeben;
  • Ein zweiter Unterschied ergibt sich daraus, dass Version 3 Funktionen durch Klassenmethoden ersetzt. Jeder Methodenaufruf erfolgt nun mit dem Ausdruck [$this->method(...)] (Zeile 31, Zeile 61);
  • Zeile 29: Ein dritter Unterschied besteht darin, dass die Methode [calculateTax] zu Beginn ihrer Arbeit nicht weiß, ob das benötigte Attribut [$taxAdminData] initialisiert wurde. Tatsächlich hat die Klasse keinen Konstruktor, der es initialisieren würde. Es ist daher Sache der Methode [calculateTax], dies mit der Methode [getTaxAdminData] zu tun. Der Operator [??=] (PHP 7.4) weist den Wert auf der rechten Seite der Variablen auf der linken Seite nur dann zu, wenn die Variable gleich [null] ist. Die Zeile ist äquivalent zu [if ($this->taxAdminData === null) { $this->taxAdminData = $this->getTaxAdminData(); }];
  • Zeile 38: Die Daten der Steuerbehörde werden direkt aus den öffentlichen schreibgeschützten Attributen des Objekts [TaxAdminData] gelesen;
  • Abgesehen von diesen Unterschieden bleibt die Steuerberechnungsmethode dieselbe wie in den vorherigen Versionen.

Die privaten Methoden zur Steuerberechnung lauten wie folgt:

    // --------------------------------------------------------------------------
    private function calculateTax2(string $married, int $children, float $salary): array
    {
        // Anzahl der Anteile
        $nbShares = match ($married) {
            "yes" => $children / 2 + 2,
            "no" => $children / 2 + 1,
        };
        // 1 Anteil pro Kind ab dem 3.
        if ($children >= 3) {
            // ein weiterer halber Anteil für jedes Kind ab dem 3.
            $nbShares += 0.5 * ($children - 2);
        }
        // zu versteuerndes Einkommen
        $taxableIncome = $this->getTaxableIncome($salary);
        // Zuschlag
        $surcharge = floor($taxableIncome - 0.9 * $salary);
        // wegen Rundungsproblemen
        if ($surcharge < 0) {
            $surcharge = 0;
        }
        // Familienquotient
        $quotient = $taxableIncome / $nbShares;
        // die Steuerstufen (Kopien der Arrays des Objekts)
        $limits = $this->taxAdminData->limits;
        $coeffR = $this->taxAdminData->coeffR;
        $coeffN = $this->taxAdminData->coeffN;
        // wird ans Ende des Arrays limits gesetzt, um die folgende Schleife zu stoppen
        $limits[count($limits) - 1] = $quotient;
        // Berechnung der Steuer
        $i = 0;
        while ($quotient > $limits[$i]) {
            $i++;
        }
        // jetzt können wir die Steuer berechnen
        $tax = floor($taxableIncome * $coeffR[$i] - $nbShares * $coeffN[$i]);
        // Ergebnis
        return ["tax" => $tax, "surcharge" => $surcharge, "rate" => $coeffR[$i]];
    }

    // taxableIncome=annualSalary-allowance
    // der Freibetrag hat ein Minimum und ein Maximum
    private function getTaxableIncome(float $salary): float
    {
        // Freibetrag von 10 % des Gehalts, begrenzt durch ein Minimum und ein Maximum
        $allowance = 0.1 * $salary;
        $allowance = min($allowance, $this->taxAdminData->tenPercentAllowanceMax);
        $allowance = max($allowance, $this->taxAdminData->tenPercentAllowanceMin);
        // zu versteuerndes Einkommen
        $taxableIncome = $salary - $allowance;
        // Ergebnis
        return floor($taxableIncome);
    }

    // berechnet eine eventuelle Ermäßigung
    private function getDiscount(string $married, float $salary, float $taxes): float
    {
        // zu Beginn eine Ermäßigung von null
        $discount = 0;
        // maximaler Steuerbetrag, um die Ermäßigung zu erhalten
        $taxCeilingForDiscount = $married === "yes"
            ? $this->taxAdminData->coupleTaxCeilingForDiscount
            : $this->taxAdminData->singleTaxCeilingForDiscount;
        if ($taxes < $taxCeilingForDiscount) {
            // maximaler Betrag der Ermäßigung
            $discountCeiling = $married === "yes"
                ? $this->taxAdminData->coupleDiscountCeiling
                : $this->taxAdminData->singleDiscountCeiling;
            // theoretische Ermäßigung
            $discount = $discountCeiling - 0.75 * $taxes;
            // die Ermäßigung darf den Steuerbetrag nicht übersteigen
            if ($discount > $taxes) {
                $discount = $taxes;
            }
            // keine Ermäßigung < 0
            if ($discount < 0) {
                $discount = 0;
            }
        }
        // Ergebnis
        return ceil($discount);
    }

    // berechnet eine eventuelle Minderung
    private function getReduction(string $married, float $salary, int $children, float $taxes): float
    {
        // die Einkommensgrenze, um Anspruch auf die Minderung von 20 % zu haben
        $incomeCeilingForReduction = $married === "yes"
            ? $this->taxAdminData->coupleIncomeCeilingForReduction
            : $this->taxAdminData->singleIncomeCeilingForReduction;
        $incomeCeilingForReduction += $children * $this->taxAdminData->halfShareReductionValue;
        if ($children > 2) {
            $incomeCeilingForReduction += ($children - 2) * $this->taxAdminData->halfShareReductionValue;
        }
        // zu versteuerndes Einkommen
        $taxableIncome = $this->getTaxableIncome($salary);
        // Minderung
        $reduction = 0;
        if ($taxableIncome < $incomeCeilingForReduction) {
            // Minderung von 20 %
            $reduction = 0.2 * $taxes;
        }
        // Ergebnis
        return ceil($reduction);
    }

Kommentare

  • Zeilen 80–83: Der Ausdruck [match] (PHP 8.0) ist ein besserer Ersatz für [if / else] aus Version 2. Er vergleicht den Wert [$married] mit den Werten seiner Zweige mit dem Gleichheitsoperator [===] und liefert den Wert des passenden Zweigs. Passt kein Zweig, löst er einen Fehler [UnhandledMatchError] aus: Ein anderer Familienstand als „yes“ oder „no“ bleibt nicht unbemerkt;
  • Zeilen 100–102: Die Tabellen der Steuerstufen werden in lokale Variablen kopiert. In PHP erzeugt die Zuweisung eines Arrays eine Kopie: Die Änderung von [$limits] in Zeile 104 wirkt sich nicht auf das Attribut [readonly] des Objekts [TaxAdminData] aus (was übrigens ein Fehler wäre);
  • Zeilen 122–123: Die Funktionen [min] und [max] ersetzen die beiden Anweisungen [if] aus Version 2: Der Abzug darf [tenPercentAllowanceMax] nicht überschreiten und [tenPercentAllowanceMin] nicht unterschreiten;
  • Der übrige Code ist derselbe wie in Version 2, wobei der Ausdruck [$taxAdminData["COUPLE_DISCOUNT_CEILING"]] zu [$this->taxAdminData->coupleDiscountCeiling] geworden ist. Ein Tippfehler in einem Attributnamen wird nun vom Editor [VS Code] (Erweiterung [PHP Intelephense]) markiert, sobald der Code geschrieben wird, was bei einem Tippfehler in einem Array-Schlüssel nicht der Fall war.

Die Methode [executeBatchTaxes] lautet wie folgt:

    // Steuerberechnung im Batch-Modus
    // --------------------------------------------------------------------------
    #[\Override]
    public function executeBatchTaxes(string $taxPayersFileName, string $resultsFileName, string $errorsFileName): void
    {
        // die drei Dateien sind noch nicht geöffnet
        $errors = $results = $data = false;
        // sobald Dateien verarbeitet werden, können einige Fehler auftreten
        try {
            // Öffnen der Fehlerdatei
            $errors = fopen($errorsFileName, "w");
            if ($errors === false) {
                throw new TaxException("Unable to create the errors file [$errorsFileName]", 10);
            }
            // Öffnen der Ergebnisdatei
            $results = fopen($resultsFileName, "w");
            if ($results === false) {
                throw new TaxException("Unable to create the results file [$resultsFileName]", 11);
            }
            // Öffnen der Datei mit den Steuerpflichtigendaten
            $data = is_readable($taxPayersFileName) ? fopen($taxPayersFileName, "r") : false;
            if ($data === false) {
                throw new TaxException("Unable to open the taxpayers' declarations [$taxPayersFileName] for reading", 12);
            }
            // wir verarbeiten die aktuelle Zeile der Datei mit den Steuerpflichtigendaten
            // die die Form Familienstand, Anzahl der Kinder, Jahresgehalt hat
            $num = 0;         // Nr. der aktuellen Zeile
            $nbErrors = 0;    // Anzahl der aufgetretenen Fehler
            while (($line = fgets($data, 100)) !== false) {
                // eine Zeile mehr
                $num++;
                // wir entfernen ein eventuelles Zeilenende-Zeichen
                $line = Utilities::cutNewLineChar($line);
                // wir ignorieren die leeren Zeilen
                if (trim($line) === "") {
                    continue;
                }
                // die Zeile muss 3 Felder haben: married,children,salary
                $fields = array_map(trim(...), explode(",", $line));
                $error = count($fields) !== 3;
                if (!$error) {
                    [$married, $children, $salary] = $fields;
                    // der Familienstand muss yes oder no sein
                    $married = strtolower($married);
                    // die Anzahl der Kinder und das Gehalt müssen positive oder null ganze Zahlen sein
                    $error = !in_array($married, ["yes", "no"], true)
                        || !preg_match('/^\d+$/', $children)
                        || !preg_match('/^\d+$/', $salary);
                }
                // Fehler?
                if ($error) {
                    fputs($errors, "line [$num] of the file [$taxPayersFileName] is incorrect\n");
                    $nbErrors++;
                    continue;
                }
                // wir berechnen die Steuer
                $result = $this->calculateTax($married, (int) $children, (int) $salary);
                // wir schreiben das Ergebnis in die Ergebnisdatei
                $result = ["married" => $married, "children" => (int) $children, "salary" => (int) $salary] + $result;
                fputs($results, json_encode($result, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR) . "\n");
            }
            // Fehler?
            if ($nbErrors > 0) {
                throw new TaxException("There were $nbErrors incorrect line(s): see the file [$errorsFileName]", 15);
            }
        } finally {
            // wir schließen die Dateien, die geöffnet wurden
            foreach ([$data, $results, $errors] as $file) {
                if ($file !== false) {
                    fclose($file);
                }
            }
        }
    }

Code-Kommentare

  • Zeile 185: Die Methode nimmt drei Parameter entgegen:
    • [$taxPayersFileName]: der Name der Textdatei mit den Daten der Steuerpflichtigen. Jede Textzeile enthält die Daten eines Steuerpflichtigen im folgenden Format: Familienstand (yes/no), Anzahl der Kinder, Jahresgehalt; zum Beispiel [yes,2,55555];
    • [$resultsFileName]: der Name der Textdatei, die die Ergebnisse enthalten wird. Jede Textzeile ist die JSON-Zeichenkette mit den Ergebnissen eines Steuerpflichtigen, zum Beispiel [{"married":"yes","children":2,"salary":50000,"tax":1384,"surcharge":0,"discount":384,"reduction":347,"rate":0.14}];
    • [$errorsFileName]: der Name der Textdatei mit den Fehlern, zum Beispiel [line [5] of the file [taxpayersdata.txt] is incorrect];
  • Zeile 188: Die Variablen für die drei Dateien werden mit [false] initialisiert (Datei nicht geöffnet). So lässt sich in der Klausel [finally] feststellen, welche Dateien geöffnet wurden;
  • Zeile 190: Da mehrere Operationen eine Ausnahme auslösen können, umschließt eine Struktur [try / finally] den gesamten Code der Methode;
  • Zeilen 192–204: Die drei Dateien werden geöffnet. Sobald ein Öffnungsvorgang fehlschlägt, wird eine Ausnahme ausgelöst, mit einem jeweils anderen Fehlercode;
  • Zeile 210: Die Zeilen der Datei [$data] werden einzeln in Blöcken von bis zu 100 Zeichen gelesen (alle Zeilen sind kürzer als 100 Zeichen);
  • Zeile 214: Die statische Methode [Utilities::cutNewLineChar] wird verwendet, um eventuelle Zeilenendzeichen zu entfernen;
  • Zeilen 216–218: Leere Zeilen (zum Beispiel am Ende der Datei) werden ignoriert;
  • Zeile 220: Die Zeile wird am Komma aufgeteilt, und die Leerzeichen um jedes Feld werden entfernt. [trim(...)] ist die Syntax für „First-Class Callables“ (PHP 8.1): Sie verweist auf die Funktion [trim] selbst, ohne sie aufzurufen;
  • Zeile 221: Die Zeile muss genau drei Felder haben. Der PHP-7-Kurs schrieb direkt [list($married, $children, $salary) = explode(",", $line)]: Bei einer Zeile mit nur zwei Feldern gibt PHP 8 die Warnung „Undefined array key 2“ aus;
  • Zeilen 227–229: Die Gültigkeit der drei Elemente wird geprüft: Der Familienstand muss „yes“ oder „no“ sein, und die Anzahl der Kinder und das Gehalt müssen positive ganze Zahlen oder null sein (eine Ziffernfolge, regulärer Ausdruck [/^\d+$/]). Der dritte Parameter [true] von [in_array] erzwingt einen strikten Vergleich [===];
  • Zeilen 232–236: Ist die Zeile ungültig, wird keine Ausnahme ausgelöst; stattdessen wird eine Fehlermeldung in die Textdatei [$errors] geschrieben, und das Programm geht zur nächsten Zeile über;
  • Zeile 238: Ist die gelesene Zeile gültig, wird die Steuer berechnet. Das Ergebnis wird als assoziatives Array [tax, surcharge, discount, reduction, rate] zurückgegeben;
  • Zeile 240: Die Schlüssel [married, children, salary] werden am Anfang des Ergebnisses hinzugefügt;
  • Zeile 241: Das Ergebnis wird in Form seiner JSON-Zeichenkette in die Textdatei [$results] geschrieben. Die Option [JSON_THROW_ON_ERROR] bewirkt, dass die Funktion [json_encode] eine Ausnahme [JsonException] auslöst, anstatt [false] zurückzugeben, wenn die Kodierung fehlschlägt;
  • Zeilen 244–246: Nach der Verarbeitung der Datei [$data] wird die Anzahl der fehlerhaften Zeilen geprüft. Gibt es mindestens eine, wird eine Ausnahme ausgelöst;
  • Zeilen 247–254: Unabhängig davon, wie die Ausführung der Methode endet (normal oder durch eine Ausnahme), wird die Klausel [finally] ausgeführt: Alle geöffneten Dateien werden geschlossen. Der PHP-7-Kurs verwendete eine Struktur [try / catch / finally] , deren Klausel [catch] die Ausnahme lediglich erneut auslöste. Das ist unnötig: Eine Struktur [try / finally] ohne [catch] lässt die Ausnahme weiterlaufen, nachdem die Klausel [finally] ausgeführt wurde. Außerdem schloss der PHP-7-Kurs die drei Dateien, ohne zu prüfen, ob sie geöffnet worden waren: In PHP 8 verursacht [fclose(false)] einen Fehler [TypeError].

8.7. Die Klasse [TaxWithTaxAdminDataInJsonFile]

Die abstrakte Klasse [AbstractBaseTax] implementiert die Methode [getTaxAdminData] der Schnittstelle [InterfaceTax] nicht. Wir müssen sie daher in einer abgeleiteten Klasse definieren. Das tun wir in der folgenden abgeleiteten Klasse [TaxWithTaxAdminDataInJsonFile]:

<?php

declare(strict_types=1);

// Namespace
namespace Application;

// eine Klasse, die die Daten der Steuerverwaltung aus einer JSON-Datei bezieht
class TaxWithTaxAdminDataInJsonFile extends AbstractBaseTax
{
    // die Daten der Steuerverwaltung
    private readonly TaxAdminData $taxAdminData;

    // der Konstruktor
    public function __construct(string $jsonFileName)
    {
        // wir initialisieren $this->taxAdminData aus der JSON-Datei
        // kann eine TaxException werfen
        $this->taxAdminData = TaxAdminData::fromJsonFile($jsonFileName);
    }

    // gibt die zur Steuerberechnung verwendeten Daten zurück
    #[\Override]
    public function getTaxAdminData(): TaxAdminData
    {
        return $this->taxAdminData;
    }
}

Kommentare

  • Zeile 9: Die Klasse [TaxWithTaxAdminDataInJsonFile] erweitert die abstrakte Klasse [AbstractBaseTax]. Sie muss die Methode [getTaxAdminData] definieren, die ihre Elternklasse nicht definiert hat;
  • Zeile 12: Das Attribut [$taxAdminData] enthält die Daten der Steuerbehörde. Es ist schreibgeschützt: Es wird einmalig vom Konstruktor initialisiert. Beachten Sie, dass auch die Elternklasse ein privates Attribut [$taxAdminData] hat: Die beiden Attribute sind verschieden, da ein privates Attribut nur innerhalb der Klasse sichtbar ist, die es deklariert;
  • Zeilen 15–20: Der Konstruktor erhält als einzigen Parameter den Namen der JSON-Datei mit den Steuerdaten;
  • Zeile 19: Es wird ein Objekt vom Typ [TaxAdminData] aus der JSON-Datei erzeugt. Dieser Vorgang kann eine Ausnahme vom Typ [TaxException] auslösen. Diese Ausnahme wird bis zum Hauptskript [main.php] weitergereicht;
  • Zeilen 23–27: Für die Methode [getTaxAdminData], die die Elternklasse nicht definiert hatte, wird ein Rumpf bereitgestellt. Hier genügt es, sicherzustellen, dass das Attribut [$this->taxAdminData] vom Konstruktor initialisiert wird.

8.8. Das Skript [main.php]

Diese Klassen und Schnittstellen werden vom folgenden Skript verwendet, [main.php]:

<?php

// strikte Einhaltung der deklarierten Typen der Funktionsparameter und -ergebnisse
declare(strict_types=1);

// Namespace
namespace Application;

// Einbindung der Schnittstellen und Klassen
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";

// Definition der Konstanten
const TAXPAYERSDATA_FILENAME = "taxpayersdata.txt";
const RESULTS_FILENAME = "results.txt";
const ERRORS_FILENAME = "errors.txt";
const TAXADMINDATA_FILENAME = "taxadmindata.json";

try {
    // wir erzeugen ein Objekt [TaxWithTaxAdminDataInJsonFile]
    $tax = new TaxWithTaxAdminDataInJsonFile(TAXADMINDATA_FILENAME);
    // wir führen den Steuer-Batch aus
    $tax->executeBatchTaxes(TAXPAYERSDATA_FILENAME, RESULTS_FILENAME, ERRORS_FILENAME);
} catch (TaxException $ex) {
    // wir zeigen den Fehler an
    print "Error no. {$ex->getCode()}: {$ex->getMessage()}\n";
}
// Ende
print "Done\n";

Kommentare

  • Zeile 4: Die strikte Einhaltung der Typen der Funktionsparameter wird erzwungen;
  • Zeile 7: Das Skript [main.php] befindet sich ebenfalls im Namespace [Application];
  • Zeilen 10–15: Die vom Skript verwendeten Klassen- und Schnittstellendateien werden geladen. Beachten Sie, dass wir hier keine Anweisung [use] verwendet haben, um die vollständigen Namen der vom Skript verwendeten Klassen zu deklarieren. Das ist unnötig, da sich das Skript und die Klassen im selben Namespace befinden, [Application]. Beachten Sie auch die Ladereihenfolge: Eine Elternklasse oder Schnittstelle muss vor der Klasse geladen werden, die von ihr abgeleitet ist oder sie implementiert;
  • Zeilen 18–21: die Namen der im Skript verwendeten Dateien. Diese Namen sind relativ: Die Dateien werden im aktuellen Verzeichnis gesucht, also in dem, aus dem das Skript ausgeführt wird;
  • Zeile 25: Es wird ein Objekt [TaxWithTaxAdminDataInJsonFile] erzeugt. Dabei kann eine Ausnahme ausgelöst werden, wenn die JSON-Datei fehlt oder fehlerhaft ist;
  • Zeile 27: Die Methode [executeBatchTaxes] wird aufgerufen, die die Steuern für alle Steuerpflichtigen in der Datei [TAXPAYERSDATA_FILENAME] berechnet. Die Ergebnisse werden in die Datei [RESULTS_FILENAME], geschrieben, und eventuelle Fehler in die Datei [ERRORS_FILENAME];
  • Zeilen 28–31: Tritt ein Fehler auf, werden Fehlercode und Meldung angezeigt. Der Ausdruck [{$ex->getCode()}] erlaubt es, das Ergebnis eines Methodenaufrufs in eine Zeichenkette einzufügen.

8.9. Ergebnisse

Führen Sie das Skript in einem Terminal aus, das im Ordner [version-03] geöffnet wurde:

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

Mit der oben gezeigten Datei der Steuerpflichtigen [taxpayersdata.txt] wird die folgende Fehlerdatei [errors.txt] erzeugt:

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

und die folgende Ergebnisdatei [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}

Die für die elf korrekten Zeilen berechneten Steuern (2814, 1384, 0, 19884, 16782, 9200, 4230, 22986, 0, 64210, 42842) sind die aus den Versionen 1 und 2.

8.10. Fazit

Version 3 bietet dieselbe Funktionalität wie Version 2, ist aber besser für die Fehlerbehandlung gerüstet: unvollständige oder fehlerhafte Steuerdaten, fehlerhafte Zeilen in der Datei der Steuerpflichtigen oder fehlende Dateien. Jeder Fehler wird durch eine Ausnahme [TaxException] mit einer Meldung und einem spezifischen Code angezeigt.

Die Klasse [AbstractBaseTax] vereint jedoch zwei Arten von Code: einerseits die Steuerberechnung, andererseits das Lesen und Schreiben von Dateien. In den folgenden Kapiteln werden wir sehen, wie sich diese beiden Aufgabenbereiche in verschiedene Schichten trennen lassen.