Kommentare ergänzt

php/model/DatabaseUserManager.php

@@ -2,10 +2,24 @@
 
 require_once "UserManagerDAO.php";
 
+/**
+ * Klasse für den Zugriff auf Benutzerdaten über eine SQLite-Datenbank.
+ *
+ * Diese Klasse verwendet PDO, Prepared Statements und speichert
+ * Benutzerdaten in der Datei db/users.db.
+ */
 class DatabaseUserManager implements UserManagerDAO {
 
     private static $instance = null;
 
+    /**
+     * Konstruktor.
+     *
+     * Erstellt die Benutzerdatenbank und die Tabelle users,
+     * falls diese noch nicht existieren.
+     *
+     * @throws RuntimeException wenn die Datenbank nicht erstellt werden kann
+     */
     public function __construct()
     {
         try {
@@ -27,6 +41,13 @@ class DatabaseUserManager implements UserManagerDAO {
         }
     }
 
+    /**
+     * Baut eine Verbindung zur SQLite-Datenbank auf.
+     *
+     * @return PDO Datenbankverbindung
+     *
+     * @throws RuntimeException wenn keine Verbindung hergestellt werden kann
+     */
     private function getConnection()
     {
         try {
@@ -42,6 +63,11 @@ class DatabaseUserManager implements UserManagerDAO {
         }
     }
 
+    /**
+     * Gibt die Singleton-Instanz des DatabaseUserManagers zurück.
+     *
+     * @return DatabaseUserManager Instanz des DatabaseUserManagers
+     */
     public static function getInstance()
     {
         if (self::$instance == null) {
@@ -51,6 +77,16 @@ class DatabaseUserManager implements UserManagerDAO {
         return self::$instance;
     }
 
+    /**
+     * Sucht einen Benutzer anhand seiner E-Mail-Adresse.
+     *
+     * @param string $email E-Mail-Adresse des Benutzers
+     *
+     * @return array|null Benutzerdaten als Array oder null,
+     *                    wenn kein Benutzer gefunden wurde
+     *
+     * @throws RuntimeException wenn der Benutzer nicht geladen werden kann
+     */
     public function findUser($email)
     {
         try {
@@ -72,6 +108,22 @@ class DatabaseUserManager implements UserManagerDAO {
         }
     }
 
+    /**
+     * Fügt einen neuen Benutzer in die Datenbank ein.
+     *
+     * Die Speicherung erfolgt innerhalb einer Transaktion.
+     * Doppelte E-Mail-Adressen werden durch den Primary Key verhindert.
+     *
+     * @param string $email E-Mail-Adresse des Benutzers
+     * @param string $vorname Vorname des Benutzers
+     * @param string $nachname Nachname des Benutzers
+     * @param string $password Passwort-Hash des Benutzers
+     *
+     * @return void
+     *
+     * @throws InvalidArgumentException wenn die E-Mail-Adresse bereits verwendet wird
+     * @throws RuntimeException wenn der Benutzer nicht gespeichert werden kann
+     */
     public function addUser($email, $vorname, $nachname, $password)
     {
         try {
@@ -107,6 +159,24 @@ class DatabaseUserManager implements UserManagerDAO {
         }
     }
 
+    /**
+     * Aktualisiert die Daten eines bestehenden Benutzers.
+     *
+     * Optional kann zusätzlich das Passwort geändert werden.
+     * Wenn kein neues Passwort übergeben wird, bleibt das alte Passwort erhalten.
+     *
+     * @param string $oldEmail Aktuelle E-Mail-Adresse des Benutzers
+     * @param string $newEmail Neue E-Mail-Adresse des Benutzers
+     * @param string $vorname Neuer Vorname des Benutzers
+     * @param string $nachname Neuer Nachname des Benutzers
+     * @param string|null $password Neues Passwort oder null
+     *
+     * @return bool true, wenn der Benutzer aktualisiert wurde,
+     *              sonst false
+     *
+     * @throws InvalidArgumentException wenn die neue E-Mail-Adresse bereits verwendet wird
+     * @throws RuntimeException wenn der Benutzer nicht aktualisiert werden kann
+     */
     public function updateUser($oldEmail, $newEmail, $vorname, $nachname, $password = null)
     {
         try {
@@ -160,6 +230,16 @@ class DatabaseUserManager implements UserManagerDAO {
         }
     }
 
+    /**
+     * Löscht einen Benutzer anhand seiner E-Mail-Adresse.
+     *
+     * @param string $email E-Mail-Adresse des zu löschenden Benutzers
+     *
+     * @return bool true, wenn der Benutzer gelöscht wurde,
+     *              sonst false
+     *
+     * @throws RuntimeException wenn der Benutzer nicht gelöscht werden kann
+     */
     public function deleteUser($email)
     {
         try {

php/validator/user-validator.php

@@ -1,5 +1,15 @@
 <?php
 
+/**
+ * Prüft, ob ein Vor- oder Nachname gültig ist.
+ *
+ * Erlaubt werden Buchstaben, Umlaute, Leerzeichen und Bindestriche.
+ * Die Länge muss zwischen 2 und 20 Zeichen liegen.
+ *
+ * @param string $name Zu prüfender Name
+ *
+ * @return bool true wenn der Name gültig ist, sonst false
+ */
 function userNameValidator($name)
 {
     $name = trim($name);
@@ -8,6 +18,16 @@ function userNameValidator($name)
     return preg_match($namePattern, $name) === 1;
 }
 
+/**
+ * Prüft, ob eine E-Mail-Adresse gültig ist.
+ *
+ * Die E-Mail-Adresse muss dem Standardformat entsprechen
+ * und darf höchstens 100 Zeichen lang sein.
+ *
+ * @param string $email Zu prüfende E-Mail-Adresse
+ *
+ * @return bool true wenn die E-Mail-Adresse gültig ist, sonst false
+ */
 function userEmailValidator($email)
 {
     $email = trim($email);
@@ -16,6 +36,15 @@ function userEmailValidator($email)
         && mb_strlen($email) <= 100;
 }
 
+/**
+ * Prüft, ob ein Passwort die Längenanforderungen erfüllt.
+ *
+ * Das Passwort muss zwischen 5 und 12 Zeichen lang sein.
+ *
+ * @param string $password Zu prüfendes Passwort
+ *
+ * @return bool true wenn das Passwort gültig ist, sonst false
+ */
 function userPasswordValidator($password)
 {
     $zeichenAnzahl = mb_strlen($password);
@@ -23,6 +52,19 @@ function userPasswordValidator($password)
     return $zeichenAnzahl >= 5 && $zeichenAnzahl <= 12;
 }
 
+/**
+ * Prüft ein optionales Passwort.
+ *
+ * Ein leeres Passwort ist erlaubt und bedeutet,
+ * dass das bestehende Passwort unverändert bleibt.
+ * Falls ein Passwort angegeben wurde, wird es
+ * mit den normalen Passwortregeln geprüft.
+ *
+ * @param string|null $password Zu prüfendes Passwort
+ *
+ * @return bool true wenn das Passwort gültig oder leer ist,
+ *              sonst false
+ */
 function userOptionalPasswordValidator($password)
 {
     if (!isset($password) || $password === '') {