Skip to content

11. Übungsanwendung – Version 4

Die Anwendung zur Steuerberechnung setzt nun die folgende Schichtenstruktur um:

Image

Wir verwenden die Komponenten aus Version 3 wieder und passen sie an die neue Architektur der Anwendung an. Man spricht von „Refactoring“ (Überarbeitung des Codes). Hier nehmen wir an, dass die von der Anwendung benötigten Daten in Textdateien gespeichert sind. Die Schicht [dao] übernimmt die Interaktionen mit diesen Dateien.

11.1. Verzeichnisstruktur der Skripte

Version 4 befindet sich im Ordner [scripts-console/tax/version-04]:

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

Der Ordner [Tests] enthält die automatisierten Tests für Version 4, die wir am Ende dieses Kapitels vorstellen.

11.2. Zwischen den Schichten ausgetauschte Objekte

Einige Elemente aus Version 3 übernehmen wir unverändert:

  • Die Ausnahme [TaxException] ist die Ausnahme, die die Schicht [dao] auslöst, wenn sie auf ein Problem stößt, entweder beim Datenzugriff oder bei der Beschaffenheit der Daten (fehlerhafte Daten);
  • die Klasse [Utilities] enthält Methoden, die für die Verwaltung von Textdateien nützlich sind (hier nur eine einzige Methode, [cutNewLineChar]);
  • Die [readonly]-Klasse [TaxAdminData] kapselt die Daten der Steuerverwaltung. Auf sie wird über die statische Methode [TaxAdminData::fromJsonFile($taxAdminDataFilename)] (oder [TaxAdminData::fromArray($data)]) zugegriffen, die die Daten validiert und eine [TaxException]-Ausnahme auslöst, wenn die Daten ungültig sind.

Wir fügen eine neue Klasse hinzu, [TaxPayerData], die die Daten eines Steuerzahlers und die Ergebnisse seiner Steuerberechnung kapselt ([TaxPayerData.php]):

<?php

declare(strict_types=1);

// Namespace
namespace Application;

// die Daten eines Steuerpflichtigen und die Ergebnisse der Berechnung seiner Steuer: ein unveränderliches Objekt
final readonly class TaxPayerData
{
    public function __construct(
        // zur Berechnung der Steuer des Steuerpflichtigen benötigte Daten
        public string $married,
        public int $children,
        public int $salary,
        // Ergebnisse der Steuerberechnung (null, solange die Steuer nicht berechnet wurde)
        public ?int $tax = null,
        public ?int $surcharge = null,
        public ?int $discount = null,
        public ?int $reduction = null,
        public ?float $rate = null,
    ) {
    }

    // gibt eine um die Ergebnisse der Steuerberechnung ergänzte Kopie des Objekts zurück
    // $results: Array [tax, surcharge, discount, reduction, rate], von der Schicht [business] zurückgegeben
    public function withResults(array $results): static
    {
        return clone($this, [
            "tax" => $results["tax"],
            "surcharge" => $results["surcharge"],
            "discount" => $results["discount"],
            "reduction" => $results["reduction"],
            "rate" => $results["rate"],
        ]);
    }

    // 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: Wie [TaxAdminData] ist die Klasse [TaxPayerData] unveränderlich: Ihre Objekte wandern von einer Schicht zur anderen, ohne dass das Risiko besteht, dass sie unterwegs verändert werden;
  • Zeilen 13–15: die Daten des Steuerzahlers, die zur Berechnung seiner Steuer erforderlich sind;
  • Zeilen 17–21: Die Ergebnisse der Steuerberechnung. Dies sind nullbare Felder ([?int], [?float]) mit dem Standardwert [null]: Ein Objekt [TaxPayerData] wird zunächst von der Schicht [dao] erzeugt und enthält nur die Daten des Steuerzahlers aus [new TaxPayerData("yes", 2, 55555)], da die Steuer noch nicht berechnet wurde. Die Attributnamen entsprechen den JSON-Schlüsseln der Ergebnisdatei aus Version 3: Die Datei [results.txt] behält somit dasselbe Format;
  • Zeilen 27–36: Da das Objekt unveränderlich ist, können ihm die Berechnungsergebnisse nicht hinzugefügt werden. Die Methode [withResults] gibt eine Kopie des Objekts zurück, ergänzt um die Ergebnisse. Sie verwendet den Operator [clone] aus PHP 8.5, der als zweiten Parameter ein Array der Attribute akzeptiert, die in der Kopie geändert werden sollen (siehe das Kapitel über Klassen). Der PHP-7-Kurs verwendete ein veränderbares Objekt mit acht Gettern und acht Settern;
  • Zeilen 39–42: Die Methode [__toString] gibt den JSON-String des Objekts zurück. Er wird zum Schreiben der Ergebnisdatei verwendet.

11.3. Die Schicht [dao]

Hier konzentrieren wir uns auf die Schicht [1] unserer Anwendung:

Image

11.3.1. Die Schnittstelle [InterfaceDao]

Die Schnittstelle der Schicht [dao] lautet wie folgt: [InterfaceDao.php]:

<?php

declare(strict_types=1);

// Namespace
namespace Application;

// die Schnittstelle der Schicht [dao]
// alle Methoden werfen bei einem nicht behebbaren Fehler eine [TaxException]
interface InterfaceDao
{
    // Lesen der Steuerpflichtigendaten
    // die fehlerhaften Zeilen werden in der Textdatei [$errorsFilename] gemeldet
    /** @return TaxPayerData[] */
    public function getTaxPayersData(string $taxPayersFilename, string $errorsFilename): array;

    // Lesen der Daten der Steuerverwaltung (Steuerstufen und Konstanten)
    public function getTaxAdminData(): TaxAdminData;

    // Speichern der Ergebnisse
    /** @param TaxPayerData[] $taxPayersData */
    public function saveResults(string $resultsFilename, array $taxPayersData): void;
}

Kommentare

  • Die Spezifikationen lauten wie folgt:
    • Die Daten der Steuerzahler sind in einer Textdatei gespeichert;
    • die Ergebnisse der Steuerberechnung werden in einer Textdatei gesichert;
    • eventuelle Fehler werden in einer Textdatei gesichert;
    • es ist nicht bekannt, in welchem Format die Daten der Steuerverwaltung vorliegen. Für jedes neue Format muss die Schnittstelle [InterfaceDao] durch eine neue Klasse implementiert werden;
    • Methoden der Schnittstelle, die beim Datenzugriff auf einen schwerwiegenden Fehler stoßen, müssen eine [TaxException]-Ausnahme auslösen;
  • Zeile 15: die Methode, die die Daten der Steuerzahler abruft, [marital status, number of children, annual salary]:
    • der erste Parameter ist der Name der Textdatei, die diese Daten enthält;
    • der zweite Parameter ist der Name der Textdatei, in der eventuell auftretende Fehler protokolliert werden sollen;
  • Zeile 14: Der Typ [array] gibt nicht an, was das Array enthält. Der Dokumentationskommentar [/** @return TaxPayerData[] */] (PHPDoc-Syntax) legt fest, dass es sich um ein Array von Objekten des Typs [TaxPayerData] handelt. PHP ignoriert dies, aber die Erweiterung [PHP Intelephense] von [VS Code] nutzt es: Sie kennt dann den Typ der Array-Elemente und kann während der Eingabe deren Attribute vorschlagen;
  • Zeile 18: die Methode, die die Daten der Steuerverwaltung abruft. Ihr werden keine Parameter übergeben, da wir nicht wissen, wie die Daten gespeichert sind;
  • Zeile 22: die Methode, die die Ergebnisse der Steuerberechnung in einer Textdatei sichert, deren Name als Parameter übergeben wird.

Beim Schreiben der Schnittstelle [InterfaceDao] wissen wir, dass es je nach Speicherung der Daten der Steuerverwaltung verschiedene Möglichkeiten geben wird, die Methode [getTaxAdminData] zu implementieren. Die Schnittstelle [InterfaceDao] wird daher von verschiedenen Klassen implementiert, die jeweils eine bestimmte Speicherart dieser Daten behandeln (JSON-Datei, Datenbank, Webservice). Diese Klassen teilen sich jedoch gemeinsamen Code: die Implementierung der Methoden [getTaxPayersData] und [saveResults]. Wie wir im Kapitel über Traits gesehen haben, lässt sich dieser Anwendungsfall auf zwei Arten umsetzen:

  • Wir erstellen eine abstrakte Klasse C, die den Code enthält, der den abgeleiteten Klassen gemeinsam ist. Die Klasse C implementiert die Schnittstelle I, aber bestimmte Methoden – die in den abgeleiteten Klassen definiert werden müssen – werden in der Klasse C als abstrakt deklariert, die damit selbst abstrakt ist. Anschließend erstellen wir von C abgeleitete Klassen C1 und C2, die jeweils die abstrakten Methoden ihrer Elternklasse C auf ihre eigene Weise implementieren;
  • wir erstellen einen Trait T, der der abstrakten Klasse C der vorherigen Lösung fast gleicht. Dieser Trait implementiert die Schnittstelle I nicht, da das syntaktisch nicht möglich ist. Anschließend erstellen wir die Klassen C1 und C2, die die Schnittstelle I implementieren und den Trait T verwenden. Diesen Klassen bleibt nur noch, die Methoden der Schnittstelle I zu implementieren, die der von ihnen importierte Trait T nicht implementiert.

In diesem Beispiel verwenden wir einen Trait [TraitDao]. In Version 3 wurde eine abstrakte Klasse verwendet.

11.3.2. Der Trait [TraitDao]

Der Code des Traits [TraitDao] lautet wie folgt: [TraitDao.php]:

<?php

declare(strict_types=1);

// Namespace
namespace Application;

// Implementierung der Methoden von [InterfaceDao], die mit Textdateien arbeiten
trait TraitDao
{
    // Trennzeichen der Felder einer Zeile der Steuerpflichtigendatei (Trait-Konstante, PHP 8.2)
    private const string SEPARATOR = ",";

    // Lesen der Steuerpflichtigendaten
    #[\Override]
    public function getTaxPayersData(string $taxPayersFilename, string $errorsFilename): array
    {
        // Array der Steuerpflichtigendaten
        $taxPayersData = [];
        // Array der Fehler
        $errors = [];
        // Öffnen der Datei mit den Steuerpflichtigendaten
        $taxPayersFile = is_readable($taxPayersFilename) ? fopen($taxPayersFilename, "r") : false;
        if ($taxPayersFile === false) {
            throw new TaxException("Unable to open the taxpayers' declarations [$taxPayersFilename] for reading", 12);
        }
        // die Datei ist geöffnet: wir müssen sie in jedem Fall schließen
        try {
            // 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
            while (($line = fgets($taxPayersFile, 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(self::SEPARATOR, $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) {
                    $errors[] = "line [$num] of the file [$taxPayersFilename] is incorrect";
                } else {
                    // wir speichern die Daten des Steuerpflichtigen
                    $taxPayersData[] = new TaxPayerData($married, (int) $children, (int) $salary);
                }
            }
            // sind wir am Dateiende?
            if (!feof($taxPayersFile)) {
                // wir haben die Schleife wegen eines Lesefehlers verlassen
                throw new TaxException("Error while reading the line no. [" . ($num + 1) . "] of the file [$taxPayersFilename]", 13);
            }
        } finally {
            // wir schließen die Datei
            fclose($taxPayersFile);
        }
        // wir speichern die Fehler in einer Textdatei
        $this->saveLines($errorsFilename, $errors);
        // Ergebnis der Funktion
        return $taxPayersData;
    }

    // Speichern der Ergebnisse
    #[\Override]
    public function saveResults(string $resultsFilename, array $taxPayersData): void
    {
        // jedes [TaxPayerData]-Element wird durch seine Methode [__toString] in einen JSON-String umgewandelt
        $this->saveLines($resultsFilename, array_map(strval(...), $taxPayersData));
    }

    // Speichern eines Arrays von Zeilen in einer Textdatei
    private function saveLines(string $fileName, array $lines): void
    {
        // wenn die Textdatei [$fileName] nicht existiert, wird sie erstellt, andernfalls überschrieben
        $data = implode("", array_map(fn(string $line): string => "$line\n", $lines));
        if (@file_put_contents($fileName, $data) === false) {
            throw new TaxException("Error while saving data to the text file [$fileName]", 14);
        }
    }
}

Kommentare

  • Zeile 9: Hier definieren wir einen Trait, keine Klasse;
  • Zeile 12: eine Konstante für das Feldtrennzeichen (PHP 8.2), typisiert (PHP 8.3): das Feldtrennzeichen einer Zeile der Steuerzahlerdatei. Sie wird zu einer Konstante der Klasse, die den Trait verwendet, und mit der Notation [self::SEPARATOR] verwendet;
  • Zeile 15: Ab PHP 8.3 wird das Attribut [#[\Override]] auf einer Trait-Methode akzeptiert. Das wird in der Klasse geprüft, die den Trait verwendet: Hier muss die Methode einer Methode der Schnittstelle [InterfaceDao] entsprechen, die diese Klasse implementiert;
  • Zeilen 16–74: Die Methode [getTaxPayersData] implementiert die gleichnamige Methode der Schnittstelle [InterfaceDao]. Sie ruft die Daten der Steuerzahler [marital status, number of children, annual salary] aus der Textdatei mit dem Namen [$taxPayersFilename] ab. Sie gibt diese Daten in Form eines Arrays [$taxPayersData] zurück, das Elemente des Typs [TaxPayerData] enthält (Zeile 58);
  • Die Methode [getTaxPayersData] ähnelt stark der Methode [AbstractBaseTax::executeBatchTaxes] aus Version 3, mit folgenden Unterschieden:
    • Die Methode [getTaxPayersData] ruft nur die Daten der Steuerzahler ab. Sie führt keine Steuerberechnungen durch: Das ist die Aufgabe der Schicht [business];
    • Wie die Methode [executeBatchTaxes] markiert sie fehlerhafte Zeilen. Hier werden die Fehler zunächst in einem Array namens [$errors] gesammelt, das am Ende der Verarbeitung in eine Textdatei geschrieben wird (Zeile 71). Je nach Situation kann dieses Array leer sein oder nicht. Eine fehlerhafte Zeile löst keine Ausnahme mehr aus: Es ist Sache des aufrufenden Codes, die Fehlerdatei auszuwerten;
    • bei einem schwerwiegenden Fehler wird eine [TaxException]-Ausnahme ausgelöst (Zeile 25, Zeile 64);
  • Zeilen 23–26: Die Datei wird vor der Struktur [try / finally] geöffnet. Schlägt das Öffnen der Datei fehl, wird eine Ausnahme ausgelöst, und es gibt nichts zu schließen. Gelingt es, stellt die Klausel [finally] (Zeilen 66–69) sicher, dass die Datei geschlossen wird, unabhängig davon, ob eine Ausnahme auftritt. Dieses Vorgehen erspart die Prüfung „Wurde die Datei geöffnet?“, die in Version 3 vorkam;
  • Zeilen 62–65: Beachten Sie die Verarbeitung beim Verlassen der Leseschleife. Die Funktion [fgets] hat den Nachteil, dass sie [false] sowohl dann zurückgibt, wenn der Lesevorgang das Dateiende erreicht, als auch dann, wenn er aufgrund eines Fehlers scheitert. Um beide Fälle zu unterscheiden, prüfen wir mit der Funktion [feof], ob das Dateiende erreicht wurde. Ist das nicht der Fall, ist ein Fehler aufgetreten, und es wird eine Ausnahme ausgelöst;
  • Zeilen 78–82: Implementierung der Methode [saveResults] der Schnittstelle [InterfaceDao]. Jedes Element [TaxPayerData] des Arrays wird von der Funktion [strval] in einen String umgewandelt, die die Methode [__toString] des Objekts aufruft: Das liefert dessen JSON-String. [strval(...)] bezeichnet die Funktion [strval] selbst (First-Class-Callable, PHP 8.1);
  • Zeilen 85–92: Die private Methode [saveLines] schreibt ein Array von Zeilen in eine Textdatei, wobei jede Zeile mit dem Zeilenendezeichen \n abgeschlossen wird;
  • Zeile 89: Die PHP-Funktion [file_put_contents] schreibt einen String in eine Textdatei. Sie öffnet die Datei, schreibt den String hinein und schließt die Datei. Tritt ein Fehler auf, gibt sie [false] zurück. In diesem Fall gibt PHP außerdem eine Warnung aus. Der Operator [@] unterdrückt diese Warnung: Der Fehler wird über die in der nächsten Zeile ausgelöste Ausnahme mit einer klareren Meldung gemeldet.

Der Trait [TraitDao] hat zwei der Methoden der Schnittstelle [InterfaceDao] implementiert: [getTaxPayersData] und [saveResults]. Es bleibt noch die Methode [getTaxAdminData] zu implementieren, die die Daten der Steuerverwaltung abruft.

11.3.3. Die Klasse [DaoTaxWithTaxAdminDataInJsonFile]

Die Klasse [DaoTaxWithTaxAdminDataInJsonFile] implementiert die Schnittstelle [InterfaceDao] wie folgt:

<?php

declare(strict_types=1);

// Namespace
namespace Application;

// eine Schicht [dao], die die Daten der Steuerverwaltung in einer JSON-Datei findet
class DaoTaxWithTaxAdminDataInJsonFile implements InterfaceDao
{
    // das Trait implementiert die Methoden [getTaxPayersData] und [saveResults] der Schnittstelle
    use TraitDao;

    // das Objekt vom Typ [TaxAdminData], das die Daten der Steuerverwaltung enthält
    private readonly TaxAdminData $taxAdminData;

    // der Konstruktor
    public function __construct(string $taxAdminDataFilename)
    {
        // kann eine [TaxException] werfen
        $this->taxAdminData = TaxAdminData::fromJsonFile($taxAdminDataFilename);
    }

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

Kommentare

  • Zeile 9: Die Klasse [DaoTaxWithTaxAdminDataInJsonFile] implementiert die Schnittstelle [InterfaceDao];
  • Zeile 12: Die Klasse verwendet den Trait [TraitDao], der, wie wir wissen, die Methoden [getTaxPayersData] und [saveResults] der Schnittstelle [InterfaceDao] implementiert. Der Klasse bleibt nur noch, die Methode [getTaxAdminData] zu implementieren, die die Daten der Steuerverwaltung abruft;
  • Zeile 15: das Attribut vom Typ [TaxAdminData] , das von der Methode [getTaxAdminData] zurückgegeben wird. Es wird vom Konstruktor initialisiert;
  • Zeile 21: Die Daten der Steuerverwaltung werden aus der JSON-Datei gelesen. Fehlt die Datei oder ist sie ungültig, wird eine [TaxException]-Ausnahme an den aufrufenden Code ausgelöst.

Damit ist die Schicht [dao] unserer Anwendung fertig: Wir haben eine Klasse, die die von uns definierte Schnittstelle [InterfaceDao] vollständig implementiert. Wir können nun zur Schicht [business] übergehen.

11.4. Die Schicht [business]

Wir implementieren nun die Schicht [2] unserer Architektur:

Image

11.4.1. Die Schnittstelle [InterfaceBusiness]

Die Schnittstelle der Schicht [business] lautet wie folgt: [InterfaceBusiness.php]:

<?php

declare(strict_types=1);

// Namespace
namespace Application;

// die Schnittstelle der Schicht [business]
interface InterfaceBusiness
{
    // Berechnung der Steuer eines Steuerpflichtigen
    // gibt das Array [tax, surcharge, discount, reduction, rate] zurück
    public function calculateTax(string $married, int $children, int $salary): array;

    // Berechnung der Steuern im Batch-Modus
    // kann eine [TaxException] werfen, die aus der Schicht [dao] aufsteigt
    public function executeBatchTaxes(string $taxPayersFileName, string $resultsFileName, string $errorsFileName): void;
}

Kommentare

  • Zeile 13: Die Schicht [business] kann den Steuerbetrag eines bestimmten Steuerzahlers berechnen, sofern ihr folgende Angaben vorliegen: Familienstand, Anzahl der Kinder und Jahresgehalt. Die Methode [calculateTax] ist eine rein „fachliche“ Methode: Sie kümmert sich nicht um die Herkunft der Daten, die sie verwendet. Sie verwendet die Schicht [dao] nicht und löst daher keine Ausnahme aus;
  • Zeile 17: Die Schicht [business] kann außerdem den Steuerbetrag für eine Gruppe von Steuerzahlern berechnen, deren Daten in der Textdatei mit dem Namen [$taxPayersFileName] gesammelt sind. Sie schreibt die Ergebnisse in die Textdatei mit dem Namen [$resultsFileName]. Nicht schwerwiegende Fehler werden in der Textdatei mit dem Namen [$errorsFileName] protokolliert. Die Methode [executeBatchTaxes] muss die Schicht [dao] aufrufen, die den Zugriff auf das Dateisystem übernimmt. Von der Schicht [dao] können dann Ausnahmen weitergereicht werden: Die Methode [executeBatchTaxes] fängt sie nicht ab; sie lässt sie bis zum Hauptskript weiterlaufen.

11.4.2. Die Klasse [Business]

Die Klasse [Business] implementiert die Schnittstelle [InterfaceBusiness] wie folgt:

<?php

declare(strict_types=1);

// Namespace
namespace Application;

// die Schicht [business]
class Business implements InterfaceBusiness
{
    // Daten der Steuerverwaltung
    private readonly TaxAdminData $taxAdminData;

    // die Schicht [dao] wird vom Konstruktor injiziert
    public function __construct(private readonly InterfaceDao $dao)
    {
        // wir rufen die zur Steuerberechnung verwendeten Daten ab
        // die Methode [getTaxAdminData] kann eine [TaxException] werfen
        // wir lassen sie dann zum aufrufenden Code aufsteigen
        $this->taxAdminData = $this->dao->getTaxAdminData();
    }

    // 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
        //
        // 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 [Business] implementiert die Schnittstelle [InterfaceBusiness], das heißt die Methoden [calculateTax] und [executeBatchTaxes];
  • Zeile 12: das Objekt vom Typ [TaxAdminData], das die Daten der Steuerverwaltung kapselt. Diese Daten werden von der fachlichen Methode [calculateTax] benötigt;
  • Zeilen 15–21: Der Konstruktor initialisiert die beiden Attribute der Klasse:
    • das Attribut [$dao], eine Referenz auf die Schicht [dao], wird durch Promotion des Konstruktorparameters initialisiert. Das ist erforderlich, damit die Schicht [business] weiß, an wen sie sich wenden muss, wenn sie externe Daten benötigt. Beachten Sie, dass der Typ dieses Parameters der der Schnittstelle [InterfaceDao] ist, sodass die Klasse [Business] mit jeder Klasse arbeiten kann, die diese Schnittstelle implementiert. Der PHP-7-Kurs bot zusätzlich einen Setter [setDao] an: Dieser entfällt nun, da die Schicht [dao] ein für alle Mal über den Konstruktor injiziert wird;
    • Das Attribut [$taxAdminData] wird durch den Aufruf der Methode [getTaxAdminData] der Schicht [dao] initialisiert;
  • wir schließen daraus, dass bei der Ausführung der Methoden [calculateTax] und [executeBatchTaxes] beide Attribute [$dao] und [$taxAdminData] initialisiert sind. Der Test [$this->taxAdminData ??= $this->getTaxAdminData()] aus Version 3 ist nicht mehr nötig;
  • Zeilen 26–77: Dieser Code stammt aus der Methode [AbstractBaseTax::calculateTax] aus Version 3. Dasselbe gilt für die privaten Methoden [calculateTax2], [getTaxableIncome], [getDiscount] und [getReduction], die hier nicht wiedergegeben sind.

Die Methode [Business::executeBatchTaxes] lautet wie folgt:

    // Berechnung der Steuern im Batch-Modus
    // --------------------------------------------------------------------------
    #[\Override]
    public function executeBatchTaxes(string $taxPayersFileName, string $resultsFileName, string $errorsFileName): void
    {
        // wir lassen die Exceptions aus der Schicht [dao] aufsteigen
        // wir rufen die Steuerpflichtigendaten ab
        $taxPayersData = $this->dao->getTaxPayersData($taxPayersFileName, $errorsFileName);
        // wir berechnen die Steuer jedes Steuerpflichtigen
        $results = array_map(
            fn(TaxPayerData $taxPayerData): TaxPayerData => $taxPayerData->withResults(
                $this->calculateTax($taxPayerData->married, $taxPayerData->children, $taxPayerData->salary)
            ),
            $taxPayersData
        );
        // Speichern der Ergebnisse
        $this->dao->saveResults($resultsFileName, $results);
    }
}

Kommentare

  • Zeile 188: Die Methode muss die Methode [calculateTax] wiederholt für jeden Steuerzahler aufrufen, der in der Textdatei mit dem Namen [$taxPayersFileName] gefunden wird, und die Ergebnisse in die Textdatei mit dem Namen [$resultsFileName] schreiben. Eventuell auftretende nicht schwerwiegende Fehler werden in der Textdatei mit dem Namen [$errorsFileName] protokolliert. Die Methode löst selbst keine Ausnahmen aus, lässt aber die von der Schicht [dao] ausgelösten durch;
  • Zeile 192: Die Daten der Steuerzahler werden bei der Schicht [dao] angefordert. Diese Schicht gibt ein Array von Elementen des Typs [TaxPayerData] zurück. Tritt hier eine Ausnahme auf, wird sie, da sie von keinem [catch] abgefangen wird, automatisch an den aufrufenden Code weitergereicht, und der Rest der Methode wird nicht ausgeführt;
  • Zeilen 194–199: Die Funktion [array_map] wendet eine Funktion auf jedes Element des Arrays [$taxPayersData] an und gibt das Array der Ergebnisse zurück. Die angewendete Funktion ist eine Arrow-Funktion, die die Steuer des Steuerzahlers [$taxPayerData] berechnet und eine Kopie von [$taxPayerData] zurückgibt, die mit den Berechnungsergebnissen gefüllt ist (Zeile 195). Beachten Sie, dass die Arrow-Funktion [$this] verwendet: Eine Arrow-Funktion erfasst Variablen aus ihrem Kontext automatisch, einschließlich [$this];
  • Zeile 201: Sobald die Steuer für alle Steuerzahler berechnet ist, werden die Ergebnisse in einer Textdatei gesichert. Diese Aufgabe übernimmt die Schicht [dao].

Im Allgemeinen ist die Schicht [business] recht einfach zu schreiben, da sie mit der Schicht [dao] kommuniziert, die den Datenzugriff und die damit verbundene Fehlerbehandlung übernimmt.

11.5. Das Hauptskript

Nun schreiben wir das Skript für die Schicht [3] unserer Architektur:

Image

Das Hauptskript lautet wie folgt: [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__ . "/Utilities.php";
require_once __DIR__ . "/TaxAdminData.php";
require_once __DIR__ . "/TaxPayerData.php";
require_once __DIR__ . "/InterfaceDao.php";
require_once __DIR__ . "/TraitDao.php";
require_once __DIR__ . "/DaoTaxWithTaxAdminDataInJsonFile.php";
require_once __DIR__ . "/InterfaceBusiness.php";
require_once __DIR__ . "/Business.php";

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

try {
    // Erzeugung der Schicht [dao]
    $dao = new DaoTaxWithTaxAdminDataInJsonFile(TAXADMINDATA_FILENAME);
    // Erzeugung der Schicht [business]
    $business = new Business($dao);
    // Steuerberechnung im Batch-Modus
    $business->executeBatchTaxes(TAXPAYERSDATA_FILENAME, RESULTS_FILENAME, ERRORS_FILENAME);
    print "The results have been saved in the file [" . RESULTS_FILENAME . "]\n";
} catch (TaxException $ex) {
    // wir zeigen den Fehler an
    print "Error no. {$ex->getCode()}: {$ex->getMessage()}\n";
}
// Ende
print "Done\n";

Kommentare

  • Zeilen 10–18: Laden der Klassen, Schnittstellen und Traits der Anwendung. Ein Trait muss vor der Klasse geladen werden, die ihn verwendet;
  • Zeile 21: der Name der Datei mit den Steuerzahlerdaten;
  • Zeile 22: der Name der Ergebnisdatei;
  • Zeile 23: der Name der Fehlerdatei;
  • Zeile 24: der Name der JSON-Datei mit den Daten der Steuerverwaltung;
  • Zeile 28: Erzeugung der Schicht [dao];
  • Zeile 30: Erzeugung der Schicht [business] auf Grundlage der Schicht [dao];
  • Zeile 32: Ausführung der Methode [executeBatchTaxes] der Schicht [business];
  • Zeilen 34–37: Wie wir gesehen haben, können die Schichten [dao] und [business] Ausnahmen auslösen. Diese werden hier abgefangen.

11.6. Visuelle Tests

11.6.1. Test Nr. 1

Führen Sie das Skript [main.php] in einem Terminalfenster aus, das im Ordner [version-04] geöffnet ist:

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

Mit der Steuerzahlerdatei [taxpayersdata.txt] aus Version 3:

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

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}

Dies sind die Ergebnisse von Version 3.

11.6.2. Test Nr. 2

Im Hauptskript weisen wir der Steuerzahlerdatei einen Dateinamen zu, der nicht existiert:

const TAXPAYERSDATA_FILENAME = "taxpayersdata2.txt";

Die in der Konsole angezeigten Ergebnisse lauten wie folgt:

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

Es wird nur die Meldung der Ausnahme angezeigt, die von der Schicht [dao] ausgelöst wurde. Im PHP-7-Kurs wurde die Funktion [fopen] auf der nicht vorhandenen Datei aufgerufen: Der PHP-Interpreter zeigte dann vor der Ausnahmemeldung eine Warnung an:

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

Der PHP-7-Kurs unterdrückte diese Meldung, indem er PHP mit der Anweisung [ini_set("display_errors", "0")] anwies, keine Fehler anzuzeigen. Das ist die richtige Konfiguration für einen Produktionsserver (Fehler werden dann in eine Logdatei geschrieben), aber während der Entwicklung müssen alle Meldungen von PHP sichtbar sein. Wir lösen die Warnung daher lieber gar nicht erst aus: Die Schicht [dao] verwendet die Funktion [is_readable], um vor dem Öffnen zu prüfen, ob die Datei gelesen werden kann.

11.7. [PHPUnit]-Tests

Visuelle Tests sind bei Weitem unzureichend:

  • wir beschränken uns in der Regel auf nur wenige Tests;
  • bei dieser visuellen Kontrolle passen wir womöglich nicht genau auf, und Details können uns entgehen.

In der professionellen Entwicklung der Praxis werden Tests als Code geschrieben und automatisch ausgeführt, oft nach jeder Codeänderung. Ziel ist es, die Tests so umfassend wie möglich zu gestalten. Dazu verwendet man Test-Frameworks.

Hier verwenden wir [PHPUnit] [https://phpunit.de/], das Standard-Test-Framework in PHP. Der PHP-7-Kurs verwendete das Framework [Codeception], das gewählt wurde, weil es in die Entwicklungsumgebung NetBeans integriert war – und das im Übrigen im Hintergrund PHPUnit nutzte. Wir nutzen nur einen kleinen Teil der Möglichkeiten von PHPUnit. Die Idee ist, nach jeder neuen Version der Übungsanwendung schnell überprüfen zu können, dass sie funktioniert. Erfolgreiche Tests geben dem Entwickler Vertrauen in den von ihm geschriebenen Code. Das ist ein wichtiger Faktor.

11.7.1. [PHPUnit] installieren

Wie viele PHP-Bibliotheken wird [PHPUnit] mit [Composer] installiert, dem PHP-Abhängigkeitsmanager, der in [Laragon] enthalten ist. Der Ordner [php8-oct-2026] mit dem Code des Kurses enthält eine Datei namens [composer.json] , die die vom Kurs verwendeten Bibliotheken auflistet. PHPUnit steht dort im Abschnitt [require-dev], der Bibliotheken enthält, die ausschließlich für die Entwicklung verwendet werden:

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

Falls noch nicht geschehen, öffnen Sie einfach ein Terminal im Ordner [php8-oct-2026] und geben Sie den folgenden Befehl ein:

composer install

[Composer] lädt dann alle in [composer.json] aufgeführten Bibliotheken in den Ordner [vendor] innerhalb von [php8-oct-2026] herunter. PHPUnit wird dort zusammen mit seiner ausführbaren Datei [vendor/bin/phpunit] installiert. In einem Projekt, das PHPUnit noch nicht enthält, würde man es mit dem Befehl [composer require --dev phpunit/phpunit] hinzufügen, der es herunterlädt und im Abschnitt [require-dev] der Datei [composer.json] einträgt.

Version 12 von PHPUnit erfordert PHP 8.3 oder höher. Die Dokumentation finden Sie unter [https://docs.phpunit.de/].

11.7.2. Die Konfigurationsdatei [phpunit.xml]

Der Ordner [php8-oct-2026] enthält außerdem die Konfigurationsdatei für PHPUnit, [phpunit.xml]. Wird PHPUnit aus diesem Ordner gestartet, verwendet es diese Datei automatisch:

<?xml version="1.0" encoding="UTF-8"?>
<!-- PHPUnit-Konfiguration für alle Tests des Kurses:
     php vendor/bin/phpunit scripts-console/tax/version-04/Tests -->
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
         colors="false"
         failOnDeprecation="true"
         failOnPhpunitDeprecation="true"
         failOnNotice="true"
         failOnWarning="true"
         displayDetailsOnTestsThatTriggerDeprecations="true"
         displayDetailsOnTestsThatTriggerNotices="true"
         displayDetailsOnTestsThatTriggerWarnings="true"
         cacheDirectory=".phpunit.cache">
    <source ignoreSuppressionOfDeprecations="true">
        <include>
            <directory>scripts-console</directory>
            <directory>scripts-web</directory>
        </include>
    </source>
</phpunit>

Kommentare

  • Zeile 5: Das XML-Schema, das die Syntax der Datei beschreibt. [VS Code] nutzt es, um die Datei zu validieren und mögliche Attribute vorzuschlagen;
  • Zeile 6: In der Ergebnisanzeige werden keine Farben verwendet. Mit [true] können Sie erfolgreiche Tests im Terminal grün und fehlgeschlagene Tests rot anzeigen lassen;
  • Zeilen 7–10: Ein Test, der eine Deprecation, einen Hinweis oder eine Warnung von PHP auslöst, gilt als fehlgeschlagen, selbst wenn seine Zusicherungen erfüllt sind. So wird sauberer PHP-8-Code erzwungen: Zum Beispiel würde die Verwendung eines in PHP 8.5 veralteten Features dazu führen, dass die Tests fehlschlagen;
  • Zeilen 11–13: In diesen Fällen zeigt PHPUnit die Details der Meldung von PHP an;
  • Zeile 14: der Ordner, in dem PHPUnit Informationen von einem Lauf zum nächsten ablegt (zum Beispiel fehlgeschlagene Tests, damit sie beim nächsten Mal zuerst ausgeführt werden);
  • Zeilen 15–20: die Ordner mit dem getesteten Quellcode. [ignoreSuppressionOfDeprecations] gibt an, dass eine Deprecation auch dann gemeldet wird, wenn sie durch den Operator [@] unterdrückt wurde.

11.7.3. Tests der Schicht [dao]

Die Tests für Version 4 befinden sich im Ordner [version-04/Tests]. Eine PHPUnit-Testklasse:

  • erweitert die Klasse [PHPUnit\Framework\TestCase];
  • hat einen Namen, der auf [Test] endet, in einer gleichnamigen Datei: So findet PHPUnit die Testklassen in einem Ordner;
  • hat öffentliche Testmethoden, deren Namen mit [test] beginnen;
  • kann eine Methode namens [setUp] haben, die vor jeder Testmethode ausgeführt wird, und eine Methode namens [tearDown], die nach jeder Testmethode ausgeführt wird. Sie dienen dazu, die Testumgebung aufzubauen und anschließend wieder aufzuräumen. Jede Testmethode läuft so in einer frischen, von den anderen unabhängigen Umgebung.

In einer Testmethode werden die Ergebnisse mit Zusicherungsmethoden überprüft, die von [TestCase] geerbt werden, zum Beispiel:

Zusicherung
Prüft, dass
[assertSame($expected, $actual)]
die beiden Werte identisch sind ([===]: gleicher Typ und gleicher Wert)
[assertEquals($expected, $actual)]
die beiden Werte gleich sind ([==])
[assertEqualsWithDelta($expected, $actual, $delta)]
beide Zahlen bis auf [$delta] gleich sind
[assertTrue($actual)], [assertFalse($actual)], [assertNull($actual)]
der Wert [true], [false] bzw. [null] ist
[assertCount($n, $array)]
das Array [$n] Elemente hat
[assertStringContainsString($substring, $string)]
der String die Teilzeichenfolge enthält
[expectException($class)]
der folgende Code eine Ausnahme der angegebenen Klasse auslöst

Um die Tests für eine Version der Übungsanwendung aufzubauen, verwenden wir eine Umgebung, die mit der des Hauptskripts [main.php] dieser Version identisch ist: Es werden dieselben Dateien geladen, und die Schichten werden auf dieselbe Weise aufgebaut.

Die Testklasse [DaoTest] lautet wie folgt: [Tests/DaoTest.php]:

<?php

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

// Namespace der Tests
namespace Application\Tests;

// die getesteten Klassen
use Application\DaoTaxWithTaxAdminDataInJsonFile;
use Application\TaxException;
use Application\InterfaceDao;
use Application\TaxPayerData;
// die PHPUnit-Klassen
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\TestCase;

// Laden der Klassen der Schicht [dao]
require_once __DIR__ . "/../TaxException.php";
require_once __DIR__ . "/../Utilities.php";
require_once __DIR__ . "/../TaxAdminData.php";
require_once __DIR__ . "/../TaxPayerData.php";
require_once __DIR__ . "/../InterfaceDao.php";
require_once __DIR__ . "/../TraitDao.php";
require_once __DIR__ . "/../DaoTaxWithTaxAdminDataInJsonFile.php";

final class DaoTest extends TestCase
{
    // der Ordner der Version 4
    private const string ROOT = __DIR__ . "/..";
    // die getestete Schicht [dao]
    private InterfaceDao $dao;
    // eine temporäre Datei für die Fehler
    private string $errorsFilename;

    // wird vor jedem Test ausgeführt
    #[\Override]
    protected function setUp(): void
    {
        // Erzeugung der Schicht [dao]
        $this->dao = new DaoTaxWithTaxAdminDataInJsonFile(self::ROOT . "/taxadmindata.json");
        // eine temporäre Datei
        $this->errorsFilename = tempnam(sys_get_temp_dir(), "errors");
    }

    // wird nach jedem Test ausgeführt
    #[\Override]
    protected function tearDown(): void
    {
        // Löschen der temporären Datei
        unlink($this->errorsFilename);
    }

    // die Daten der Steuerverwaltung
    public function testTaxAdminData(): void
    {
        $taxAdminData = $this->dao->getTaxAdminData();
        // Berechnungskonstanten
        $this->assertSame(1551.0, $taxAdminData->halfShareQfCeiling);
        $this->assertSame(21037.0, $taxAdminData->singleIncomeCeilingForReduction);
        $this->assertSame(42074.0, $taxAdminData->coupleIncomeCeilingForReduction);
        $this->assertSame(3797.0, $taxAdminData->halfShareReductionValue);
        $this->assertSame(1196.0, $taxAdminData->singleDiscountCeiling);
        $this->assertSame(1970.0, $taxAdminData->coupleDiscountCeiling);
        $this->assertSame(1595.0, $taxAdminData->singleTaxCeilingForDiscount);
        $this->assertSame(2627.0, $taxAdminData->coupleTaxCeilingForDiscount);
        $this->assertSame(12502.0, $taxAdminData->tenPercentAllowanceMax);
        $this->assertSame(437.0, $taxAdminData->tenPercentAllowanceMin);
        // Steuerstufen
        $this->assertSame([9964.0, 27519.0, 73779.0, 156244.0, 0.0], $taxAdminData->limits);
        $this->assertSame([0.0, 0.14, 0.30, 0.41, 0.45], $taxAdminData->coeffR);
        $this->assertSame([0.0, 1394.96, 5798.0, 13913.69, 20163.45], $taxAdminData->coeffN);
    }

    // fehlerhafte Steuerdatendateien
    public static function invalidFiles(): array
    {
        // [Dateiname, erwarteter Fehlercode]
        return [
            "non-existent file" => ["nonexistent.json", 1],
            "invalid JSON" => ["syntax.json", 2],
            "missing key" => ["missing-key.json", 4],
            "negative value" => ["negative-value.json", 6],
        ];
    }

    #[DataProvider("invalidFiles")]
    public function testInvalidTaxAdminData(string $file, int $code): void
    {
        // wir erwarten eine [TaxException] mit einem bestimmten Code
        $this->expectException(TaxException::class);
        $this->expectExceptionCode($code);
        // Erzeugung einer Schicht [dao] mit einer fehlerhaften Datei
        new DaoTaxWithTaxAdminDataInJsonFile(__DIR__ . "/data/$file");
    }

    // die Daten der Steuerpflichtigen
    public function testTaxPayersData(): void
    {
        $taxPayersData = $this->dao->getTaxPayersData(self::ROOT . "/taxpayersdata.txt", $this->errorsFilename);
        // 11 korrekte Steuerpflichtige
        $this->assertCount(11, $taxPayersData);
        $this->assertContainsOnlyInstancesOf(TaxPayerData::class, $taxPayersData);
        // der erste und der letzte
        $this->assertEquals(new TaxPayerData("yes", 2, 55555), $taxPayersData[0]);
        $this->assertEquals(new TaxPayerData("yes", 3, 200000), $taxPayersData[10]);
        // 2 fehlerhafte Zeilen: die Zeilen 5 und 8
        $errors = file($this->errorsFilename, FILE_IGNORE_NEW_LINES);
        $this->assertCount(2, $errors);
        $this->assertStringContainsString("line [5]", $errors[0]);
        $this->assertStringContainsString("line [8]", $errors[1]);
    }

    // eine nicht existierende Steuerpflichtigendatei
    public function testNonExistentTaxPayersData(): void
    {
        $this->expectException(TaxException::class);
        $this->expectExceptionCode(12);
        $this->dao->getTaxPayersData(self::ROOT . "/nonexistent.txt", $this->errorsFilename);
    }
}

Kommentare

  • Zeile 7: Die Testklassen befinden sich im Namensraum [Application\Tests], der sich von dem der Anwendung unterscheidet;
  • Zeilen 10–16: Die verwendeten Klassen werden mit der Anweisung [use] importiert. Die Klassen der Anwendung befinden sich im Namensraum [Application], die von PHPUnit in [PHPUnit\Framework];
  • Zeilen 19–25: Laden der Dateien der Schicht [dao], wie in [main.php]. Die Pfade sind relativ zum Ordner der Testdatei ([__DIR__]): Die Tests laufen unabhängig davon, aus welchem Ordner PHPUnit gestartet wird, und unabhängig vom Speicherort des Ordners [php8-oct-2026] auf der Festplatte. Der PHP-7-Kurs verwendete absolute Pfade ([C:/Data/...]), die für den Rechner des Autors spezifisch waren. Die Klassen von PHPUnit hingegen werden vom Lader von [Composer] automatisch geladen, der von PHPUnit initialisiert wird;
  • Zeile 27: Die Testklasse erweitert [TestCase];
  • Zeile 30: der Ordner von Version 4, in dem sich die Datendateien befinden;
  • Zeilen 38–44: Vor jedem Test wird die Schicht [dao] so aufgebaut, wie es [main.php] tut, und es wird eine temporäre Datei für Fehler angelegt. Die Funktion [tempnam] erzeugt eine eindeutig benannte Datei im Ordner für temporäre Dateien des Systems, wie ihn [sys_get_temp_dir] zurückgibt. Der PHP-7-Kurs erledigte diese Aufgabe im Konstruktor der Testklasse: Der Konstruktor von [TestCase] muss ab PHPUnit 10 nicht mehr überschrieben werden;
  • Zeilen 48–52: Nach jedem Test wird die temporäre Datei gelöscht;
  • Zeilen 55–73: Test der Daten der Steuerverwaltung. Wir prüfen, dass der Inhalt des Objekts [TaxAdminData], das die Schicht [dao] zurückgibt, dem Erwarteten entspricht. Verwendet wird die Methode [assertSame]: [assertSame(1551.0, ...)] prüft, dass der Wert die reelle Zahl 1551.0 ist; [assertSame(1551, ...)] würde fehlschlagen, da die ganze Zahl 1551 nicht mit der reellen Zahl 1551.0 identisch ist. Bei Arrays prüft [assertSame] , dass die beiden Arrays dieselben Schlüssel in derselben Reihenfolge mit identischen Werten haben;
  • Zeilen 76–85: ein Data-Provider . Das ist eine statische öffentliche Methode, die ein Array von Datensätzen zurückgibt. Jeder Datensatz ist ein Array von Argumenten, die an eine Testmethode übergeben werden. Der Schlüssel jedes Datensatzes („non-existent file“ ...) gibt ihm einen Namen, der in den Testergebnissen erscheint;
  • Zeile 87: Das PHP-8-Attribut [#[DataProvider]] gibt an, dass die Testmethode [testInvalidTaxAdminData] einmal für jeden Datensatz des Providers [invalidFiles] ausgeführt werden muss. Versionen von PHPUnit vor Version 10 verwendeten stattdessen eine Annotation in einem Kommentar: Annotationen werden ab PHPUnit 12 nicht mehr erkannt;
  • Zeilen 88–95: Prüfen, dass eine mit einer fehlerhaften Steuerdatendatei aufgebaute Schicht eine Ausnahme mit dem richtigen Fehlercode auslöst. Die Methoden [expectException] und [expectExceptionCode] müssen vor dem Code aufgerufen werden, der die Ausnahme auslöst: Der Test ist bestanden, wenn die Ausnahme ausgelöst wird; andernfalls schlägt er fehl. Die fehlerhaften Dateien befinden sich im Ordner [Tests/data]: eine fehlerhaft aufgebaute JSON-Datei (fehlendes Komma), eine Datei, in der der Schlüssel [coupleDiscountCeiling] fehlt, und eine Datei mit einem negativen Wert;
  • Zeilen 98–112: der Test für das Lesen der Steuerzahlerdaten. Die Datei [taxpayersdata.txt] aus Version 4 enthält 11 korrekte und 2 fehlerhafte Zeilen. Wir prüfen die Anzahl der abgerufenen Steuerzahler, ihren Typ ([assertContainsOnlyInstancesOf]), den Inhalt des ersten und des letzten Datensatzes und anschließend den Inhalt der Fehlerdatei. Um zwei Objekte [TaxPayerData] zu vergleichen, verwenden wir [assertEquals]: Zwei verschiedene Objekte sind nie identisch ([===]), aber sie sind gleich ([==]), wenn ihre Attribute gleich sind;
  • Zeilen 115–120: Eine nicht vorhandene Steuerzahlerdatei muss eine Ausnahme mit Code 12 auslösen.

11.7.4. Die Tests ausführen

Die Tests werden in einem im Ordner [php8-oct-2026] geöffneten Terminal ausgeführt, indem PHPUnit der Testordner übergeben wird:

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

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

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

Time: 00:00.020, Memory: 16.00 MB

OK (18 tests, 52 assertions)
  • Zeile 5: PHPUnit hat die Konfigurationsdatei [phpunit.xml] gefunden und verwendet;
  • Zeile 7: ein Punkt pro erfolgreichem Test. Die 18 Tests stammen aus den beiden Testklassen [DaoTest] und [BusinessTest] (Letztere wird im folgenden Absatz beschrieben): Ein Testlauf mit einem Data-Provider zählt so viele Tests, wie es Datensätze gibt;
  • Zeile 11: die Ergebnisse: Alle Tests wurden bestanden.

Die Option [--testdox] liefert eine aussagekräftigere Anzeige, in der jeder Test durch einen Satz aus dem Namen seiner Methode und dem Namen seines Datensatzes beschrieben wird:

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

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

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

Time: 00:00.006, Memory: 16.00 MB

Business (Application\Tests\Business)
 ✔ Calculate tax with data set "couple, 2 children, 55555"
 ✔ Calculate tax with data set "couple, 2 children, 50000"
 ✔ Calculate tax with data set "couple, 3 children, 50000"
 ✔ Calculate tax with data set "single, 2 children, 100000"
 ✔ Calculate tax with data set "single, 3 children, 100000"
 ✔ Calculate tax with data set "couple, 3 children, 100000"
 ✔ Calculate tax with data set "couple, 5 children, 100000"
 ✔ Calculate tax with data set "single, 0 children, 100000"
 ✔ Calculate tax with data set "couple, 2 children, 30000"
 ✔ Calculate tax with data set "single, 0 children, 200000"
 ✔ Calculate tax with data set "couple, 3 children, 200000"

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

OK (18 tests, 52 assertions)

Betrachten wir nun einen Test, der fehlschlägt. In der Klasse [BusinessTest] führen wir einen Fehler in die erwartete Ermäßigung für den zweiten Steuerzahler ein (346 statt 347). Die Ausführung der Tests liefert dann das folgende Ergebnis:

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

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

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

Time: 00:00.008, Memory: 16.00 MB

There was 1 failure:

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

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

FAILURES!
Tests: 18, Assertions: 52, Failures: 1.
  • Zeile 7: Der Buchstabe F (Failure) kennzeichnet den Test, der fehlgeschlagen ist;
  • Zeile 13: der fehlgeschlagene Test, zusammen mit dem Namen und dem Inhalt seines Datensatzes;
  • Zeilen 14–24: die fehlgeschlagene Zusicherung ([assertSame]) und der Unterschied zwischen dem erwarteten (-) und dem tatsächlichen (+) Array;
  • Zeile 26: die Datei und die Zeilennummer der fehlgeschlagenen Zusicherung;
  • Zeilen 28–29: die Zusammenfassung.

Wenn ein Test gar nicht erst läuft (zum Beispiel weil eine mit [require_once] geladene Datei nicht gefunden wird), zeigt PHPUnit den entsprechenden PHP-Fehler an, genau wie bei der Ausführung eines gewöhnlichen PHP-Skripts.

11.7.5. Tests der Schicht [business]

Die Testklasse [BusinessTest] folgt denselben Aufbauregeln wie die Klasse [DaoTest]: [Tests/BusinessTest.php]:

<?php

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

// Namespace der Tests
namespace Application\Tests;

// die getesteten Klassen
use Application\DaoTaxWithTaxAdminDataInJsonFile;
use Application\InterfaceBusiness;
use Application\Business;
// die PHPUnit-Klassen
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\TestCase;

// Laden der Klassen der Schichten [dao] und [business]
require_once __DIR__ . "/../TaxException.php";
require_once __DIR__ . "/../Utilities.php";
require_once __DIR__ . "/../TaxAdminData.php";
require_once __DIR__ . "/../TaxPayerData.php";
require_once __DIR__ . "/../InterfaceDao.php";
require_once __DIR__ . "/../TraitDao.php";
require_once __DIR__ . "/../DaoTaxWithTaxAdminDataInJsonFile.php";
require_once __DIR__ . "/../InterfaceBusiness.php";
require_once __DIR__ . "/../Business.php";

final class BusinessTest extends TestCase
{
    // der Ordner der Version 4
    private const string ROOT = __DIR__ . "/..";
    // die getestete Schicht [business]
    private InterfaceBusiness $business;

    // wird vor jedem Test ausgeführt
    #[\Override]
    protected function setUp(): void
    {
        // Erzeugung der Schicht [dao]
        $dao = new DaoTaxWithTaxAdminDataInJsonFile(self::ROOT . "/taxadmindata.json");
        // Erzeugung der Schicht [business]
        $this->business = new Business($dao);
    }

    // die Steuerpflichtigen der Tabelle mit den offiziellen Zahlen
    public static function taxpayers(): array
    {
        // [married, children, salary, offizielle Steuer, erwartete Ergebnisse des Algorithmus]
        return [
            "couple, 2 children, 55555" => ["yes", 2, 55555, 2815,
                ["tax" => 2814, "surcharge" => 0, "discount" => 0, "reduction" => 0, "rate" => 0.14]],
            "couple, 2 children, 50000" => ["yes", 2, 50000, 1385,
                ["tax" => 1384, "surcharge" => 0, "discount" => 384, "reduction" => 347, "rate" => 0.14]],
            "couple, 3 children, 50000" => ["yes", 3, 50000, 0,
                ["tax" => 0, "surcharge" => 0, "discount" => 720, "reduction" => 0, "rate" => 0.14]],
            "single, 2 children, 100000" => ["no", 2, 100000, 19884,
                ["tax" => 19884, "surcharge" => 4480, "discount" => 0, "reduction" => 0, "rate" => 0.41]],
            "single, 3 children, 100000" => ["no", 3, 100000, 16782,
                ["tax" => 16782, "surcharge" => 7176, "discount" => 0, "reduction" => 0, "rate" => 0.41]],
            "couple, 3 children, 100000" => ["yes", 3, 100000, 9200,
                ["tax" => 9200, "surcharge" => 2180, "discount" => 0, "reduction" => 0, "rate" => 0.3]],
            "couple, 5 children, 100000" => ["yes", 5, 100000, 4230,
                ["tax" => 4230, "surcharge" => 0, "discount" => 0, "reduction" => 0, "rate" => 0.14]],
            "single, 0 children, 100000" => ["no", 0, 100000, 22986,
                ["tax" => 22986, "surcharge" => 0, "discount" => 0, "reduction" => 0, "rate" => 0.41]],
            "couple, 2 children, 30000" => ["yes", 2, 30000, 0,
                ["tax" => 0, "surcharge" => 0, "discount" => 0, "reduction" => 0, "rate" => 0.0]],
            "single, 0 children, 200000" => ["no", 0, 200000, 64211,
                ["tax" => 64210, "surcharge" => 7498, "discount" => 0, "reduction" => 0, "rate" => 0.45]],
            "couple, 3 children, 200000" => ["yes", 3, 200000, 42843,
                ["tax" => 42842, "surcharge" => 17283, "discount" => 0, "reduction" => 0, "rate" => 0.41]],
        ];
    }

    // ein Test, der für jeden Steuerpflichtigen des Data Providers einmal ausgeführt wird
    #[DataProvider("taxpayers")]
    public function testCalculateTax(string $married, int $children, int $salary, int $officialTax, array $expected): void
    {
        // Steuerberechnung
        $result = $this->business->calculateTax($married, $children, $salary);
        // die Steuer entspricht der des offiziellen Simulators auf 1 Euro genau
        $this->assertEqualsWithDelta($officialTax, $result["tax"], 1);
        // die Ergebnisse sind exakt die erwarteten (gleiche Schlüssel, gleiche Werte, gleiche Typen)
        $this->assertSame($expected, $result);
    }
}

Kommentare

  • Zeilen 18–26: Laden der Dateien für die Schichten [dao] und [business]. Die Testumgebung ist dieselbe wie die von [main.php];
  • Zeilen 37–43: Instanziierung der Schichten [dao] und [business], wie in [main.php];
  • Zeilen 46–73: der Data-Provider: die elf Steuerzahler aus der Tabelle der offiziellen Zahlen. Jeder Datensatz enthält die Daten des Steuerzahlers, den Steuerbetrag, den der offizielle Simulator der Steuerverwaltung [https://www3.impots.gouv.fr/simulateur/calcul_impot/2019/simplifie/index.htm] liefert, und die erwarteten Ergebnisse des im Dokument beschriebenen Algorithmus;
  • Zeile 76: Die Methode [testCalculateTax] wird elfmal ausgeführt, einmal pro Steuerzahler. Der PHP-7-Kurs enthielt ursprünglich elf nahezu identische Testmethoden, von [test1] bis [test11]; der Data-Provider beseitigt diese Duplizierung;
  • Zeile 80: Die Steuerberechnung wird von der Schicht [business] durchgeführt;
  • Zeile 82: Wir prüfen, dass die berechnete Steuer bis auf 1 Euro mit dem Ergebnis des offiziellen Simulators übereinstimmt. Wir haben gesehen, dass Rundungsprobleme dazu führten, dass der Algorithmus des Dokuments Ergebnisse lieferte, die um bis zu 1 Euro von den offiziellen abwichen;
  • Zeile 84: Wir prüfen, dass die Ergebnistabelle [tax, surcharge, discount, reduction, rate] exakt dem Erwarteten entspricht, einschließlich der Datentypen: ganze Zahlen für die Beträge, eine reelle Zahl für den Satz. Deshalb ist der Satz für den 9. Steuerzahler als 0.0 und nicht als 0 geschrieben. Diese genaue Prüfung schützt vor unbeabsichtigten Änderungen am Algorithmus in künftigen Versionen.

Die Ergebnisse der Ausführung dieser Tests sind die im vorherigen Absatz gezeigten: Alle 11 Tests der Schicht [business] werden bestanden.

11.7.6. PHPUnit in VS Code

Der einfachste Weg, die Tests in [VS Code] auszuführen, ist das integrierte Terminal (Menü Terminal / Neues Terminal): Es öffnet sich im Ordner [php8-oct-2026] des Projekts, und Sie geben dort den Befehl [php vendor/bin/phpunit scripts-console/tax/version-04/Tests] ein. Mit der Pfeil-nach-oben-Taste rufen Sie den letzten Befehl wieder auf: Die Tests nach einer Codeänderung erneut auszuführen, kostet nur einen Tastendruck.

Einige nützliche Optionen des Befehls [phpunit]:

  • [--testdox]: zeigt Tests als Sätze an;
  • [--filter testCalculateTax]: führt nur die Tests aus, deren Namen den angegebenen Text enthalten;
  • [--stop-on-failure]: stoppt beim ersten Fehlschlag.

Es gibt außerdem Erweiterungen für [VS Code] , die PHPUnit in den Test-Explorer des Editors integrieren (zum Beispiel die Erweiterung „PHPUnit Test Explorer“): Sie ermöglichen es, einen Test mit einem einzigen Klick auszuführen und die Ergebnisse neben dem Code anzuzeigen. Tatsächlich führen sie denselben Befehl [phpunit] aus, den wir im Terminal eingeben.

11.7.7. Tests für die kommenden Versionen

Künftig sind die Tests für die Schichten [dao] und [business] mit denen von Version 4 identisch. Das Einzige, was sich ändert, ist die Testumgebung: die geladenen Dateien und die Art, wie die Schichten [dao] und [business] aufgebaut werden. Wir stellen deshalb nur diese und die Testergebnisse vor.