API getuned, neue Methoden findBy/queryBy

CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+## xx-xx-2024 x.x.x (**Breacking Changes ⚠**)
+
+> Work in Progress !!!
+
+Version x.x.x ist an vielen Ständen überarbeitet, was auch die Schnittstellen der
+Klassen/Methoden betrifft. Beim Update von Versionen vor x.x.x müssen ggf. Anpassungen
+im eigenen Code vorgenommen werden:
+
+- Klasse `Author`:
+  - alter Klassenname: `neues_author` => neu: `FriendsOfRedaxo\Neues\Author`
+  - `$author->getName`: liefert immer einen ggf. leeren `string`; `null` als Rückgabe ist entfernt
+  - `$author->getNickName`: liefert immer einen ggf. leeren `string`; `null` als Rückgabe ist entfernt
+  - `$author->geText`: liefert immer einen ggf. leeren `string`; `null` als Rückgabe ist entfernt
+  - `$author->getBeUserId`: liefert immer eine Id vom Typ`int` (0=unbekannt); `null` als Rückgabe ist entfernt
+- Klasse `Category`:
+  - alter Klassenname: `neues_category` => neu: `FriendsOfRedaxo\Neues\Category`
+  - `$cat->getName`: liefert immer einen ggf. leeren `string`; `null` als Rückgabe ist entfernt
+- Klasse `Entry`:
+  - alter Klassenname: `neues_entry` => neu: `FriendsOfRedaxo\Neues\Entry`
+  - `$post->getImages`: API angepasst auf `array`, da ohnehin stets ein ggf. leeres Array geliefert wurde, aber nie `null`
+  - `$post->setImages`: `null` für "leer also löschen" wird nicht mehr akzeptiert; statt dessen `[]`benutzen oder den Parameter weglassen.
+  - `$post->getExternalUrl`: liefert immer einen ggf. leeren `string`; `null` als Rückgabe ist entfernt.
+  - `$post->getStatus`: liefert nun richtigerweise `int` statt `string`
+  - `Entry::findOnline`: `null` als "suche alle"-Kennung durch `0`ersetzt.
+  - `Entry::findByCategory`: `null` als "suche alle"-Kennung durch `0`ersetzt.
+  - `Entry::findByCategoryIds`: `null` als "suche alle"-Kennung durch `0`ersetzt.
+  - neu: `$post->getCanonicalUrl`
+  - neu: `$post->setCanonicalUrl`
+  - neu: `Entry::queryBy`
+  - neu: `Entry::findBy`
+- Klasse `EntryLang`
+  - alter Klassenname: `neues_entry_lang` => neu: `FriendsOfRedaxo\Neues\EntryLang`
+  - `$cat->getCode`: liefert immer einen ggf. leeren `string`; `null` als Rückgabe ist entfernt
+  - `$cat->geName`: liefert immer einen ggf. leeren `string`; `null` als Rückgabe ist entfernt
+- Klasse `Entry`:
+  - alter Klassenname: `neues` => neu: `FriendsOfRedaxo\Neues\Neues`

docs/03_neues_entry.md

@@ -236,15 +236,15 @@ Setzt den Status des Eintrags.
 $entry = $entry->setStatus(1);
 ```
 
-### findOnline(?int $category_id = null)
+### findOnline(int $category_id = 0)
 
 Findet Online-Einträge. Wenn eine Kategorie-ID angegeben ist, werden nur Einträge aus dieser Kategorie zurückgegeben.
 
 ```php
 $entries = FriendsOfRedaxo\Neues\Entry::findOnline(1);
 ```
 
-### findByCategory(?int $category_id = null, int $status = Entry::ONLINE)
+### findByCategory(int $category_id = 0, int $status = Entry::ONLINE)
 
 Findet Einträge nach Kategorie.
 

fragments/neues/entry.php

@@ -25,7 +25,7 @@
 
                         <!-- Author -->
                         <?php if (null !== $post->getAuthor()) : ?>
-                            <?php if (null !== $post->getAuthor()->getName()) : ?>
+                            <?php if ('' !== $post->getAuthor()->getName()) : ?>
                                 von <span><?= htmlspecialchars($post->getAuthor()->getName()) ?></span>
                             <?php elseif(null !== $post->getAuthor()->getNickname()): ?>
                                 von <span><?= htmlspecialchars($post->getAuthor()->getNickname()) ?></span>

lib/Author.php

@@ -29,16 +29,19 @@ class Author extends rex_yform_manager_dataset
      * Gibt den Namen des Autors zurück.
      * Returns the name of the author.
      *
-     * @return string|null Der Name des Autors oder null, wenn kein Name gesetzt ist. / The name of the author or null if no name is set.
+     * @return string Der Name des Autors oder '', wenn kein Name gesetzt ist. / The name of the author or '' if no name is set.
      *
      * Beispiel / Example:
      * $name = $author->getName();
      *
      * @api
      */
-    public function getName(): ?string
+    public function getName(): string
     {
-        return $this->getValue('name');
+        if ($this->hasValue('name')) {
+            return $this->getValue('name');
+        }
+        return '';
     }
 
     /**
@@ -60,16 +63,19 @@ public function setName(string $value): self
      * Gibt den Spitznamen des Autors zurück.
      * Returns the nickname of the author.
      *
-     * @return string|null Der Spitzname des Autors oder null, wenn kein Spitzname gesetzt ist. / The nickname of the author or null if no nickname is set.
+     * @return string Der Spitzname des Autors oder '', wenn kein Spitzname gesetzt ist. / The nickname of the author or '' if no nickname is set.
      *
      * Beispiel / Example:
      * $nickname = $author->getNickname();
      *
      * @api
      */
-    public function getNickname(): ?string
+    public function getNickname(): string
     {
-        return $this->getValue('nickname');
+        if ($this->hasValue('nickname')) {
+            return $this->getValue('nickname');
+        }
+        return '';
     }
 
     /**
@@ -92,19 +98,19 @@ public function setNickname(string $value): self
      * Returns the text of the author.
      *
      * @param bool $asPlaintext Wenn true, wird der Text ohne HTML-Tags zurückgegeben. / If true, the text is returned without HTML tags.
-     * @return string|null Der Text des Autors oder null, wenn kein Text gesetzt ist. / The text of the author or null if no text is set.
+     * @return string Der Text des Autors oder '', wenn kein Text gesetzt ist. / The text of the author or '' if no text is set.
      *
      * Beispiel / Example:
      * $text = $author->getText(true);
      *
      * @api
      */
-    public function getText(bool $asPlaintext = false): ?string
+    public function getText(bool $asPlaintext = false): string
     {
-        if ($asPlaintext) {
-            return strip_tags($this->getValue('text'));
+        if ($this->hasValue('text')) {
+            return $asPlaintext ? strip_tags($this->getValue('text')) : $this->getValue('text');
         }
-        return $this->getValue('text');
+        return '';
     }
 
     /**
@@ -126,16 +132,19 @@ public function setText(string $value): self
      * Gibt die Benutzer-ID des Autors zurück.
      * Returns the user ID of the author.
      *
-     * @return int|null Die Benutzer-ID des Autors oder null, wenn keine Benutzer-ID gesetzt ist. / The user ID of the author or null if no user ID is set.
+     * @return int Die Benutzer-ID des Autors oder 0, wenn keine Benutzer-ID gesetzt ist. / The user ID of the author or 0 if no user ID is set.
      *
      * Beispiel / Example:
      * $beUserId = $author->getBeUserId();
      *
      * @api
      */
-    public function getBeUserId(): ?int
+    public function getBeUserId(): int
     {
-        return (int) $this->getValue('be_user_id');
+        if ($this->hasValue('be_user_id')) {
+            return (int) $this->getValue('be_user_id');
+        }
+        return 0;
     }
 
     /**
@@ -165,6 +174,10 @@ public function setBeUserId(int $value): self
      */
     public function getBeUser(): ?rex_user
     {
-        return rex_user::get($this->getBeUserId());
+        $userId = $this->getBeUserId();
+        if (0 !== $userId) {
+            return rex_user::get($userId);
+        }
+        return null;
     }
 }

lib/Category.php

@@ -41,7 +41,10 @@ class Category extends rex_yform_manager_dataset
      */
     public function getName(): string
     {
-        return $this->getValue('name');
+        if ($this->hasValue('name')) {
+            return $this->getValue('name');
+        }
+        return '';
     }
 
     /**
@@ -65,7 +68,7 @@ public function setName(string $name): self
      * Gibt die Einträge der Kategorie zurück.
      * Returns the entries of the Category.
      *
-     * @return rex_yform_manager_collection<Entry> Die Einträge der Kategorie oder null, wenn keine Einträge vorhanden sind. / The entries of the Category or null if no entries are present.
+     * @return rex_yform_manager_collection<Entry> Die Einträge der Kategorie oder leere Liste, wenn keine Einträge vorhanden sind. / The entries of the Category or empty list if no entries are present.
      *
      * Beispiel / Example:
      * $entries = $category->getEntries();