Initial xentral_oss_20.3.c9ffacf

classes/Components/HttpClient/docs/index.md

@@ -0,0 +1,126 @@
+# HTTP-Client
+
+## Neue HttpClient-Instanz erzeugen
+
+```php
+/** @var \Xentral\Components\HttpClient\HttpClientFactory $factory */
+$factory = $container->get('HttpClientFactory');
+$client = $factory->createClient();
+```
+
+## Requests abschicken
+
+```php
+/** @var \Xentral\Components\HttpClient\HttpClientFactory $factory */
+/** @var \Xentral\Components\HttpClient\HttpClientInterface $client */
+$client = $factory->createClient();
+
+$uri = 'https://httpbin.org/json';
+$headers = ['Accept' => 'application/json'];
+$request = new \Xentral\Components\HttpClient\Request\ClientRequest('GET', $uri, $headers);
+
+try {
+    /** @var \Xentral\Components\HttpClient\Response\ServerResponseInterface $response */
+    $response = $client->sendRequest($request);
+} catch (\Xentral\Components\HttpClient\Exception\TransferErrorExceptionInterface $exception) {
+    $request = $exception->getRequest();
+    $response = $exception->hasResponse() ? $exception->getResponse() : null;
+    // ...
+}
+```
+
+## Request-Optionen
+
+Mit den Request-Optionen kann das Standard-Verhalten des Http-Clients beeinflusst werden.
+
+### Standard-Optionen
+
+* Timeout: 0 Sekunden (kein Timeout)
+* Umleitungen folgen: Maximal fünf Redirects
+* Streaming-Verhalten: Deaktiviert (alles am Stück downloaden)
+* SSL-Zertifikatsverifizierung: Aktiv
+* HTTP-Protokollversion: 1.1
+
+### Request-Optionen übergeben
+
+Es gibt zwei Möglichkeiten Request-Optionen zu übergeben:
+1. Beim Erzeugen der HttpClient-Instanz (`HttpClientFactory::createClient($options)`)
+    * Die Optionen gelten dann für alle Requests dieser Instanz.
+2. Beim Abschicken eines Requests (`HttpClient::sendRequest($request, $options)`)
+    * Die Optionen werden nur für diesen Request angewendet.
+
+Wenn an beiden Stellen Optionen übergeben werden, werden die Optionen zusammengefasst. Bei Konflikten haben die 
+Optionen Vorrang die beim Abschicken des Request übergeben werden (2. Möglichkeit).   
+
+### Beispiele
+
+```php
+$options = new \Xentral\Components\HttpClient\RequestOptions();
+$options->setTimeout(5); // Maximal fünf Sekunden auf eine Antwort warten 
+$options->disallowRedirects(); // Keinen Umleitungen folgen
+$options->setAuthDigest('username', 'password'); // Per DigestAuth authentifizieren
+$options->setHeader('Accept', ['text/html', 'text/plain']); // Accept-Header setzen
+```
+
+#### Große Dateien downloaden
+
+Für den Download von großen Dateien empfiehlt es sich die `setStorageLocation()`-Option zu verwenden.
+Die Methode nimmt entweder einen Dateipfad oder ein `resource`-Objekt als Parameter entgegen.
+
+Der Vorteil dieser Option besteht darin, dass der Response-Body direkt in eine Datei gestreamt wird.
+Das führt zu einem sehr geringen Arbeitsspeicherbedarf.
+
+```php
+$options = new \Xentral\Components\HttpClient\RequestOptions();
+$options->setStorageLocation('/tmp/large_file');
+
+$response = $client->sendRequest($request, $options);
+```
+
+## Fehlerbehandlung
+
+Im Fehlerfall wird standardmäßig eine Exception geworfen. Alle Exceptions implementieren 
+`\Xentral\Components\HttpClient\Exception\HttpClientExceptionInterface`.
+
+Desweiteren gibt es spezielle Exceptions die bei HTTP-Protokollfehlern geworfen werden. Diese sind 
+alle von `\Xentral\Components\HttpClient\Exception\TransferErrorException` abgeleitet.
+
+### Transfer-Fehler
+
+* Verbindungsaufbau ist fehlgeschlagen
+    * Mögliche Ursachen: Gegenstelle ist nicht vorhanden (URL falsch/fehlerhaft), Gegenstelle momentan nicht 
+      erreichbar, Routing-Fehler
+    * Klasse: `\Xentral\Components\HttpClient\Exception\ConnectionFailedException`
+
+* HTTP-Client-Fehler (HTTP-Status 4xx)
+    * Die Ursache des Scheiterns liegt eher im Verantwortungsbereich des HTTP-Clients.
+    * Beispiel: Zugriff auf Resource ist nicht erlaubt (HTTP-Status 403)
+    * Klasse: `\Xentral\Components\HttpClient\Exception\ClientErrorException`
+
+* HTTP-Server-Fehler (HTTP-Status 5xx)
+    * Die Ursache des Scheiterns liegt eher im Verantwortungsbereich der Gegenstelle (Server).
+    * Beispiel: Internal Server Error (HTTP-Status 500)
+    * Klasse: `\Xentral\Components\HttpClient\Exception\ServerErrorException`
+
+* Zu viele Umleitungen
+    * In der Standard-Einstellung sind fünf Weiterleitungen erlaubt. Wird diese Zahl überschritten wird die 
+    `TooManyRedirectsException` geworfen. In den Request-Optionen lässt sich die Anzahl der maximal erlaubten 
+    Weiterleitungen festlegen. 
+    * Klasse: `\Xentral\Components\HttpClient\Exception\TooManyRedirectsException`
+
+
+### Transfer-Fehler-Exceptions deaktivieren
+
+Über die Request-Optionen können Exceptions für HTTP-Protokollfehler deaktiviert werden. 
+
+```php
+$options = new \Xentral\Components\HttpClient\RequestOptions();
+$options->disableHttpErrorExceptions();
+
+/** @var \Xentral\Components\HttpClient\HttpClientFactory $factory */
+$factory = $container->get('HttpClientFactory');
+$client = $factory->createClient($options);
+
+$response = $client->request('GET', 'http://not_existing');
+echo $response->getStatusCode(); // Ausgabe: 404
+```