Merge branch 'cleanup/PHPDokumentation' into 'dev'

cleanup/PHPDokumentation

See merge request eb2342s/swe-b1-a!2

webseite/classes/SubjectData.php

@@ -2,16 +2,52 @@
 require_once("Util.php");
 require_once("TopicData.php");
 
+/**
+ * Stellt alle relevanten Daten für ein einzeles Fach bereit
+ *
+ */
 class SubjectData
 {
+    /**
+     * @var string Ein eindeutiger Bezeichner für das Fach, darf nur A-Z, a-Z, 0-9 sowie _ und - enthalten
+     */
     public string $id;
+
+    /**
+     * @var string Der für User angezeigte Name des Faches, nur reiner Text
+     */
     public string $displayName;
+
+    /**
+     * @var string Eine kurze Beschreibung des Faches, z.B. für den Text auf der Startseite, kann HTML enthalten
+     */
     public string $description;
+
+    /**
+     * @var string Themenfarbe des Faches, entweder als hexcode oder CSS-Klasse, noch nicht spezifiziert
+     */
     public string $color;
+
+    /**
+     * @var string Text des Knopfes der auf die Fachseite weiterführt, nur reiner Text
+     */
     public string $buttonText;
+
+    /**
+     * @var string Icon des Faches als Font-Awesome CSS-Klasse
+     */
     public string $icon;
+
+    /**
+     * @var array Alle Themen des Faches als TopicData Objekt
+     * @see TopicData
+     */
     public array $topics;
 
+    /**
+     * Gibt alle Fächer als SubjectData Objekt zurück
+     * @return array Alle Fächer als SubjectData
+     */
     public static function getAll() : array
     {
         $result = array();
@@ -34,17 +70,22 @@ class SubjectData
         return $result;
     }
 
-    public static function fromName($subjectName) : SubjectData|null
+    /**
+     * Lädt ein Fach über eine gegebene ID
+     * @param $subjectId string Die eindeutige ID des Faches
+     * @return SubjectData|null Das Fach zu der ID oder null, wenn kein entsprechendes Fach gefunden wurde
+     */
+    public static function fromName(string $subjectId) : SubjectData|null
     {
         $result = new SubjectData();
 
-        $subjectName = Util::removeIllegalCharacters($subjectName);
+        $subjectId = Util::removeIllegalCharacters($subjectId);
 
-        $subjectDirectory = "config/subjects/$subjectName";
+        $subjectDirectory = "config/subjects/$subjectId";
         $filename = "$subjectDirectory/properties.json";
         $data = Util::parseJsonFromFile($filename);
 
-        $result->id = $subjectName;
+        $result->id = $subjectId;
 
         if(isset($data->displayName)) {
             $result->displayName = $data->displayName;
@@ -76,7 +117,7 @@ class SubjectData
             return null;
         }
 
-        $result->topics = TopicData::getAll($subjectName);
+        $result->topics = TopicData::getAll($subjectId);
 
         return $result;
     }

webseite/classes/TopicData.php

@@ -3,26 +3,62 @@ require_once("Util.php");
 
 class TopicData
 {
+    /**
+     * @var string Innerhalb des zugehörigen Faches eindeutige ID, darf nur A-Z, a-z, 0-9 sowie - und _ enthalten
+     */
     public string $id;
+
+    /**
+     * @var string Die eindeutige ID des zugehörigen Faches
+     */
     public string $subjectId;
+
+    /**
+     * @var string Der für User angezeigt Name des Themas, darf nur reinen Text enthalten
+     */
     public string $displayName;
+
+    /**
+     * @var string Das Icon des Themas als Font-Awesome CSS-Klasse
+     */
     public string $icon;
+
+    /**
+     * @var string Eine kurze Beschreibung des Themas, z.B. für die Fachübersichtsseite, darf HTML enthalten
+     */
     public string $description;
+
+    /**
+     * @var array Die IDs aller verwandten Themen als String
+     */
     public array $relatedTopics;
+
+    /**
+     * @var array Die Dateinamen (Datei.pdf) aller downloadbarer Dateien zu diesem Thema als String
+     */
     public array $files;
+
+    /**
+     * @var string Der gesamte Erklärungstext zum Thema, enthält fertiges HTML
+     */
     public string $article;
 
-    public static function getAll($subjectName) : array
+    /**
+     * Gibt alle Themen zu einem gegebenen Fach zurück
+     * @param $subjectId string Die ID des Faches
+     * @return array Alle zugehörigen Themen als TopicData Objekte
+     */
+    public static function getAll(string $subjectId) : array
     {
         $result = array();
 
-        $topicDirectory = "config/subjects/$subjectName/topics";
+        $topicDirectory = "config/subjects/$subjectId/topics";
         $topicNames = scandir($topicDirectory);
         foreach ($topicNames as $topicName) {
             if ($topicName == "." || $topicName == "..") {
                 continue;
             }
-            $topicData = TopicData::fromName($subjectName, $topicName);
+            $topicData = TopicData::fromName($subjectId, $topicName);
             if(!isset($topicData)) {
                 continue;
             }
@@ -33,19 +69,25 @@ class TopicData
         return $result;
     }
 
-    public static function fromName($subjectName, $topicName): TopicData|null
+    /**
+     * Gibt Themendaten zu einem bestimmten Thema eines Faches zurück
+     * @param $subjectId string Die ID des Faches
+     * @param $topicId string Die ID des Themas
+     * @return TopicData|null Die Themendaten oder null, wenn das Thema nicht existiert
+     */
+    public static function fromName(string $subjectId, string $topicId): TopicData|null
     {
         $result = new TopicData();
 
-        $subjectName = Util::removeIllegalCharacters($subjectName);
-        $topicName = Util::removeIllegalCharacters($topicName);
+        $subjectId = Util::removeIllegalCharacters($subjectId);
+        $topicId = Util::removeIllegalCharacters($topicId);
 
-        $topicDirectory = "config/subjects/$subjectName/topics";
-        $filename = "$topicDirectory/$topicName/properties.json";
+        $topicDirectory = "config/subjects/$subjectId/topics";
+        $filename = "$topicDirectory/$topicId/properties.json";
         $data = Util::parseJsonFromFile($filename);
 
-        $result->id = $topicName;
-        $result->subjectId = $subjectName;
+        $result->id = $topicId;
+        $result->subjectId = $subjectId;
 
         if(isset($data->displayName)) {
             $result->displayName = $data->displayName;

webseite/classes/Util.php

@@ -1,13 +1,26 @@
 <?php
 
+/**
+ * Hilfsmethoden für verschiedene Aufgaben
+ */
 class Util
 {
-    static function removeIllegalCharacters($string): string
+    /**
+     * Entfernt alle Zeichen außer A-Z, a-z, 0-9 sowie - und _
+     * @param string $string Eingabe mit möglicherweise ungültigen Zeichen
+     * @return string Eingabestring mit allen ungültigen Zeichen entfernt
+     */
+    static function removeIllegalCharacters(string $string): string
     {
         return preg_replace("/[^a-zA-Z0-9_-]/", "", $string);
     }
 
-    static function parseJsonFromFile($filename): mixed
+    /**
+     * Öffnet eine Datei und gibt JSON-Inhalte als Array zurück
+     * @param string $filename Dateipfad
+     * @return mixed Array mit Key-Value Paaren
+     */
+    static function parseJsonFromFile(string $filename): mixed
     {
         $file = fopen($filename, "r") or die("Unable to open file!");
         $fileContent = fread($file, filesize($filename));