Docs

exam/classes/Models/Post/Post.php

@@ -2,7 +2,6 @@
 
 namespace Khofmann\Models\Post;
 
-use Api\User\User as UserUser;
 use DateTime;
 use Exception;
 use Khofmann\Models\User\User;
@@ -12,6 +11,11 @@ use Khofmann\Config\Config;
 use Khofmann\Database\Database;
 use PDO;
 
+/**
+ * Post database model
+ *
+ * Abstracts database access
+ */
 class Post implements JsonSerializable
 {
   private int $id;
@@ -37,6 +41,16 @@ class Post implements JsonSerializable
   * Statics
   */
 
+  /**
+   * Get a post by ID.
+   *
+   * Also get creator (`User` object).
+   *
+   * @param int $id Post ID
+   *
+   * @throws NotFound Post not found
+   * @throws NotFound Creator of post was not found
+   */
   public static function getByID(int $id): Post
   {
     $db = Database::getInstance();
@@ -59,6 +73,15 @@ class Post implements JsonSerializable
     return new Post($data["id"], $user, null, null, $data["beitrag"], $data["zeitstempel"]);
   }
 
+  /**
+   * Create a new post.
+   *
+   * @param User $user Creator of post
+   * @param string $content Post content
+   * @param int $limit Limit for posts list to calculate number of pages
+   *
+   * @return array Number of pages after creation (in accordance with `limit`) and created post
+   */
   public static function create(User $user, string $content, int $limit): array
   {
     $content = substr(trim($content), 0, 250);
@@ -91,6 +114,15 @@ class Post implements JsonSerializable
     ];
   }
 
+  /**
+   * List of posts
+   *
+   * @param int $page Current page (offset)
+   * @param int $limit Posts per page
+   * @param bool $authed If `true`, include full `User` object. Defaults to `false`
+   * 
+   * @return array Number of pages and posts of selected page
+   */
   public static function list(int $page, int $limit, bool $authed = false): array
   {
     $db = Database::getInstance();
@@ -128,10 +160,20 @@ class Post implements JsonSerializable
   * Members
   */
 
+  /**
+   * Update post
+   *
+   * Does nothing if new `content` is empty
+   *
+   * @param ?string $content New content
+   *
+   * @throws Failed Failed to update content
+   */
   public function update(?string $content): Post
   {
     $db = Database::getInstance();
 
+    // Make sure we do all changes or none
     $db->beginTransaction();
 
     $failed = [];
@@ -156,16 +198,25 @@ class Post implements JsonSerializable
       }
     }
     if (count($failed) > 0) {
+      // We failed, go back
       $db->rollBack();
 
       throw ApiError::failedUpdate($failed, $reason);
     }
 
+    // Commit the changes
     $db->commit();
 
     return Post::getByID($this->id);
   }
 
+  /**
+   * Delete post
+   *
+   * @param int $limit Limit of list for which the returned pages is calculated.
+   *
+   * @return array Returns deleted post and resulting amount of pages for a given limit.
+   */
   public function delete(int $limit): array
   {
     $db = Database::getInstance();
@@ -189,21 +240,33 @@ class Post implements JsonSerializable
   * Getters
   */
 
+  /**
+   * Get post ID
+   */
   public function getId(): int
   {
     return $this->id;
   }
 
+  /**
+   * Get post creator
+   */
   public function getUser(): User
   {
     return $this->user;
   }
 
+  /**
+   * Get post content
+   */
   public function getContent(): string
   {
     return $this->content;
   }
 
+  /**
+   * Get time when post was created
+   */
   public function getPostedAt(): DateTime
   {
     return $this->postedAt;