From 5a0c2d333ff41ec4da6a4d58bc1553beeee1affa Mon Sep 17 00:00:00 2001
From: rdalverny <rdalverny@gmail.com>
Date: Sat, 22 Jan 2022 19:53:01 +0100
Subject: More type hints

---
 Makefile                     |  3 ++-
 app/classes/Cache.php        | 38 ++++++++++++-----------------
 app/classes/Opml.php         |  8 +++---
 app/classes/OpmlManager.php  | 10 ++++++--
 app/classes/Planet.php       | 21 ++++++++++++----
 app/classes/PlanetConfig.php | 58 +++++++++++++++++++++-----------------------
 app/classes/PlanetError.php  | 16 +++++-------
 app/classes/PlanetFeed.php   | 20 +++++++--------
 app/classes/PlanetItem.php   |  4 +++
 app/classes/Simplel10n.php   |  2 +-
 app/helpers.php              |  4 +--
 11 files changed, 98 insertions(+), 86 deletions(-)

diff --git a/Makefile b/Makefile
index 7548027..2d5aa92 100644
--- a/Makefile
+++ b/Makefile
@@ -35,4 +35,5 @@ serve:
 
 clean:
 	rm -fr ./cache/*
-	rm -fr ./custom/config/*
\ No newline at end of file
+	rm -fr ./custom/config/*
+	rm -fr ./custom/config.* ./custom/people.*
diff --git a/app/classes/Cache.php b/app/classes/Cache.php
index c2e0c27..474c560 100644
--- a/app/classes/Cache.php
+++ b/app/classes/Cache.php
@@ -47,21 +47,18 @@ class Cache
 {
     /**
     * Whether caching is enabled
-    * @var bool
     */
-    public static $enabled = true;
+    public static bool $enabled = true;
 
     /**
     * Place to store the cache files
-    * @var string
     */
-    protected static $store = '/dev/shm/';
+    protected static string $store = '/dev/shm/';
         
     /**
     * Prefix to use on cache files
-    * @var string
     */
-    protected static $prefix = 'cache_';
+    protected static string $prefix = 'cache_';
 
     /**
     * Stores data
@@ -70,7 +67,7 @@ class Cache
     * @param string $id    Unique ID of this data
     * @param int    $ttl   How long to cache for (in seconds)
     */
-    protected static function write($group, $id, $ttl, $data)
+    protected static function write(string $group, string $id, int $ttl, string $data) : void
     {
         $filename = self::getFilename($group, $id);
             
@@ -91,7 +88,7 @@ class Cache
     * @param string $group Group to store data under
     * @param string $id    Unique ID of this data
     */
-    protected static function read($group, $id)
+    protected static function read($group, $id) : string
     {
         $filename = self::getFilename($group, $id);
             
@@ -104,7 +101,7 @@ class Cache
     * @param string $group Group to store data under
     * @param string $id    Unique ID of this data
     */
-    protected static function isCached($group, $id)
+    protected static function isCached($group, $id) : bool
     {
         $filename = self::getFilename($group, $id);
 
@@ -126,7 +123,7 @@ class Cache
     * @param string $group Group to store data under
     * @param string $id    Unique ID of this data
     */
-    protected static function getFilename($group, $id)
+    protected static function getFilename(string $group, string $id) : string
     {
         $id = md5($id);
 
@@ -138,7 +135,7 @@ class Cache
     *
     * @param string $prefix Filename Prefix to use
     */
-    public static function setPrefix($prefix)
+    public static function setPrefix($prefix) : void
     {
         self::$prefix = $prefix;
     }
@@ -149,7 +146,7 @@ class Cache
     *
     * @param string $store The dir to store the cache data in
     */
-    public static function setStore($store)
+    public static function setStore($store) : void
     {
         self::$store = $store;
     }
@@ -162,21 +159,18 @@ class OutputCache extends Cache
 {
     /**
     * Group of currently being recorded data
-    * @var string
     */
-    private static $group;
+    private static string $group;
         
     /**
     * ID of currently being recorded data
-    * @var string
     */
-    private static $id;
+    private static string $id;
         
     /**
     * Ttl of currently being recorded data
-    * @var int
     */
-    private static $ttl;
+    private static int $ttl;
 
     /**
     * Starts caching off. Returns true if cached, and dumps
@@ -187,7 +181,7 @@ class OutputCache extends Cache
     * @param  int    $ttl   How long to cache for (in seconds)
     * @return bool          True if cached, false if not
     */
-    public static function Start($group, $id, $ttl)
+    public static function Start($group, $id, $ttl) : bool
     {
         if (self::isCached($group, $id)) {
             echo self::read($group, $id);
@@ -206,7 +200,7 @@ class OutputCache extends Cache
     /**
     * Ends caching. Writes data to disk.
     */
-    public static function End()
+    public static function End() : void
     {
         $data = ob_get_contents();
         ob_end_flush();
@@ -228,7 +222,7 @@ class DataCache extends Cache
     * @param  string $id    Unique ID of the data
     * @return mixed         Either the resulting data, or null
     */
-    public static function Get($group, $id)
+    public static function Get($group, $id) : mixed
     {
         if (self::isCached($group, $id)) {
             return unserialize(self::read($group, $id));
@@ -245,7 +239,7 @@ class DataCache extends Cache
     * @param int    $ttl   How long to cache for (in seconds)
     * @param mixed  $data  The data to store
     */
-    public static function Put($group, $id, $ttl, $data)
+    public static function Put($group, $id, $ttl, $data) : void
     {
         self::write($group, $id, $ttl, serialize($data));
     }
diff --git a/app/classes/Opml.php b/app/classes/Opml.php
index b91b43e..4920af1 100644
--- a/app/classes/Opml.php
+++ b/app/classes/Opml.php
@@ -14,8 +14,10 @@ class Opml
 
     public string $title = '';
 
-    /** @var array<int, string> */
+    /** @var array<int, array<mixed>> */
     public $entries = array();
+
+    /** @var array<string, string> */
     private $map  =
         array(
             'URL'         => 'website',
@@ -30,7 +32,7 @@ class Opml
 
     /**
      * @param string $data
-     * @return array<int, string>
+     * @return array<int, array<mixed>>
     */
     public function parse(string $data) : array
     {
@@ -99,7 +101,7 @@ class Opml
     }
 
     /**
-     * @return array<int, string>
+     * @return array<int, array<mixed>>
     */
     public function getPeople() : array
     {
diff --git a/app/classes/OpmlManager.php b/app/classes/OpmlManager.php
index 679d1c4..d7e7895 100644
--- a/app/classes/OpmlManager.php
+++ b/app/classes/OpmlManager.php
@@ -22,7 +22,13 @@ class OpmlManager
         return $opml;
     }
 
-    public static function format(Opml $opml, $freezeDateModified = false) : string
+    /**
+     *
+     * @param  Opml $opml object
+     * @param  boolean $freezeDateModified update (or not) the dateModified entry - used for tests only
+     * @return string  OPML valid string
+     */
+    public static function format(Opml $opml, bool $freezeDateModified = false) : string
     {
         $owner = '';
         if ($opml->ownerName != '') {
@@ -81,7 +87,7 @@ XML;
         return file_put_contents($file, self::format($opml));
     }
 
-    public static function backup($file)
+    public static function backup(string $file) : void
     {
         copy($file, $file.'.bak');
     }
diff --git a/app/classes/Planet.php b/app/classes/Planet.php
index 1555c25..0bb4b32 100644
--- a/app/classes/Planet.php
+++ b/app/classes/Planet.php
@@ -75,13 +75,13 @@ class Planet
      * @param  string $supplied
      * @return bool
      */
-    public static function authenticateUser(string $known = '', string $supplied = '')
+    public static function authenticateUser(string $known = '', string $supplied = '') : bool
     {
         return hash_equals($known, $supplied);
     }
 
     /**
-     * @return array $items
+     * @return array<PlanetItem> $items
      */
     public function getFeedsItems()
     {
@@ -95,6 +95,8 @@ class Planet
 
     /**
      * Getters
+     *
+     * @return array<int, PlanetItem>
      */
     public function getItems()
     {
@@ -106,6 +108,9 @@ class Planet
         return $this->items;
     }
 
+    /**
+     * @return array<PlanetFeed>
+     */
     public function getPeople()
     {
         return $this->people;
@@ -115,6 +120,7 @@ class Planet
      * Adds a feed to the planet.
      *
      * @param PlanetFeed $feed
+     * @return void
      */
     public function addPerson(&$feed)
     {
@@ -150,6 +156,7 @@ class Planet
 
     /**
      * Load feeds
+     * @return void
      */
     public function loadFeeds()
     {
@@ -168,6 +175,7 @@ class Planet
      * Fetch feeds and see if new data is present.
      *
      * @param float $max_load Percentage of feeds to load
+     * @return void
      */
     public function download($max_load = 0.1)
     {
@@ -215,6 +223,9 @@ class Planet
         OpmlManager::save($opml, $this->config->getOpmlFile());
     }
 
+    /**
+     * @return void
+     */
     public function sort()
     {
         usort($this->items, array('PlanetItem','compare'));
@@ -226,13 +237,13 @@ class Planet
      *
      * If there's no category, return all items.
      *
-     * @param array  $items to filter
+     * @param array<PlanetItem>  $items to filter
      * @param string $categories to filter against; may be a single word
      * or a comma-separated list of words.
      *
-     * @return array resulting list of items
+     * @return array<PlanetItem> resulting list of items
     */
-    public function _filterItemsByCategory($items, $categories = null)
+    public function _filterItemsByCategory(array $items, string $categories = null)
     {
         if (is_null($categories) or empty(trim($categories))) {
             return $items;
diff --git a/app/classes/PlanetConfig.php b/app/classes/PlanetConfig.php
index 6094956..25b438d 100644
--- a/app/classes/PlanetConfig.php
+++ b/app/classes/PlanetConfig.php
@@ -6,11 +6,13 @@
 class PlanetConfig
 {
 
+    /** @var array<string, mixed> */
     protected $conf = [];
 
     private ?string $opmlFile = null;
     private ?string $cacheDir = null;
 
+    /** @var array<string, mixed> */
     public static $defaultConfig = [
         'url'           => 'http://www.example.com/',
         'name'          => '',
@@ -26,7 +28,7 @@ class PlanetConfig
 
     /**
      * PlanetConfig constructor.
-     * @param array $userConfig
+     * @param array<string, mixed> $userConfig
      * @param bool  $useDefaultConfig
      */
     public function __construct($userConfig = [], $useDefaultConfig = true)
@@ -36,9 +38,8 @@ class PlanetConfig
     }
 
     /**
-     * @return static
      */
-    public static function load(string $dir)
+    public static function load(string $dir) : PlanetConfig
     {
         $config = new PlanetConfig;
 
@@ -108,7 +109,7 @@ class PlanetConfig
             self::migrate_file('people.opml');
     }
 
-    public static function migrate_file($file) : bool
+    public static function migrate_file(string $file) : bool
     {
         $source = custom_path($file);
         $dest = config_path($file);
@@ -127,36 +128,36 @@ class PlanetConfig
     /**
      * Merge the configuration of the user in the default one.
      *
-     * @param array $default
-     * @param array $user
-     * @return array
+     * @param array<string, mixed> $default
+     * @param array<string, mixed> $user
+     * @return array<string, mixed>
      */
     protected function merge($default = [], $user = [])
     {
         return array_merge($default, $this->normalizeArrayKeys($user));
     }
 
-    public function getUrl()
+    public function getUrl() : string
     {
         return $this->conf['url'];
     }
 
-    public function getName()
+    public function getName() : string
     {
         return $this->conf['name'];
     }
 
-    public function setName($name)
+    public function setName(string $name) : void
     {
         $this->conf['name'] = $name;
     }
 
-    public function getCacheTimeout()
+    public function getCacheTimeout() : int
     {
         return $this->conf['refresh'];
     }
 
-    public function getCacheDir()
+    public function getCacheDir() : string
     {
         if (is_null($this->cacheDir)) {
             $this->cacheDir = realpath(__DIR__ . '/../../'.$this->conf['cachedir']);
@@ -164,7 +165,7 @@ class PlanetConfig
         return $this->cacheDir;
     }
 
-    public function getOpmlFile()
+    public function getOpmlFile() : string
     {
         if (is_null($this->opmlFile)) {
             $this->opmlFile = realpath(config_path('people.opml'));
@@ -172,51 +173,51 @@ class PlanetConfig
         return $this->opmlFile;
     }
 
-    public function getOutputTimeout()
+    public function getOutputTimeout() : int
     {
         return $this->conf['cache'];
     }
 
-    public function getMaxDisplay()
+    public function getMaxDisplay() : int
     {
         return $this->conf['items'];
     }
 
-    public function getCategories()
+    public function getCategories() : string
     {
         return $this->conf['categories'];
     }
 
-    public function toYaml()
+    public function toYaml() : string
     {
         return Spyc::YAMLDump($this->conf, 4);
     }
 
     /**
-     * @return array
+     * @return array<string, mixed>
      */
     public function toArray()
     {
         return $this->conf;
     }
 
-    public function getDebug()
+    public function getDebug() : bool
     {
         return $this->conf['debug'];
     }
 
-    public function checkCertificates()
+    public function checkCertificates() : bool
     {
         return $this->conf['checkcerts'];
     }
 
-    public function getLocale()
+    public function getLocale() : string
     {
         return $this->conf['locale'];
     }
 
     /**
-     * @return array
+     * @return array<string, mixed>
      */
     public function getDefaultConfig()
     {
@@ -229,7 +230,7 @@ class PlanetConfig
      * @param  string $key
      * @return string
      */
-    protected function normalizeKeyName($key = null)
+    protected function normalizeKeyName(string $key) : string
     {
         return strtolower($key);
     }
@@ -237,8 +238,8 @@ class PlanetConfig
     /**
      * Normalize all the keys of the array.
      *
-     * @param  array $array
-     * @return array
+     * @param  array<string, mixed> $array
+     * @return array<string, mixed>
      */
     protected function normalizeArrayKeys($array = [])
     {
@@ -258,7 +259,7 @@ class PlanetConfig
      *
      * @return mixed|null
      */
-    public function __get($key)
+    public function __get(string $key)
     {
         $key = $this->normalizeKeyName($key);
 
@@ -269,11 +270,8 @@ class PlanetConfig
 
     /**
      * Generic configuration setter.
-     *
-     * @param $key
-     * @param $value
      */
-    public function __set($key, $value)
+    public function __set(string $key, mixed $value) : void
     {
         $key = $this->normalizeKeyName($key);
 
diff --git a/app/classes/PlanetError.php b/app/classes/PlanetError.php
index e47ab1d..a7d2a63 100644
--- a/app/classes/PlanetError.php
+++ b/app/classes/PlanetError.php
@@ -2,30 +2,26 @@
 
 class PlanetError
 {
-    public $level;
+    public int $level;
+
+    /** @var array<int, string> */
     public $levels = array(
         1 => 'notice',
         2 => 'warning',
         3 => 'error',
     );
-    public $message;
+    public string $message;
 
     /**
      * PlanetError constructor.
-     * @param $level
-     * @param $message
      */
-    public function __construct($level, $message)
+    public function __construct(int $level, string $message)
     {
         $this->level = (int) $level;
         $this->message = $message;
     }
 
-    /**
-     * @param  string $format
-     * @return string
-     */
-    public function toString($format = '%1$s: %2$s')
+    public function toString(string $format = '%1$s: %2$s') : string
     {
         return sprintf($format, $this->levels[$this->level], $this->message);
     }
diff --git a/app/classes/PlanetFeed.php b/app/classes/PlanetFeed.php
index 6cd6b08..39fbe75 100644
--- a/app/classes/PlanetFeed.php
+++ b/app/classes/PlanetFeed.php
@@ -6,10 +6,10 @@
 
 class PlanetFeed extends SimplePie
 {
-    public $name;
-    public $feed;
-    public $website;
-    public $isDown;
+    public string $name;
+    public string $feed;
+    public string $website;
+    public string $isDown;
 
     public function __construct($name, $feed, $website, $isDown)
     {
@@ -46,22 +46,22 @@ class PlanetFeed extends SimplePie
         ]);
     }
 
-    public function getFeed()
+    public function getFeed() : string
     {
         return $this->feed;
     }
 
-    public function getName()
+    public function getName() : string
     {
         return $this->name;
     }
 
-    public function getWebsite()
+    public function getWebsite() : string
     {
         return $this->website;
     }
 
-    public function getIsDown()
+    public function getIsDown() : string
     {
         return $this->isDown;
     }
@@ -69,8 +69,8 @@ class PlanetFeed extends SimplePie
     /**
      * Compare two Person by their name.
      *
-     * @param  $person1
-     * @param  $person2
+     * @param  PlanetFeed $person1
+     * @param  PlanetFeed $person2
      * @return int
      */
     public static function compare($person1, $person2)
diff --git a/app/classes/PlanetItem.php b/app/classes/PlanetItem.php
index 7d55781..ae97db0 100644
--- a/app/classes/PlanetItem.php
+++ b/app/classes/PlanetItem.php
@@ -6,6 +6,10 @@
 
 class PlanetItem extends SimplePie_Item
 {
+    /**
+     * @param SimplePie $feed
+     * @param string $data
+     */
     public function __construct($feed, $data)
     {
         parent::__construct($feed, $data);
diff --git a/app/classes/Simplel10n.php b/app/classes/Simplel10n.php
index f84ef5c..a8660f0 100755
--- a/app/classes/Simplel10n.php
+++ b/app/classes/Simplel10n.php
@@ -20,7 +20,7 @@ class Simplel10n
         $this->l10nFolder = $path;
     }
 
-    public static function getString($str, $comment = '')
+    public static function getString(string $str, string $comment = '')
     {
         if (array_key_exists($str, $GLOBALS['locale'])) {
             return trim(str_replace('{ok}', '', $GLOBALS['locale'][$str]));
diff --git a/app/helpers.php b/app/helpers.php
index 24f9d38..85c63a3 100644
--- a/app/helpers.php
+++ b/app/helpers.php
@@ -7,7 +7,7 @@
  * is available, and we won't force the use of our own
  * implementation.
  */
-function register_polyfills()
+function register_polyfills() : void
 {
 }
 
@@ -88,7 +88,7 @@ function _g($str, $comment = '')
 /**
  * Reset the moonmoon instance.
  */
-function removeCustomFiles()
+function removeCustomFiles() : void
 {
     $toRemove = [
         config_path('config.yml'),
-- 
cgit v1.2.1