<?php

/**
 * Interface für den Zugriff auf Benutzerdaten.
 *
 * Definiert die Methoden, die jede UserDAO-Implementierung
 * bereitstellen muss.
 */
interface UserManagerDAO {

    /**
     * Sucht einen Benutzer anhand seiner E-Mail-Adresse.
     *
     * Funktion:
     * Liefert die gespeicherten Benutzerdaten zu einer E-Mail-Adresse.
     *
     * Eingabe:
     * @param string $email E-Mail-Adresse des gesuchten Benutzers
     *
     * Ausgabe:
     * @return array|null Benutzerdaten als Array oder null
     *
     * Mögliche Fehler:
     * @throws RuntimeException wenn die Benutzerdaten nicht gelesen werden können
     */
    public function findUser($email);

    /**
     * Fügt einen neuen Benutzer hinzu.
     *
     * Funktion:
     * Erstellt einen neuen Benutzereintrag und speichert ihn
     * in der jeweiligen Datenquelle.
     *
     * Eingabe:
     * @param string $email E-Mail-Adresse des Benutzers
     * @param string $vorname Vorname des Benutzers
     * @param string $nachname Nachname des Benutzers
     * @param string $password Passwort des Benutzers
     *
     * Ausgabe:
     * @return void
     *
     * Mögliche Fehler:
     * @throws InvalidArgumentException wenn die E-Mail-Adresse bereits verwendet wird
     * @throws RuntimeException wenn die Benutzerdaten nicht gelesen oder gespeichert werden können
     */
    public function addUser($email, $vorname, $nachname, $password);

    /**
     * Aktualisiert einen bestehenden Benutzer.
     *
     * Funktion:
     * Ändert die E-Mail-Adresse, den Vornamen, den Nachnamen
     * und optional das Passwort eines bestehenden Benutzers.
     *
     * Eingabe:
     * @param string $oldEmail Alte E-Mail-Adresse
     * @param string $newEmail Neue E-Mail-Adresse
     * @param string $vorname Neuer Vorname
     * @param string $nachname Neuer Nachname
     * @param string|null $password Neues Passwort oder null
     *
     * Ausgabe:
     * @return bool true, wenn der Benutzer aktualisiert wurde, sonst false
     *
     * Mögliche Fehler:
     * @throws InvalidArgumentException wenn die neue E-Mail-Adresse bereits verwendet wird
     * @throws RuntimeException wenn die Benutzerdaten nicht gelesen oder gespeichert werden können
     */
    public function updateUser($oldEmail, $newEmail, $vorname, $nachname, $password = null);

    /**
     * Löscht einen Benutzer anhand seiner E-Mail-Adresse.
     *
     * Funktion:
     * Entfernt einen vorhandenen Benutzer aus der Datenquelle.
     *
     * Eingabe:
     * @param string $email E-Mail-Adresse des zu löschenden Benutzers
     *
     * Ausgabe:
     * @return bool true, wenn der Benutzer gelöscht wurde, sonst false
     *
     * Mögliche Fehler:
     * @throws RuntimeException wenn die Benutzerdaten nicht gelesen oder gespeichert werden können
     */
    public function deleteUser($email);
}