Skip to content

22. Praktische Übung – Version 11

Es ist nach wie vor üblich, dass Webservices ihre Antwort als XML-Dokument statt als JSON-Dokument senden:

  • Das JSON-Dokument ist kleiner, aber man braucht Anweisungen, um es zu verstehen;
  • Das XML-Dokument ist ausführlicher, aber selbstbeschreibend. Es ist sofort verständlich.

Wir ändern die Client-Server-Anwendung aus Version 10 so, dass der Server seinen Clients nun ein XML-Dokument als Antwort sendet. Damit setzen wir das vorherige Kapitel in die Praxis um.

22.1. Der Server

Image

Diese Architektur wird durch die folgenden Dateien umgesetzt:

1
2
3
4
5
6
7
8
9
scripts-web/tax/version-11
├── Data
│   ├── .htaccess
│   ├── config-server.json
│   └── logs.txt
├── Utilities
│   ├── XmlUtilities.php
│   └── testXml.php
└── tax-server.php

22.1.1. Die Klasse [XmlUtilities]

Der PHP-7-Kurs fügte der Klasse [getXmlForArrayOfAttributes], die Methode [Utilities] hinzu, die das XML-Dokument aus einem Array erzeugte. Unser Server verwendet bereits die Klasse [Utilities] aus Version 5 (für die Klasse [Database]): Wir erstellen eine neue Klasse [XmlUtilities]:

<?php

declare(strict_types=1);

// Namespace
namespace Application;

// Hilfsfunktionen für das XML-Format: die Klasse kann weder instanziiert noch abgeleitet werden
final class XmlUtilities
{
    // privater Konstruktor: die Klasse kann nicht instanziiert werden
    private function __construct()
    {
    }

    // gibt das XML-Dokument eines Arrays [$data] zurück: das Wurzelelement heißt [$root]
    // die Schlüssel des Arrays werden zu Elementnamen, die Werte zu deren Inhalt
    public static function arrayToXml(array $data, string $root): string
    {
        // ein leeres XML-Dokument (neue DOM-API von PHP 8.4)
        $document = \Dom\XMLDocument::createEmpty();
        // das Dokument wird eingerückt
        $document->formatOutput = true;
        // das Wurzelelement und seine Nachkommen
        $document->append(self::element($document, $root, $data));
        // der XML-Text des Dokuments
        return $document->saveXml();
    }

    // gibt das XML-Element [<$name>$value</$name>] zurück
    private static function element(\Dom\XMLDocument $document, string $name, mixed $value): \Dom\Element
    {
        $element = $document->createElement($name);
        if (is_array($value)) {
            // ein Array: jedes Element des Arrays wird zu einem Kindelement (rekursiver Aufruf)
            foreach ($value as $key => $subValue) {
                // die Elemente einer Liste (Schlüssel 0, 1, 2...) heißen [item]
                $element->append(self::element($document, is_int($key) ? "item" : $key, $subValue));
            }
        } else {
            // ein einfacher Wert wird zum Text des Elements (die Zeichen <, >, & werden von DOM codiert)
            $element->textContent = match (true) {
                is_bool($value) => $value ? "true" : "false",
                default => (string) $value,
            };
        }
        return $element;
    }
}

Anmerkungen

  • Zeile 9: Wie die Klasse [Utilities] in Version 5 hat diese Klasse nur statische Methoden. Sie ist [final], und ihr Konstruktor ist privat: Sie kann weder abgeleitet noch instanziiert werden;
  • Zeile 18: Die statische Methode [arrayToXml] gibt das XML-Dokument aus dem als Parameter übergebenen Array [$data] zurück. Der zweite Parameter ist der Name des Wurzelelements des Dokuments;
  • Zeile 21: Wir verwenden die neue DOM-API aus PHP 8.4, die im vorherigen Kapitel vorgestellt wurde. Die statische Methode [createEmpty] erzeugt ein leeres XML-Dokument. Das PHP-7-Skript verwendete [SimpleXML], das ebenfalls ein Dokument erzeugen kann, jedoch nicht so gut: Die Sonderzeichen im Text mussten Sie selbst mit der Funktion [htmlspecialchars] codieren;
  • Zeile 23: Das entstehende Dokument wird eingerückt, was es besser lesbar macht;
  • Zeile 25: Das Wurzelelement des Dokuments, das mit der Methode [element] erzeugt wird, wird dem Dokument hinzugefügt;
  • Zeile 27: Die Methode [saveXml] liefert den XML-Text des Dokuments;
  • Zeile 31: Die private Methode [element] gibt das XML-Element mit dem Namen [$name] zurück, das den Wert [$value] darstellt;
  • Zeile 33: Die Methode [createElement] des Dokuments erzeugt das Element;
  • Zeilen 34–38: Ist der Wert ein Array, wird jedes seiner Elemente zu einem Kindelement, das durch einen rekursiven Aufruf der Methode [element] erzeugt wird. Die Schlüssel des Arrays werden zu den Namen der Kindelemente. Die Schlüssel einer Liste sind die ganzen Zahlen 0, 1, 2 ..., die keine gültigen XML-Elementnamen sind: Diese Elemente heißen deshalb [item]. Das PHP-7-Skript nannte sie [i0], [i1], [i2] ...;
  • Zeilen 40–45: Andernfalls wird der Wert zum Text des Elements und seiner Eigenschaft [textContent] zugewiesen. Die Zeichen [<], [>], und [&] im Text werden von DOM codiert ([&lt;], [&gt;], [&amp;]). Boolesche Werte werden als [true] und [false] geschrieben; andere Werte werden in Strings umgewandelt. Der Ausdruck [match (true)] wählt den ersten Zweig, dessen Bedingung wahr ist.

Wir schreiben das folgende Testskript [testXml.php]:

<?php

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

// Abhängigkeit
require_once __DIR__ . "/XmlUtilities.php";

use Application\XmlUtilities;

// ein assoziatives Array
$array = [
    "lastName" => "amédée",
    "firstName" => "sylvain",
    "age" => 40,
    "children" => [
        ["lastName" => "amédée", "firstName" => "béatrice", "age" => 6],
        ["lastName" => "amédée", "firstName" => "bertrand", "age" => 4],
    ],
    "remark" => "<married> & happy",
];
// die Antwort ist ein XML-Dokument
header("Content-Type: application/xml; charset=utf-8");
print XmlUtilities::arrayToXml($array, "person");
  • Zeilen 12–21: ein assoziatives Array mit einer Liste und einem Text mit XML-Sonderzeichen;
  • Zeile 23: Die Funktion [header] setzt den HTTP-Header [Content-Type] der Antwort: Es handelt sich um ein XML-Dokument;
  • Zeile 24: Das XML-Dokument des Arrays mit dem Wurzelelement [person] wird an den Client gesendet.

Rufen wir die URL [http://localhost/php8-oct-2026/scripts-web/tax/version-11/Utilities/testXml.php] mit [curl] auf:

> curl http://localhost/php8-oct-2026/scripts-web/tax/version-11/Utilities/testXml.php
<?xml version="1.0" encoding="UTF-8"?>
<person>
  <lastName>amédée</lastName>
  <firstName>sylvain</firstName>
  <age>40</age>
  <children>
    <item>
      <lastName>amédée</lastName>
      <firstName>béatrice</firstName>
      <age>6</age>
    </item>
    <item>
      <lastName>amédée</lastName>
      <firstName>bertrand</firstName>
      <age>4</age>
    </item>
  </children>
  <remark>&lt;married&gt; &amp; happy</remark>
</person>
  • Zeilen 7–18: die Liste [children] und ihre beiden Elemente [item];
  • Zeile 19: Die Zeichen [<], [>], und [&] wurden codiert.

Ein Browser zeigt dasselbe Dokument in Baumform an:

Image

Beachten Sie, dass [Chrome] den Text des Elements [remark] dekodiert hat.

22.1.2. Das serverseitige Skript

Das serverseitige Skript [tax-server.php] muss zusammen mit seiner Konfigurationsdatei [config-server.json] angepasst werden:

{
    "databaseFilename": "../version-08/Data/database-mysql.json",
    "dependencies": [
        "../../../scripts-console/tax/version-05/Entities/TaxException.php",
        "../../../scripts-console/tax/version-05/Entities/TaxAdminData.php",
        "../../../scripts-console/tax/version-05/Entities/Database.php",
        "../../../scripts-console/tax/version-05/Utilities/Utilities.php",
        "../version-08/Dao/InterfaceServerDao.php",
        "../version-08/Dao/ServerDao.php",
        "../version-09/Dao/ServerDaoWithSession.php",
        "../version-08/Business/InterfaceServerBusiness.php",
        "../version-08/Business/ServerBusiness.php",
        "../version-09/Utilities/Logger.php",
        "../version-09/Utilities/SendAdminMail.php",
        "Utilities/XmlUtilities.php"
    ],
  • Zeile 15: Die neue Klasse [XmlUtilities] wird eingebunden. Die übrige Konfiguration entspricht der von Version 10.

Die Änderungen am Serverskript sehen wie folgt aus:

}

// Senden der HTTP-Antwort an den Client
// $result: das zu sendende Array in Form des XML-Dokuments <response>...</response>
// $statusCode: der HTTP-Status der Antwort
// $headers: der Antwort hinzuzufügende HTTP-Header
// $logger: das Log der Anwendung (null, wenn es nicht erstellt werden konnte)
// $redis: der Redis-Client (null, wenn er noch nicht erstellt wurde)
function sendResponse(
    array $result,
    int $statusCode,
    array $headers = [],
    ?Logger $logger = null,
    ?RedisClient $redis = null
): void {
    // die XML-Antwort
    $response = new Response(XmlUtilities::arrayToXml($result, "response"), $statusCode, $headers);
    $response->headers->set("Content-Type", "application/xml; charset=utf-8");
    // Senden
    $response->send();
    // Log in JSON, kompakter als XML
    $logger?->write(json_encode(
        ["response" => $result],
        JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_PRESERVE_ZERO_FRACTION
    ));
    // Schließen der Verbindung zum Redis-Server
    $redis?->disconnect();
}

Anmerkungen

  • Die Klasse [JsonResponse] wird nicht mehr verwendet: Die Antwort ist eine einfache [Response]-Antwort;
  • Zeile 212: Die Serverantwort ist nun das XML-Dokument mit dem Wurzelelement [response] aus dem Array [$result];
  • Zeile 213: Es wird angegeben, dass die Antwort ein XML-Dokument in UTF-8-Codierung ist;
  • Zeilen 217–220: Die Antwort wird als JSON protokolliert, das kompakter ist als XML.

Der Rest des Skripts bleibt unverändert. Da alle Antworten über die Funktion [sendResponse] laufen, genügt es, diese Funktion zu ändern, damit alle Antworten – auch die Fehlerantworten – XML-Dokumente sind.

Test

Rufen wir die URL [http://localhost/php8-oct-2026/scripts-web/tax/version-11/tax-server.php?married=yes&children=2&salary=60000], mit [curl] auf:

> curl -i -u admin:admin "http://localhost/php8-oct-2026/scripts-web/tax/version-11/tax-server.php?married=yes&children=2&salary=60000"
HTTP/1.0 200 OK
Date: Fri, 02 Oct 2026 12:29:50 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: PHPSESSID=cdcb082d1342f5b0a273f76a30f92fc6; path=/
Cache-Control: no-cache, private
Vary: Accept-Encoding
Connection: close
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <tax>3375</tax>
  <surcharge>0</surcharge>
  <discount>0</discount>
  <reduction>0</reduction>
  <rate>0.14</rate>
</response>
  • Zeile 7: das Session-Cookie, das der Server bei der ersten Anfrage sendet;
  • Zeile 11: der Typ des gesendeten Dokuments;
  • Zeilen 13–20: Das XML-Dokument der Antwort.

In einem Browser erhält man nach der Authentifizierung das folgende Ergebnis:

Image

Auch Fehlerantworten sind XML-Dokumente. Eine Anfrage mit falschen Parametern:

1
2
3
4
5
6
7
8
9
> curl -u admin:admin "http://localhost/php8-oct-2026/scripts-web/tax/version-11/tax-server.php?married=x&children=2"
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <errors>
    <item>GET method required with only the parameters [married, children, salary]</item>
    <item>invalid married parameter [x]</item>
    <item>missing salary parameter</item>
  </errors>
</response>

Eine Anfrage eines unbekannten Benutzers:

1
2
3
4
5
> curl -u x:x "http://localhost/php8-oct-2026/scripts-web/tax/version-11/tax-server.php"
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <error>Authentication failed [x]</error>
</response>

22.2. Der Client

Wir konzentrieren uns nun auf die Client-Seite der Anwendung.

Image

Diese Architektur wird durch die folgenden Dateien umgesetzt:

scripts-console/tax/version-11
├── Dao
│   └── ClientDao.php
├── Data
│   ├── config-client-ko.json
│   ├── config-client.json
│   ├── errors.json
│   ├── results.json
│   └── taxpayersdata.json
├── Main
│   └── MainTaxClient.php
└── Tests
    └── ClientBusinessTest.php

In der neuen Version ändert sich nur Folgendes:

  • die Konfigurationsdatei [config-client.json];
  • die Clientschicht [dao].

Die Konfigurationsdatei [config-client.json] sieht nun wie folgt aus:

{
    "urlServer": "http://localhost/php8-oct-2026/scripts-web/tax/version-11/tax-server.php",
    "user": {
        "login": "admin",
        "passwd": "admin"
    },
    "httpClientOptions": {
        "verify_peer": false,
        "verify_host": false
    },
    "taxPayersDataFilename": "Data/taxpayersdata.json",
    "resultsFilename": "Data/results.json",
    "errorsFilename": "Data/errors.json",
    "dependencies": [
        "../version-05/Entities/TaxException.php",
        "../version-05/Entities/TaxPayerData.php",
        "../version-05/Utilities/Utilities.php",
        "../version-05/Dao/TraitDao.php",
        "../version-08/Dao/InterfaceClientDao.php",
        "Dao/ClientDao.php",
        "../version-08/Business/InterfaceClientBusiness.php",
        "../version-08/Business/ClientBusiness.php"
    ]
}
  • Zeile 2: die URL des Servers von Version 11;
  • Zeile 20: die neue Clientschicht [dao].

22.2.1. Die Schicht [dao]

Die Klasse [ClientDao] aus Version 9 wird angepasst, um das neue Antwortformat zu berücksichtigen. Zur Verarbeitung dieser Antwort wird [SimpleXML] verwendet:

        try {
            // wir stellen die Anfrage an den Server
            $response = $this->httpClient->request("GET", $this->urlServer, $options);
            // der Status, die Header und das XML-Dokument der Antwort, auch im Fehlerfall (Parameter false)
            $statusCode = $response->getStatusCode();
            $headers = $response->getHeaders(false);
            $content = $response->getContent(false);
        } catch (ExceptionInterface $ex) {
            // der Server war nicht erreichbar
            throw new TaxException("Error communicating with the server ({$ex->getMessage()})", 40, $ex);
        }
        // Logs
        // print "$content\n";
        // der Server sendet das XML-Dokument <response>...</response>
        // die Optionen LIBXML_NOERROR und LIBXML_NOWARNING vermeiden PHP-Warnungen bei ungültigem XML
        $xml = simplexml_load_string($content, options: LIBXML_NOERROR | LIBXML_NOWARNING);
        if ($xml === false || $xml->getName() !== "response") {
            throw new TaxException("Invalid server response [$content]", 41);
        }
        // Fehler?
        if ($statusCode !== 200) {
            // wir werfen eine Exception, deren Nachricht die in JSON umgewandelte Antwort des Servers ist (kompakter),
            // ergänzt um ihren HTTP-Status
            $serverResponse = json_decode(json_encode($xml, JSON_THROW_ON_ERROR), true, flags: JSON_THROW_ON_ERROR);
            $message = json_encode(
                ["HTTP status" => $statusCode] + $serverResponse,
                JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR
            );
            throw new TaxException($message, 42);
        }
        // wir rufen das Session-Cookie ab, falls es noch nicht bekannt ist
        if ($this->sessionCookie === null) {
            foreach ($headers["set-cookie"] ?? [] as $cookie) {
                if (preg_match('/^PHPSESSID=(.+?);/', $cookie, $fields) === 1) {
                    $this->sessionCookie = "PHPSESSID=$fields[1]";
                }
            }
        }
        // wir geben die Antwort zurück: das Array [tax, surcharge, discount, reduction, rate]
        // im XML-Dokument sind alle Werte Texte: wir wandeln sie in ihren Typ um
        return [
            "tax" => (int) $xml->tax,
            "surcharge" => (int) $xml->surcharge,
            "discount" => (int) $xml->discount,
            "reduction" => (int) $xml->reduction,
            "rate" => (float) $xml->rate,
        ];
    }
}

Anmerkungen

  • Zeile 63: Die Antwort des Servers wird gelesen. Es ist ein XML-Dokument [<response>…</response>];
  • Zeile 72: Die Funktion [simplexml_load_string] parst das empfangene XML-Dokument und gibt ein Objekt [SimpleXMLElement] zurück, das sein Wurzelelement darstellt, oder [false] , wenn das Dokument kein gültiges XML-Dokument ist. Standardmäßig meldet die Bibliothek [libxml], die von [SimpleXML] verwendet wird, Dokumentfehler auch als PHP-Warnungen: Die Optionen [LIBXML_NOERROR] und [LIBXML_NOWARNING] unterdrücken sie. Sie werden über das benannte Argument [options] übergeben, wodurch man den Parameter [class_name] , der in der Signatur der Funktion davor steht, nicht schreiben muss;
  • Zeile 73: Die Methode [getName] gibt den Namen des Wurzelelements zurück, der [response] lauten muss;
  • Zeilen 77–85: Im Fehlerfall ist die Meldung der Ausnahme der JSON-String der Serverantwort statt des empfangenen XML-Strings, weil der JSON-String kompakter ist. Um das assoziative Array der XML-Antwort zu erhalten, verwenden wir einen klassischen Trick: Die Funktion [json_encode] kann ein Objekt [SimpleXMLElement] in JSON umwandeln, und [json_decode] wandelt dieses JSON anschließend in ein Array um. Die Meldung der Ausnahme hat so dasselbe Format wie in den vorherigen Versionen;
  • Zeilen 97–103: Das Ergebnis-Array wird zurückgegeben. Auf die Kindelemente des Elements [response] wird wie auf Eigenschaften des Objekts [$xml] zugegriffen ([$xml->tax]). In einem XML-Dokument sind alle Werte Text: Anders als JSON unterscheidet XML nicht zwischen ganzen Zahlen, reellen Zahlen und Zeichenketten. Jeder Wert wird daher in den von der Schicht [business] erwarteten Typ umgewandelt, und zwar mit den Operatoren [(int)] und [(float)] . Der PHP-7-Client gab die Werte als Strings zurück.

Test

Wenn Sie den Client in einer korrekt konfigurierten Umgebung (Datenbank, Authentifizierung, Logs, Redis) ausführen, erhalten Sie die gewohnten Ergebnisse:

1
2
3
> php MainTaxClient.php
The results have been saved in the file [Data/results.json]
Done

Prüfen Sie die Dateien im Ordner [taxpayersdata.json, results.json, errors.json]: Die Datei [results.json] ist mit der aus den vorherigen Versionen identisch. Auf der Serverseite sehen die Logs wie folgt aus:

01/10/26 18:12:15.370 : ---new request
01/10/26 18:12:15.370 : Authentication in progress…
01/10/26 18:12:15.370 : Authentication successful [admin]
01/10/26 18:12:15.370 : valid parameters ['married'=>yes, 'children'=>2, 'salary'=>55555]
01/10/26 18:12:15.371 : tax data taken from the database
01/10/26 18:12:15.373 : {"response":{"tax":2814,"surcharge":0,"discount":0,"reduction":0,"rate":0.14}}
01/10/26 18:12:15.376 : ---new request
01/10/26 18:12:15.376 : Authentication taken from the session…
01/10/26 18:12:15.376 : valid parameters ['married'=>yes, 'children'=>2, 'salary'=>50000]
01/10/26 18:12:15.377 : tax data taken from Redis
01/10/26 18:12:15.377 : {"response":{"tax":1384,"surcharge":0,"discount":384,"reduction":347,"rate":0.14}}
…

Mit der Konfigurationsdatei [config-client-ko.json] (unbekannter Benutzer) lautet die Ausgabe:

1
2
3
> php MainTaxClient.php config-client-ko.json
Error no. 42: {"HTTP status":401,"error":"Authentication failed [x]"}
Done

Die Fehlermeldung hat dasselbe Format wie in den vorherigen Versionen, obwohl der Server mit einem XML-Dokument geantwortet hat.

22.2.2. [PHPUnit]-Tests

Der Test [Tests/ClientBusinessTest.php] gilt für Version 10, während die Testumgebung die des Clients der Version 11 ist. Die Ergebnisse lauten wie folgt:

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

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

...........                                                       11 / 11 (100%)

Time: 00:00.073, Memory: 16.00 MB

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

OK (11 tests, 22 assertions)

Die Tests bestehen mit der Prüfung [assertSame]: Die von der [dao]-Schicht zurückgegebenen Werte haben tatsächlich die erwarteten Typen, dank der Konvertierungen, die nach dem Lesen des XML-Dokuments durchgeführt werden.