Add phpstan type to NewsHandler

Author: markrandall

src/News/NewsHandler.php

@@ -5,15 +5,41 @@
 namespace phpweb\News;
 
 use DateTimeImmutable;
-
 use function array_filter;
 use function array_values;
 use function is_array;
 
+/**
+ * @phpstan-type NewsEntryStruct array{
+ *     title: string,
+ *     id: string,
+ *     published: string,
+ *     updated: string,
+ *     link?: list<array{
+ *        href: string,
+ *        rel: string,
+ *        type?: string,
+ *     }>,
+ *     category: list<array{
+ *         term: string,
+ *         label: string,
+ *     }>,
+ *     newsImage?: array{
+ *         link: string,
+ *         content: string,
+ *     },
+ *     content: string,
+ *     intro?: string,
+ *     finalTeaserDate?: string,
+ * }
+ */
 final class NewsHandler
 {
     private const MAX_FRONT_PAGE_NEWS = 25;
 
+    /**
+     * @return NewsEntryStruct|null
+     */
     public function getLastestNews(): array|null
     {
         $news = $this->getPregeneratedNews();
@@ -24,8 +50,14 @@ public function getLastestNews(): array|null
         return $news[0];
     }
 
-    /** @return list<array> */
-    public function getFrontPageNews(): array
+    /**
+     * Unused - Looks up generated news with frontpage tags.
+     *
+     * Currently unused as the front page no longer displays news.
+     *
+     * @return list<NewsEntryStruct>
+     */
+    public function getFrontPageNews(int $limit = self::MAX_FRONT_PAGE_NEWS): array
     {
         $frontPage = [];
         foreach ($this->getPregeneratedNews() as $entry) {
@@ -35,7 +67,7 @@ public function getFrontPageNews(): array
                 }
 
                 $frontPage[] = $entry;
-                if (count($frontPage) >= self::MAX_FRONT_PAGE_NEWS) {
+                if (count($frontPage) >= $limit) {
                     break 2;
                 }
             }
@@ -44,7 +76,9 @@ public function getFrontPageNews(): array
         return $frontPage;
     }
 
-    /** @return list<array> */
+    /**
+     * @return list<NewsEntryStruct>
+     */
     public function getConferences(): array
     {
         $conferences = [];
@@ -62,7 +96,9 @@ public function getConferences(): array
         return $conferences;
     }
 
-    /** @return list<array> */
+    /**
+     * @return list<NewsEntryStruct>
+     */
     public function getNewsByYear(int $year): array
     {
         return array_values(array_filter(
@@ -71,11 +107,46 @@ public function getNewsByYear(int $year): array
         ));
     }
 
+    /**
+     * @return list<NewsEntryStruct>
+     */
     public function getPregeneratedNews(): array
     {
         $NEWS_ENTRIES = null;
         include __DIR__ . '/../../include/pregen-news.inc';
 
+        /** @phpstan-ignore-next-line - pregen-news sets global variable */
         return is_array($NEWS_ENTRIES) ? $NEWS_ENTRIES : [];
     }
+
+
+    /**
+     * @param NewsEntryStruct $data
+     */
+    public static function parseTeaserCutoff(array $data): ?DateTimeImmutable
+    {
+        $finalTeaserDate = $data['finalTeaserDate'] ?? null;
+        if (!$finalTeaserDate) {
+            return null;
+        }
+
+        return new DateTimeImmutable($finalTeaserDate);
+    }
+
+    /**
+     * @param NewsEntryStruct $data
+     * @param list<string>|string $tags
+     */
+    public static function isTagged(array $data, array|string $tags): bool
+    {
+        $tags = is_array($tags) ? $tags : [$tags];
+
+        foreach ($data['category'] as $category) {
+            if (in_array($category['term'], $tags, true)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
 }