Initial xentral_oss_20.3.c9ffacf

classes/Components/Http/docs/request.md

@@ -0,0 +1,223 @@
+# Http-Komponente
+
+Die Http-Komponente ist eine objektorientierte Abstraction der HTTP-Spezifikation.
+
+## Request-Klasse
+
+Die Request-Klasse beinhaltet `$_GET`, `$_POST`, `$_FILES`, `$_COOKIE` (todo), und `$_SERVER`.
+
+### Request erstellen
+
+```php
+$request = Request::createFromGlobals();
+```
+
+ist das gleiche wie
+
+```php
+$request = new Request(
+    $_GET,
+    $_POST,
+    $_FILES,
+    $_SERVER
+    $_COOKIE,
+);
+```
+
+createFromGlobals ist die empfohlene Methode
+
+##### Request aus Container holen
+
+```php
+$request = $container->get('Request');
+```
+
+Im alten Bereich:
+
+```php
+$request = $this->app->Container->get('Request');
+```
+
+### Request-Parameter abrufen
+
+* `$request->getGet()` für den Zugriff auf `$_GET`
+* `$request->getPost()` für den Zugriff auf `$_POST`
+* `$request->getFiles()` für den Zugriff auf `$_FILES`
+* `$request->getServer()` für den Zugriff auf `$_SERVER`
+* `$request->getCookie()` für den Zugriff auf `$_COOKIE` (TODO)
+
+###### Beispiele
+
+* `$request->getGet('value')` wie `$_GET['value']`  
+* `$request->getPost('value')` wie `$_POST['value']`
+* `$request->getServer('SERVER_NAME')` wie `$_SERVER['SERVER_NAME']`
+
+#### ReadonlyParameterCollection
+
+Die public Eigenschaften `get`, `post`, `files` und `server` liefern Instanzen der `ReadonlyParameterCollection`-Klasse.
+Die Klasse bietet einige Hilfsmethoden:
+
+* `has()` – Gibt `true` zurück wenn der Parameter gesetzt wurde
+* `get()` – Gibt den Parameter zurück falls dieser gesetzt wurde; andernfalls `null`
+* `all()` – Gibt alle gesetzten Parameter zurück
+
+
+* `getBool()` – Wandelt den Wert zu Boolean
+* `getInt()` – Wandelt den Wert zu Integer
+* `getDigits()` – Wandelt den Wert zu String und entfernt alle Zeichen außer Zahlen `[0-9]`
+* `getAlpha()` – Wandelt den Wert zu String und entfernt alle Zeichen außer Buchstaben `[a-z, A-Z]`
+* `getAlphaNum()` – wie `getAlpha()` zusätzlich Zahlen `[a-z, A-Z, 0-9]`
+* `getAlphaNumWithDashes()` – wie `getAlphaDigit()` zusätzlich Minus und Unterstrich `[a-z, A-Z, 0-9, -, _]`
+
+##### Default-Werte
+
+Die Getter-Methoden der `ParameterCollection` nehmen als zweiten Parameter einen Default-Wert entgegen.
+Der Default-Wert wird verwendet wenn der Parameter nicht gesetzt ist.
+
+###### Beispiele
+
+* `$request->post->get('cmd', 'download')`  
+	Gibt `'download'` zurück, falls `$_POST['cmd']'` nicht gesetzt ist.
+* `$request->post->getBool('active', true)`  
+  Gibt `true` zurück, falls `$_POST['active']'` nicht gesetzt ist. 
+
+### Nützliches
+
+Nachfolgende Beispielausgaben gehen von folgendem Request aus:
+
+```http request
+POST /wawision-19.1/www/index.php?module=welcome&action=settings HTTP/1.1
+
+Host: 192.168.0.177
+User-Agent: Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:64.0) Gecko/20100101 Firefox/64.0
+Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
+Accept-Language: de-DE,de;q=0.8,en-US;q=0.5,en;q=0.3
+Accept-Encoding: gzip, deflate
+Referer: http://192.168.0.177/wawision-19.1/www/index.php?module=welcome&action=settings
+Content-Type: application/x-www-form-urlencoded
+Content-Length: 101
+Connection: keep-alive
+Cookie: PHPSESSID=19n48qro8d9blluqveg3dm1qth
+Upgrade-Insecure-Requests: 1
+
+startseite=&defaultcolor=%23FFFFFF&chat_popup=1&callcenter_notification=1&submit_startseite=Speichern
+```
+
+#### `$request->isSecure()`
+
+Kam der Request über eine geschützte Verbindung?
+
+Ausgabe: `false`
+
+#### `$request->isAjax()`
+
+Kam der Request über XHR?
+
+Ausgabe: `false`
+
+#### `$request->isCli()`
+
+Kam der Request über eine Kommandozeile?
+
+Ausgabe: `false`
+
+#### `$request->getMethod()`
+
+HTTP-Verb in Grossbuchstaben.
+
+Ausgabe: `POST`
+
+#### `$request->getContentType()`
+
+Der hintere Teil von Content-Type Header.
+
+Ausgabe: `x-www-form-urlencoded`
+
+Beispiele:
+* `json` bei `application/json`
+* `html` bei `text/html`
+
+#### `$request->getAcceptableContentTypes()`
+
+```php
+array (
+   0 => 'text/html',
+   1 => 'application/xhtml+xml',
+   2 => 'application/xml',
+   3 => '*/*',
+ )
+```
+
+#### `$request->getContent()`
+
+Gibt den Request-Body zurück.
+
+Ausgabe: `startseite=&defaultcolor=%23FFFFFF&chat_popup=1&callcenter_notification=1&submit_startseite=Speichern`
+
+#### `$request->getFullUri()`
+
+Nicht mehr benutzen; stattdessen getFullUrl oder getBaseUrl verwenden.
+
+`http://192.168.0.177/wawision-19.1/www/index.php?module=welcome&action=settings`
+
+#### `$request->getFullUrl()`
+
+Gibt die komplette Url zurück.
+
+Ausgabe: `http://192.168.0.177/wawision-19.1/www/index.php?module=welcome&action=settings`
+
+#### `$request->getBaseUrl()`
+
+Gibt die Url ohne GET parameter zurück.
+
+Ausgabe: `http://192.168.0.177/wawision-19.1/www/index.php`
+
+#### `$request->getUrlForPath('/mypath')`
+
+Gibt die URL um den angegebenen Pfad erweitert zurück.
+Der Pfad muss mit `/` beginnen.
+
+Ausgabe: `http://192.168.0.177/wawision-19.1/www/mypath`
+
+#### `$request->getBasePath()`
+
+Gibt den Pfad zwischen URL und aktuellen SCRIPT_NAME an.
+
+##### Beispiel1:
+
+```php
+$_SERVER[
+    'REQUEST_URI' => '/www/path/?value=1',
+    'SCRIPT_NAME' => '/www/path/index.php',
+]
+```
+
+Ausgabe: `/`
+
+##### Beispiel2:
+
+URL: 'http://192.168.0.177/wawision/www/api/v1/dateien/50' => '/v1/dateien/50'
+
+#### `$request->getRequestUri()`
+
+Gibt die relative Url ab dem Host zurück; wie `$_SERVER['REQUEST_URI']`
+
+Ausgabe: `/wawision-19.1/www/index.php?module=welcome&action=settings`
+
+#### `$request->isFailsafeUri()`
+
+Gibt `true` zurück, wenn die Failsafe-URI im Request benutzt wurde.
+
+Beispiel Failsafe-Uri: /api/index.php?path=/v1/adressen
+
+#### `$request->getPathInfo()`
+
+Gibt den PathInfo-Teil der Url zurück.
+
+Ausgabe: `''`
+
+#### `$request->getSchemeAndHttpHost()`
+
+Gibt HTTP Schema und Host aus.
+
+Ausgabe: `http://localhost`

classes/Components/Http/docs/response.md

@@ -0,0 +1,173 @@
+# Http-Response
+
+Die Response-Klassen dienen dazu eine gültige Response zu erstellen und an den Client zu senden.
+
+Für die unterschiedliche Response-Arten gibt es mehrere Klassen um die Anwendung zu erleichtern:
+
+* `Response` – Universelle Klasse
+* `FileResponse` – Zum Senden von Dateien
+* `JsonResponse` – Zum Senden von JSON-Inhalten (z.B. für AJAX-Requests)
+* `RedirectResponse` – Zum Umleiten des Clients auf eine andere URL
+
+## Response Klasse
+
+Die Klasse `Response` wird für alle Response-Arten benutzt, für die keine spezielle Klasse existiert. 
+
+#### Beispiel
+
+```php
+use Xentral\Components\Http\Response;
+
+$response = new Response('This is my response body.');
+$response->setContentType('text/html', 'utf-8');
+$response->addHeader('Cache-Control', 'no-cache');
+$response->send();
+```
+
+### Überblick
+
+1. Response erstellen
+2. Eigene Header anfügen oder überschreiben
+3. Response-Body setzen
+4. Response an Client senden
+
+### Response erstellen
+
+```php
+use Xentral\Components\Http\Response;
+
+$response = new Response(
+    'This is my response Content.',
+    Response::HTTP_CREATED,             //alle HTTP status Codes sind als Konstante verfügbar
+    ['Cache-Control' => ['no-cache']],
+    '1.0',
+    'Created'
+);
+```
+Erzeugt folgende Response:
+```http request
+HTTP/1.0 201 Created
+
+Cache-Control: no-cache
+Content-Type: text/html; charset=utf-8
+Content-Length: 28
+
+This is my response Content.
+```
+
+### Header hinzufügen/ändern
+
+#### `addHeader`
+
+Mit `addHeader('Header-Name', 'Value')` wird ein neuer Header bzw.
+ein weiterer Wert zu einem bestehenden Header hinzugefügt.
+
+**Hinweis:** Bei einigen Headern wie z.B. `Content-Type`, `Content-Length`, `Content-Disposition` und `Date` kann nur
+ein Wert zugewiesen werden. Bei der Übergabe von mehreren Werten wird ein `InvalidArgumentException` geworfen.
+
+#### `setHeader`
+
+Mit `setHeader('Header-Name', ['Value1', 'value2])` wird ein neuer Header gesetzt und dabei ein 
+bestehender Header überschrieben. Hier können mehrere Werte in einem `array` übergeben werden.
+
+### Response-Body setzen
+
+Mit `setContent('Mein Inhalt als String')` wird der Response-Body gesetzt.
+
+**Hinweis:** `setContent` berechnet und setzt zusätzlich den `Content-Length` Header. Wird `null` als Parameter
+übergeben, so wird der `Content-Length` Header entfernt.
+
+### Response an Client senden
+
+Mit `send()` wird die Response abgeschickt. Vor dem Senden wird die Response noch modifiziert:
+- Falls noch nicht vorhanden wird der `Date` Header gesetzt.
+- Falls der Response-Body `null` ist, werden der `Content-Type`- und `Content-Length` Header entfernt.
+
+
+## RedirectResponse Klasse
+
+Die RedirectResponse-Klasse vereinfacht das Umleiten auf andere Seiten.
+
+#### Beispiel
+
+```php
+use Xentral\Components\Http\Response;
+use Xentral\Components\Http\RedirectResponse;
+
+$redirect = RedirectResponse::createFromUrl('index.php?module=auftrag&action=list');
+$redirect->setStatusCode(Response::HTTP_MOVED_PERMANENTLY);
+$redirect->send();
+```
+
+Im Beispiel wird der Statuscode geändert. Per default ist `302 Found` als HTTP Status gesetzt.
+
+## JsonResponse Klasse
+
+Die JsonResponse Klasse vereinfacht das Erstellen von JSON-formatierten Antworten.
+
+#### Beispiel
+
+```php
+use Xentral\Components\Http\JsonResponse;
+
+$data = [
+    'data' => [
+        'id'   => '1234',
+        'typ'  => 'herr',
+        'name' => 'Max Mustermann',
+    ]
+];
+
+$response = new JsonResponse($data);
+```
+
+Erzeugt folgende Response:
+
+```http request
+HTTP/1.1 200 OK
+
+Content-Type: application/json; charset=utf-8
+Content-Length: 59
+
+{"data":{"id":"1234","typ":"herr","name":"Max Mustermann"}}
+```
+
+Als FileResponse kann ein `array` oder ein `JsonSerializable`-Objekt übergeben werden.
+
+## FileResponse Klasse
+
+Die FileResponse Klasse vereinfacht das Erstellen von Datei-Downloads.
+
+### `FileResponse::createFromFile()`
+
+Im folgenden Beispiel enthält `/tmp/file.txt` den Text `Hallo Welt`.
+
+```php
+use Xentral\Components\Http\FileResponse;
+
+$fileResponse = FileResponse::createFromFile('/tmp/file.txt', 'download.txt');
+```
+
+Erzeugt folgende Response:
+
+```http request
+HTTP/1.1 200 OK
+
+Content-Disposition: attachment; filename*="download.txt"; filename="download.txt"
+Content-Type: text/plain; charset=utf-8
+Content-Length: 20
+
+Hallo Welt
+```
+
+Es wird versucht den Content-Type anhand des Mimetyps der Datei zu ermitteln. Falls die Erkennung fehlschlägt wird 
+der Content-Type auf `application/octet-stream` gesetzt. Der Content-Type kann mit `$response->setContentType()` 
+überschrieben werden.
+
+### `FileResponse::createForcedDownload()`
+
+Erzwingt den Download des Response-Contents. Das ist bei PDF's und Bildern besonders nützlich. 
+Diese werden im Browser oft im Viewer geöffnet anstatt heruntergeladen zu werden.
+
+`createForcedDownload` setzt den Content-Type `application/force-download`, dadurch erhält der User
+den "Speichern unter"-Dialog.

classes/Components/Http/docs/uploads.md

@@ -0,0 +1,182 @@
+# Http Dateiuploads
+
+In den Folgenden Beispielen wird gezeigt, wie man Http Datei Uploads realisieren und verarbeiten kann.
+
+## Einfacher Dateiupload
+
+### Frontend (HTML)
+
+Der Dateiupload nutzt im Frontend ein HTML-Formular.
+Wichtig: Parameter `enctype="multipart/form-data` muss gesetzt sein.
+
+```html
+<form action="?module=upload&action=upload" method="post" enctype="multipart/form-data">
+  <input name="file" type="file">
+  <input name="anotherfile" type="file">
+  <button type="submit">UPLOAD</button>
+</form>
+```
+
+### Verarbeitung in PHP
+
+Bei einem Dateiupload werden die Dateien von PHP vor der Programmausführung entgegengenommen und in `/tmp` gespeichert.
+Zusätzlich werden die Informationen über den Upload in der `$_FILES` Variable gespeichert.
+
+`var_dump($_FILES)` erzeugt diesen Output:
+
+```php
+array (size=2)
+  'file' => 
+    array (size=5)
+      'name' => string 'my_uploaded_file.md' (length=19)
+      'type' => string 'text/markdown' (length=13)
+      'tmp_name' => string '/tmp/phphoXkRU' (length=14)
+      'error' => int 0
+      'size' => int 8972
+  'anotherfile' => 
+    array (size=5)
+      'name' => string 'my_other_file.txt.xml' (length=28)
+      'type' => string 'text/xml' (length=8)
+      'tmp_name' => string '/tmp/php2NqM0Z' (length=14)
+      'error' => int 0
+      'size' => int 9499
+```
+
+### Verarbeitung im Controller
+
+Auf die Uploadinfo kann man pro datei über die Request Klasse zugreifen:
+
+```php
+$request = $this->app->Container->get('Request');
+$fileUpload = $request->getFile('file');
+```
+
+`getFile` liefert eine Instanz von `FileUpload` zurück.
+
+#### Validierung
+
+Bevor der FileUpload weiterverwertet wird, sollte aus Sicherheitsgründen die Integrität des Uploads überprüft werden.
+Dafür stehen mehrere Methoden zur Verfügung:
+
+* `$fileUpload->isValid()` prüft, ob die Datei zu einem gültigen `POST` Upload gehört und sollte **immer** ausgeführt werden.
+* `$fileUpload->isFile()` prüft, ob die Datei im `/tmp` existiert.
+* `$fileUpload->isReadable()` prüft, ob die Datei gelesen werden kann.
+* `$fileUpload->hasError()` prüft, ob ein Http Error vorliegt.
+
+**Hinweis:** Wenn ein Http Fehler vorliegt, kann man den Grund dafür per `$fileUpload->getErrorMessage()` ermitteln
+und ggf. an den Client weitergeben. Liegt allerdings kein Fehler vor, führt diese Methode zu einer Exception!
+
+#### Speicherung
+
+Wenn ein Upload dauerhaft gespeichert werden soll, muss die Datei aus dem `/temp` an einen dauerhaften Speicherort
+verschoben werden:
+
+```php
+$fileUpload->move('/var/storage', 'upload.txt');
+```
+
+**Hinweis:** Wenn sich bereits eine Datei mit diesem Namen am Zielort befindet, wird eine Exception geworfen und die
+Datei wird **nicht** überschrieben oder anderweitig gespeichert.
+
+#### Zugriff
+
+Man kann auf zwei Arten auf den Inhalt des Uploads zugreifen:
+
+* `$fileUpload->getContent()` liefert den Inhalt als `string` zurück. (empfohlen für kleinere Dateien)
+* `$fileUpload->createContentStream()` liefert eine `resource`, aus der der Inhalt gestreamed werden kann. 
+
+**Tipp:** Mit `$fileUpload->getMimeType()` kann man vor dem Einlesen nocht prüfen, ob der User die Datei im
+richtigen Format (json, csv, xml usw.) hochgeladen hat.
+
+## Dateiupload in Array
+
+### Frontend (HTML)
+
+Für den Dateiupload können Dateien auch in zusammengehörigen Arrays hochgeladen werden.
+
+Beispiel: Upload einer eigenen Schriftart. Hier werden vier dateien hochgeladen, die aber semantisch zusammengehören.
+
+```html
+<form action="?module=upload&action=upload" method="post" enctype="multipart/form-data">
+  <input name="font[default]" type="file">
+  <input name="font[bold]" type="file">
+  <input name="font[italic]" type="file">
+  <input name="font[bolditalic]" type="file">
+  <button type="submit">UPLOAD</button>
+</form>
+```
+
+### Verarbeitung in PHP
+
+In diesem Fall wird die `$_FILES` Variable in einer anderen hierarchie aufgebaut:
+
+```php
+array (size=1)
+  'font' => 
+    array (size=5)
+      'name' => 
+        array (size=4)
+          'regular' => string 'LiberationMono-Regular.ttf' (length=26)
+          'bold' => string 'LiberationMono-Bold.ttf' (length=23)
+          'italic' => string 'LiberationMono-Italic.ttf' (length=25)
+          'bolditalic' => string 'LiberationMono-BoldItalic.ttf' (length=29)
+      'type' => 
+        array (size=4)
+          'regular' => string 'font/ttf' (length=8)
+          'bold' => string 'font/ttf' (length=8)
+          'italic' => string 'font/ttf' (length=8)
+          'bolditalic' => string 'font/ttf' (length=8)
+      'tmp_name' => 
+        array (size=4)
+          'regular' => string '/tmp/phpN3NU7D' (length=14)
+          'bold' => string '/tmp/phpKzBu8u' (length=14)
+          'italic' => string '/tmp/php9wVd9l' (length=14)
+          'bolditalic' => string '/tmp/phpRYicad' (length=14)
+      'error' => 
+        array (size=4)
+          'regular' => int 0
+          'bold' => int 0
+          'italic' => int 0
+          'bolditalic' => int 0
+      'size' => 
+        array (size=4)
+          'regular' => int 108172
+          'bold' => int 105460
+          'italic' => int 124012
+          'bolditalic' => int 118296
+```
+
+### Verarbeitung im Controller
+
+Auf die Uploadinfo muss jetzt anders zugegriffen werden, da `getFile` nur die oberste Ebene des Arrays ausgibt.
+
+```php
+$request = $this->app->Container->get('Request');
+$fileArray = $request->getFile('font');
+$fontRegular = $fileArray['regular'];
+$fontBold = $fileArray['bold'];
+```
+
+Alternativ ist auch möglich:
+
+```php
+$request = $this->app->Container->get('Request');
+$fileArray = $request->files->all();
+$fontRegular = $fileArray['font']['regular'];
+$fontBold = $fileArray['font']['bold'];
+```
+
+Beispiel: über alle Uploads iterieren:
+
+```php
+$request = $this->app->Container->get('Request');
+foreach($request->files as $fontType => $file) {
+    doSomething($fontType, $file);
+}
+```
+
+Mit den einzelnen `FileUpload` Objekten verfährt man nun genau wie im oberen Beispiel.
+
+**Hinweis:** Die Hierarchie der Dateiuploads kann beliebig tief geschachtelt sein. Getestet wird aber nur bis zur
+dritten Ebene.
+