From 989103f6d77fe50c7acb035673bcdcdcb13b4c1d Mon Sep 17 00:00:00 2001
From: Alexander Walther <mail@alexplus.de>
Date: Sat, 16 Dec 2023 17:35:25 +0100
Subject: [PATCH] =?UTF-8?q?Zus=C3=A4tzliche=20Docs=20f=C3=BCr=20neues=5Fen?=
 =?UTF-8?q?try?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/03_neues_entry.md   | 219 ++++++++++++++++++++++++-
 lib/neues_entry.php      | 337 +++++++++++++++++++++++++++++++++------
 lib/neues_entry_lang.php |  98 ++++++++++++
 3 files changed, 601 insertions(+), 53 deletions(-)
 create mode 100644 lib/neues_entry_lang.php

diff --git a/docs/03_neues_entry.md b/docs/03_neues_entry.md
index 6613766..c6a3389 100644
--- a/docs/03_neues_entry.md
+++ b/docs/03_neues_entry.md
@@ -12,7 +12,7 @@ $entries = neues_entry::findOnline(); // Alle Online-Einträge
 $entries = neues_entry::findByCategory($category_id [, $status]) // Alle Einträge einer Kategorie
 ```
 
-## Beispiel-Ausgabe einer News
+## Methoden und Beispiele
 
 ```php
 $entry = neues_entry::get(3); // News mit der id=3
@@ -29,7 +29,6 @@ echo $entry->getDescription();
 echo $entry->getExternalUrl();
 echo $entry->getExternalLabel();
 echo $entry->getPublishDate();
-echo $entry->getPublishDateTime();
 echo $entry->getFormattedPublishDate($format); // IntlDateFormatter::FULL
 echo $entry->getFormattedPublishDateTime($format); // [IntlDateFormatter::FULL, IntlDateFormatter::SHORT]
 echo $entry->getStatus();
@@ -44,3 +43,219 @@ foreach($categories as $category) {
 // ...
 }
 ```
+
+### getName()
+
+Gibt den Namen des Eintrags zurück.
+
+```php
+$name = $entry->getName();
+```
+
+### setName(string $name)
+
+Setzt den Namen des Eintrags.
+
+```php
+$entry = $entry->setName('Neuer Name');
+```
+
+### getAuthor()
+
+Gibt den Autor des Eintrags zurück oder null, wenn kein Autor gesetzt ist.
+
+```php
+$author = $entry->getAuthor();
+```
+
+### getDomain()
+
+Gibt die Domain des Eintrags zurück.
+
+```php
+$domain = $entry->getDomain();
+```
+
+### setDomain(mixed $domain)
+
+Setzt die Domain des Eintrags.
+
+```php
+$entry = $entry->setDomain('neue-domain.com');
+```
+
+### getTeaser()
+
+Gibt den Teaser des Eintrags zurück.
+
+```php
+$teaser = $entry->getTeaser();
+```
+
+### getCategories()
+
+Gibt die Kategorien des Eintrags zurück oder null, wenn keine Kategorien gesetzt sind.
+
+```php
+$categories = $entry->getCategories();
+```
+
+### getImage()
+
+Gibt das Bild des Eintrags zurück.
+
+```php
+$image = $entry->getImage();
+```
+
+### setImage(string $image)
+
+Setzt das Bild des Eintrags.
+
+```php
+$entry = $entry->setImage('neues_bild.jpg');
+```
+
+### getImages()
+
+Gibt die Bilder des Eintrags zurück oder null, wenn keine Bilder gesetzt sind.
+
+```php
+$images = $entry->getImages();
+```
+
+### setImages(?array $images)
+
+Setzt die Bilder des Eintrags.
+
+```php
+$entry = $entry->setImages(['bild1.jpg', 'bild2.jpg']);
+```
+
+### getMedia()
+
+Gibt das Medium des Eintrags zurück oder null, wenn kein Medium gesetzt ist.
+
+```php
+$media = $entry->getMedia();
+```
+
+### setMedia(?rex_media $media)
+
+Setzt das Medium des Eintrags.
+
+```php
+$entry = $entry->setMedia($newMedia);
+```
+
+### getDescriptionAsPlaintext()
+
+Gibt die Beschreibung des Eintrags als reinen Text zurück.
+
+```php
+$descriptionPlainText = $entry->getDescriptionAsPlaintext();
+```
+
+### getDescription()
+
+Gibt die Beschreibung des Eintrags zurück.
+
+```php
+$description = $entry->getDescription();
+```
+
+### setDescription(string $description)
+
+Setzt die Beschreibung des Eintrags.
+
+```php
+$entry = $entry->setDescription('Neue Beschreibung');
+```
+
+### getExternalUrl()
+
+Gibt die externe URL des Eintrags zurück oder null, wenn keine URL gesetzt ist.
+
+```php
+$externalUrl = $entry->getExternalUrl();
+```
+
+### setExternalUrl(string $url)
+
+Setzt die externe URL des Eintrags.
+
+```php
+$entry = $entry->setExternalUrl('http://neue-url.com');
+```
+
+### getPublishDate()
+
+Gibt das Veröffentlichungsdatum des Eintrags zurück.
+
+```php
+$publishDate = $entry->getPublishDate();
+```
+
+### setPublishDate(string $publishdate)
+
+Setzt das Veröffentlichungsdatum des Eintrags.
+
+```php
+$entry = $entry->setPublishDate('2022-01-01');
+```
+
+### getFormattedPublishDate($format_date = IntlDateFormatter::FULL)
+
+Gibt das formatierte Veröffentlichungsdatum des Eintrags zurück.
+
+```php
+$formattedPublishDate = $entry->getFormattedPublishDate(IntlDateFormatter::FULL);
+```
+
+### getFormattedPublishDateTime($format = [IntlDateFormatter::FULL, IntlDateFormatter::SHORT])
+
+Gibt das formatierte Veröffentlichungsdatum und -zeit des Eintrags zurück.
+
+```php
+$formattedPublishDateTime = $entry->getFormattedPublishDateTime([IntlDateFormatter::FULL, IntlDateFormatter::SHORT]);
+```
+
+### getStatus()
+
+Gibt den Status des Eintrags zurück.
+
+```php
+$status = $entry->getStatus();
+```
+
+### setStatus(int $status)
+
+Setzt den Status des Eintrags.
+
+```php
+$entry = $entry->setStatus(1);
+```
+
+### findOnline(?int $category_id = null)
+
+Findet Online-Einträge. Wenn eine Kategorie-ID angegeben ist, werden nur Einträge aus dieser Kategorie zurückgegeben.
+
+```php
+$entries = neues_entry::findOnline(1);
+```
+
+### findByCategory(?int $category_id = null, int $status = 1)
+
+Findet Einträge nach Kategorie.
+
+```php
+$entries = neues_entry::findByCategory(1, 1);
+```
+
+### getUrl(string $profile = 'neues-entry-id')
+
+Gibt die URL des Eintrags zurück.
+
+```php
+$url = $entry->getUrl();
+```
diff --git a/lib/neues_entry.php b/lib/neues_entry.php
index 3207f51..9080b5a 100644
--- a/lib/neues_entry.php
+++ b/lib/neues_entry.php
@@ -26,32 +26,37 @@ public function getName(): string
     {
         return $this->getValue('name');
     }
-
+    /**
+     * Setzt den Namen des Eintrags.
+     * Sets the name of the entry.
+     *
+     * @param string $name Der neue Name des Eintrags. / The new name of the entry.
+     * @return self
+     *
+     * Beispiel / Example:
+     * $entry = $entry->setName('Neuer Name');
+     *
+     * @api
+     */
     public function setName(string $name): self
     {
         $this->setValue('name', $name);
         return $this;
     }
-
     /**
-     * @api
-     * @return string
-     *
      * Gibt den Autor des Eintrags zurück.
      * Returns the author of the entry.
      *
+     * @return neues_author|null Der Autor des Eintrags oder null, wenn kein Autor gesetzt ist. / The author of the entry or null if no author is set.
+     *
      * Beispiel / Example:
      * $author = $entry->getAuthor();
+     *
+     * @api
      */
-    public function getAuthor(): string
-    {
-        return $this->getValue('author');
-    }
-
-    public function setAuthor(string $author): self
+    public function getAuthor(): ?neues_author
     {
-        $this->setValue('author', $author);
-        return $this;
+        return $this->getRelatedDataset('author');
     }
 
     /**
@@ -69,25 +74,65 @@ public function getDomain(): string
         return $this->getValue('domain');
     }
 
-    public function setDomain(string $domain): self
+    /**
+     * Setzt die Domain des Eintrags.
+     * Sets the domain of the entry.
+     *
+     * @param mixed $domain Die neue Domain des Eintrags. / The new domain of the entry.
+     * @return self
+     *
+     * Beispiel / Example:
+     * $entry = $entry->setDomain('neue-domain.com');
+     *
+     * @api
+     */
+    public function setDomain(mixed $domain): self
     {
         $this->setValue('domain', $domain);
         return $this;
     }
 
-    /** @api */
+    /**
+     * Gibt den Teaser des Eintrags zurück.
+     * Returns the teaser of the entry.
+     *
+     * @return string Der Teaser des Eintrags. / The teaser of the entry.
+     *
+     * Beispiel / Example:
+     * $teaser = $entry->getTeaser();
+     *
+     * @api
+     */
     public function getTeaser(): string
     {
         return $this->getValue('teaser');
     }
 
-    /** @api */
+    /**
+     * Gibt die Kategorien des Eintrags zurück.
+     * Returns the categories of the entry.
+     *
+     * @return rex_yform_manager_collection|null Die Kategorien des Eintrags oder null, wenn keine Kategorien gesetzt sind. / The categories of the entry or null if no categories are set.
+     *
+     * Beispiel / Example:
+     * $categories = $entry->getCategories();
+     *
+     * @api
+     */
     public function getCategories(): ?rex_yform_manager_collection
     {
         return $this->getRelatedCollection('category_ids');
-    }
-
-    /** @api */
+    }    /**
+     * Gibt das Bild des Eintrags zurück.
+     * Returns the image of the entry.
+     *
+     * @return string Das Bild des Eintrags. / The image of the entry.
+     *
+     * Beispiel / Example:
+     * $image = $entry->getImage();
+     *
+     * @api
+     */
     public function getImage(): string
     {
         if ('' == $this->getValue('image')) {
@@ -98,25 +143,68 @@ public function getImage(): string
         return $this->image;
     }
 
+    /**
+     * Setzt das Bild des Eintrags.
+     * Sets the image of the entry.
+     *
+     * @param string $image Das neue Bild des Eintrags. / The new image of the entry.
+     * @return self
+     *
+     * Beispiel / Example:
+     * $entry = $entry->setImage('neues_bild.jpg');
+     *
+     * @api
+     */
     public function setImage(string $image): self
     {
         $this->setValue('image', $image);
         return $this;
     }
 
-    /** @api */
+    /**
+     * Gibt die Bilder des Eintrags zurück.
+     * Returns the images of the entry.
+     *
+     * @return array|null Die Bilder des Eintrags oder null, wenn keine Bilder gesetzt sind. / The images of the entry or null if no images are set.
+     *
+     * Beispiel / Example:
+     * $images = $entry->getImages();
+     *
+     * @api
+     */
     public function getImages(): ?array
     {
         return array_filter(explode(',', $this->getValue('images')));
     }
 
+    /**
+     * Setzt die Bilder des Eintrags.
+     * Sets the images of the entry.
+     *
+     * @param array|null $images Die neuen Bilder des Eintrags. / The new images of the entry.
+     * @return self
+     *
+     * Beispiel / Example:
+     * $entry = $entry->setImages(['bild1.jpg', 'bild2.jpg']);
+     *
+     * @api
+     */
     public function setImages(?array $images): self
     {
         $this->setValue('images', implode(',', $images));
         return $this;
     }
-
-    /** @api */
+    /**
+     * Gibt das Medium des Eintrags zurück.
+     * Returns the media of the entry.
+     *
+     * @return rex_media|null Das Medium des Eintrags oder null, wenn kein Medium gesetzt ist. / The media of the entry or null if no media is set.
+     *
+     * Beispiel / Example:
+     * $media = $entry->getMedia();
+     *
+     * @api
+     */
     public function getMedia(): ?rex_media
     {
         if (rex_addon::get('media_manager_resposnive')->isAvailable()) {
@@ -125,6 +213,18 @@ public function getMedia(): ?rex_media
         return rex_media::get($this->getImage());
     }
 
+    /**
+     * Setzt das Medium des Eintrags.
+     * Sets the media of the entry.
+     *
+     * @param rex_media|null $media Das neue Medium des Eintrags. / The new media of the entry.
+     * @return self
+     *
+     * Beispiel / Example:
+     * $entry = $entry->setMedia($newMedia);
+     *
+     * @api
+     */
     public function setMedia(?rex_media $media): self
     {
         if (null !== $media) {
@@ -135,89 +235,200 @@ public function setMedia(?rex_media $media): self
         return $this;
     }
 
-    /** @api */
+    /**
+     * Gibt die Beschreibung des Eintrags als reinen Text zurück.
+     * Returns the description of the entry as plain text.
+     *
+     * @return string Die Beschreibung des Eintrags als reinen Text. / The description of the entry as plain text.
+     *
+     * Beispiel / Example:
+     * $descriptionPlainText = $entry->getDescriptionAsPlaintext();
+     *
+     * @api
+     */
     public function getDescriptionAsPlaintext(): string
     {
         return strip_tags($this->getValue('description'));
     }
 
-    /** @api */
+    /**
+     * Gibt die Beschreibung des Eintrags zurück.
+     * Returns the description of the entry.
+     *
+     * @return string Die Beschreibung des Eintrags. / The description of the entry.
+     *
+     * Beispiel / Example:
+     * $description = $entry->getDescription();
+     *
+     * @api
+     */
     public function getDescription(): string
     {
         return $this->getValue('description');
     }
-
+    /**
+     * Setzt die Beschreibung des Eintrags.
+     * Sets the description of the entry.
+     *
+     * @param string $description Die neue Beschreibung des Eintrags. / The new description of the entry.
+     * @return self
+     *
+     * Beispiel / Example:
+     * $entry = $entry->setDescription('Neue Beschreibung');
+     *
+     * @api
+     */
     public function setDescription(string $description): self
     {
         $this->setValue('description', $description);
         return $this;
     }
 
-    /** @api */
+    /**
+     * Gibt die externe URL des Eintrags zurück.
+     * Returns the external URL of the entry.
+     *
+     * @return string|null Die externe URL des Eintrags oder null, wenn keine URL gesetzt ist. / The external URL of the entry or null if no URL is set.
+     *
+     * Beispiel / Example:
+     * $externalUrl = $entry->getExternalUrl();
+     *
+     * @api
+     */
     public function getExternalUrl(): ?string
     {
         return $this->getValue('url');
     }
 
+    /**
+     * Setzt die externe URL des Eintrags.
+     * Sets the external URL of the entry.
+     *
+     * @param string $url Die neue externe URL des Eintrags. / The new external URL of the entry.
+     * @return self
+     *
+     * Beispiel / Example:
+     * $entry = $entry->setExternalUrl('http://neue-url.com');
+     *
+     * @api
+     */
     public function setExternalUrl(string $url): self
     {
         $this->setValue('url', $url);
         return $this;
     }
-
-    /** @api */
-    public function getExternalLabel(): string
-    {
-        if ('' == $this->externalLabel) {
-            $this->externalLabel = rex_config::get('neues', 'default_url_label');
-        } else {
-            $this->getValue('url_Label');
-        }
-        return $this->externalLabel;
-    }
-
-    public function setExternalLabel(string $label): self
-    {
-        $this->setValue('url_label', $label);
-        return $this;
-    }
-
-    /** @api */
+    /**
+     * Gibt das Veröffentlichungsdatum des Eintrags zurück.
+     * Returns the publish date of the entry.
+     *
+     * @return string Das Veröffentlichungsdatum des Eintrags. / The publish date of the entry.
+     *
+     * Beispiel / Example:
+     * $publishDate = $entry->getPublishDate();
+     *
+     * @api
+     */
     public function getPublishDate(): string
     {
         return $this->getValue('publishdate');
     }
 
+    /**
+     * Setzt das Veröffentlichungsdatum des Eintrags.
+     * Sets the publish date of the entry.
+     *
+     * @param string $publishdate Das neue Veröffentlichungsdatum des Eintrags. / The new publish date of the entry.
+     * @return self
+     *
+     * Beispiel / Example:
+     * $entry = $entry->setPublishDate('2022-01-01');
+     *
+     * @api
+     */
     public function setPublishDate(string $publishdate): self
     {
         $this->setValue('publishdate', $publishdate);
         return $this;
     }
 
-    /** @api */
+    /**
+     * Gibt das formatierte Veröffentlichungsdatum des Eintrags zurück.
+     * Returns the formatted publish date of the entry.
+     *
+     * @param int $format_date Das Format des Datums. Standardmäßig IntlDateFormatter::FULL. / The format of the date. Defaults to IntlDateFormatter::FULL.
+     * @return string Das formatierte Veröffentlichungsdatum des Eintrags. / The formatted publish date of the entry.
+     *
+     * Beispiel / Example:
+     * $formattedPublishDate = $entry->getFormattedPublishDate(IntlDateFormatter::FULL);
+     *
+     * @api
+     */
     public function getFormattedPublishDate($format_date = IntlDateFormatter::FULL): string
     {
         return $this->getFormattedPublishDateTime([$format_date, IntlDateFormatter::NONE]);
     }
 
-    /** @api */
+    /**
+     * Gibt das formatierte Veröffentlichungsdatum und -zeit des Eintrags zurück.
+     * Returns the formatted publish date and time of the entry.
+     *
+     * @param array $format Das Format des Datums und der Zeit. Standardmäßig [IntlDateFormatter::FULL, IntlDateFormatter::SHORT]. / The format of the date and time. Defaults to [IntlDateFormatter::FULL, IntlDateFormatter::SHORT].
+     * @return string Das formatierte Veröffentlichungsdatum und -zeit des Eintrags. / The formatted publish date and time of the entry.
+     *
+     * Beispiel / Example:
+     * $formattedPublishDateTime = $entry->getFormattedPublishDateTime([IntlDateFormatter::FULL, IntlDateFormatter::SHORT]);
+     *
+     * @api
+     */
     public function getFormattedPublishDateTime($format = [IntlDateFormatter::FULL, IntlDateFormatter::SHORT]): string
     {
         return rex_formatter::intlDateTime($this->getPublishDate(), $format);
     }
-
-    /** @api */
+    /**
+     * Gibt den Status des Eintrags zurück.
+     * Returns the status of the entry.
+     *
+     * @return string Der Status des Eintrags. / The status of the entry.
+     *
+     * Beispiel / Example:
+     * $status = $entry->getStatus();
+     *
+     * @api
+     */
     public function getStatus(): string
     {
         return $this->getValue('status');
     }
 
+    /**
+     * Setzt den Status des Eintrags.
+     * Sets the status of the entry.
+     *
+     * @param int $status Der neue Status des Eintrags. / The new status of the entry.
+     * @return self
+     *
+     * Beispiel / Example:
+     * $entry = $entry->setStatus(1);
+     *
+     * @api
+     */
     public function setStatus(int $status): self
     {
         $this->setValue('status', $status);
         return $this;
     }
-
+    /**
+     * Findet Online-Einträge. Wenn eine Kategorie-ID angegeben ist, werden nur Einträge aus dieser Kategorie zurückgegeben.
+     * Finds online entries. If a category ID is provided, only entries from this category are returned.
+     *
+     * @param int|null $category_id Die ID der Kategorie. / The ID of the category.
+     * @return rex_yform_manager_collection|null Die gefundenen Einträge oder null, wenn keine Einträge gefunden wurden. / The found entries or null if no entries were found.
+     *
+     * Beispiel / Example:
+     * $entries = neues_entry::findOnline(1);
+     *
+     * @api
+     */
     public static function findOnline(?int $category_id = null): ?rex_yform_manager_collection
     {
         if ($category_id) {
@@ -226,13 +437,37 @@ public static function findOnline(?int $category_id = null): ?rex_yform_manager_
         return self::query()->where('status', 1, '>=')->find();
     }
 
+    /**
+     * Findet Einträge nach Kategorie.
+     * Finds entries by category.
+     *
+     * @param int|null $category_id Die ID der Kategorie. / The ID of the category.
+     * @param int $status Der Status der Einträge. / The status of the entries.
+     * @return rex_yform_manager_collection|null Die gefundenen Einträge oder null, wenn keine Einträge gefunden wurden. / The found entries or null if no entries were found.
+     *
+     * Beispiel / Example:
+     * $entries = neues_entry::findByCategory(1, 1);
+     *
+     * @api
+     */
     public static function findByCategory(?int $category_id = null, int $status = 1): ?rex_yform_manager_collection
     {
         $query = self::query()->joinRelation('category_ids', 'c')->where('rex_neues_entry.status', $status, '>=')->where('c.id', $category_id);
         return $query->find();
     }
 
-    /** @api */
+    /**
+     * Gibt die URL des Eintrags zurück.
+     * Returns the URL of the entry.
+     *
+     * @param string $profile Das Profil, das für die URL-Erstellung verwendet wird. Standardmäßig 'neues-entry-id'. / The profile used for URL creation. Defaults to 'neues-entry-id'.
+     * @return string Die URL des Eintrags oder ein leerer String, wenn keine URL gefunden wurde. / The URL of the entry or an empty string if no URL was found.
+     *
+     * Beispiel / Example:
+     * $url = $entry->getUrl('neues-entry-id');
+     *
+     * @api
+     */
     public function getUrl(string $profile = 'neues-entry-id'): string
     {
         if ($url = rex_getUrl(null, null, [$profile => $this->getId()])) {
diff --git a/lib/neues_entry_lang.php b/lib/neues_entry_lang.php
new file mode 100644
index 0000000..2009350
--- /dev/null
+++ b/lib/neues_entry_lang.php
@@ -0,0 +1,98 @@
+<?php
+/**
+ * Class neues_entry_lang.
+ *
+ * Diese Klasse repräsentiert einen neuen Eintrag.
+ * This class represents a new entry.
+ *
+ * Beispiel / Example:
+ * $entry = neues_entry_lang::get($id);
+ *
+ * @package rex_yform_manager_dataset
+ */
+class neues_entry_lang extends \rex_yform_manager_dataset
+{
+    /**
+     * Gibt die News-Einträge der aktuellen Sprache zurück.
+     * Returns the entries of the language.
+     *
+     * @return rex_yform_manager_collection|null Die Einträge der Sprache oder null, wenn keine Einträge gefunden wurden. / The entries of the language or null if no entries were found.
+     *
+     * Beispiel / Example:
+     * $entries = $language->getEntries();
+     *
+     * @api
+     */
+    public function getEntries() : ?rex_yform_manager_collection
+    {
+        return $this->getRelatedCollection("entry");
+    }
+
+    /**
+     * Gibt den Code der Sprache zurück.
+     * Returns the code of the language.
+     *
+     * @return string|null Der Code der Sprache oder null, wenn kein Code gesetzt ist. / The code of the language or null if no code is set.
+     *
+     * Beispiel / Example:
+     * $code = $language->getCode();
+     *
+     * @api
+     */
+    public function getCode() : ?string
+    {
+        return $this->getValue("code");
+    }
+
+    /**
+     * Setzt den Code der Sprache.
+     * Sets the code of the language.
+     *
+     * @param string $value Der neue Code der Sprache. / The new code of the language.
+     * @return self
+     *
+     * Beispiel / Example:
+     * $language = $language->setCode('Neuer Code');
+     *
+     * @api
+     */
+    public function setCode(string $value) : self
+    {
+        $this->setValue("code", $value);
+        return $this;
+    }
+
+    /**
+     * Gibt den Namen der Sprache zurück.
+     * Returns the name of the language.
+     *
+     * @return string Der Name der Sprache. / The name of the language.
+     *
+     * Beispiel / Example:
+     * $name = $language->getName();
+     *
+     * @api
+     */
+    public function getName() : string
+    {
+        return $this->getValue("name");
+    }
+
+    /**
+     * Setzt den Namen der Sprache.
+     * Sets the name of the language.
+     *
+     * @param string $value Der neue Name der Sprache. / The new name of the language.
+     * @return self
+     *
+     * Beispiel / Example:
+     * $language = $language->setName('Neuer Name');
+     *
+     * @api
+     */
+    public function setName(string $value) : self
+    {
+        $this->setValue("name", $value);
+        return $this;
+    }
+}