Merge pull request #11 from AntCMS-org/docsandtypehints

Added missing type hints, bumped PHPStan to level 6

phpstan.neon

@@ -1,5 +1,5 @@
 parameters:
-	level: 5
+	level: 6
 	paths:
 		- src
 	excludePaths:

src/AntCMS/AntAuth.php

@@ -6,6 +6,13 @@ use AntCMS\AntConfig;
 
 class AntAuth
 {
+    /**
+     * Check if the user is authenticated using the credentials in the config file.
+     * If the plain text password in the config file is still present, it will be hashed and the config file will be updated.
+     * If the user is not authenticated, it will call AntAuth::requireAuth()
+     *
+     * @return void
+     */
     public static function checkAuth()
     {
         $currentConfig = AntConfig::currentConfig();
@@ -23,13 +30,18 @@ class AntAuth
 
             //Now, we can perform the check as normal
             if ($currentConfig['admin']['username'] == $_SERVER['PHP_AUTH_USER'] && password_verify($_SERVER['PHP_AUTH_PW'], $currentConfig['admin']['password'])) {
-                return true;
+                return;
             }
         }
 
         AntAuth::requireAuth();
     }
 
+    /**
+     * Send an authentication challenge to the browser, with the realm set to the site title in config.
+     *
+     * @return void
+     */
     private static function requireAuth()
     {
         $currentConfig = AntConfig::currentConfig();

src/AntCMS/AntCMS.php

@@ -9,7 +9,13 @@ use AntCMS\AntConfig;
 
 class AntCMS
 {
-    public function renderPage($page, $params = null)
+    /**
+     * Renders a page based on the provided page name.
+     *
+     * @param string $page The name of the page to be rendered
+     * @return string The rendered HTML of the page
+     */
+    public function renderPage(string $page)
     {
         $start_time = microtime(true);
         $content = $this->getPage($page);
@@ -42,7 +48,13 @@ class AntCMS
         return $pageTemplate;
     }
 
-    public function getPageLayout($theme = null)
+    /**
+     * Returns the default layout of the active theme unless otherwise specified.
+     * 
+     * @param string|null $theme optional - the theme to get the page layout for.
+     * @return string the default page layout
+     */
+    public function getPageLayout(string $theme = null)
     {
         $siteInfo = AntCMS::getSiteInfo();
 
@@ -55,7 +67,13 @@ class AntCMS
         return $pageTemplate;
     }
 
-    public function renderException($exceptionCode)
+    /**
+     * Render an exception page with the provided exception code.
+     * 
+     * @param string $exceptionCode The exception code to be displayed on the error page
+     * @return never 
+     */
+    public function renderException(string $exceptionCode)
     {
         $pageTemplate = $this->getPageLayout();
 
@@ -66,7 +84,11 @@ class AntCMS
         exit;
     }
 
-    public function getPage($page)
+    /**
+     * @param string $page 
+     * @return array<mixed>|false 
+     */
+    public function getPage(string $page)
     {
         $page = strtolower($page);
         $pagePath = AntDir . "/Content/$page";
@@ -94,7 +116,12 @@ class AntCMS
         }
     }
 
-    public function getThemeTemplate($layout = 'default_layout', $theme = null)
+    /**
+     * @param string $layout 
+     * @param string|null $theme 
+     * @return string 
+     */
+    public function getThemeTemplate(string $layout = 'default_layout', string $theme = null)
     {
         $theme = $theme ?? AntConfig::currentConfig('activeTheme');
 
@@ -142,7 +169,11 @@ class AntCMS
         return $template;
     }
 
-    public static function getPageHeaders($pageContent)
+    /**
+     * @param string $pageContent 
+     * @return array<mixed> 
+     */
+    public static function getPageHeaders(string $pageContent)
     {
         $AntKeywords = new AntKeywords();
 
@@ -178,12 +209,19 @@ class AntCMS
         return $pageHeaders;
     }
 
+    /**
+     * @return mixed
+     */
     public static function getSiteInfo()
     {
         return AntConfig::currentConfig('SiteInfo');
     }
 
-    public function serveContent($path)
+    /**
+     * @param string $path 
+     * @return void 
+     */
+    public function serveContent(string $path)
     {
         if (!file_exists($path)) {
             $this->renderException('404');

src/AntCMS/AntCache.php

@@ -10,12 +10,12 @@ class AntCache
     /**
      * Caches a value for a given cache key.
      * 
-     * @param mixed $key The cache key to use for the cached value.
-     * @param mixed $content The value to cache.
+     * @param string $key The cache key to use for the cached value.
+     * @param string $content The value to cache.
      * @return bool True if the value was successfully cached, false otherwise.
      * @throws ParseException If there is an error parsing the AntCMS configuration file.
      */
-    public function setCache($key, $content)
+    public function setCache(string $key, string $content)
     {
         $cachePath = AntCachePath . DIRECTORY_SEPARATOR . "$key.cache";
         $config = AntConfig::currentConfig();
@@ -34,11 +34,11 @@ class AntCache
     /**
      * Retrieves the cached value for a given cache key.
      * 
-     * @param mixed $key The cache key used to retrieve the cached value.
+     * @param string $key The cache key used to retrieve the cached value.
      * @return string|false The cached value, or false if there was an error loading it or if caching is disabled.
      * @throws ParseException If there is an error parsing the AntCMS configuration file.
      */
-    public function getCache($key)
+    public function getCache(string $key)
     {
         $cachePath = AntCachePath . DIRECTORY_SEPARATOR . "$key.cache";
         $config = AntConfig::currentConfig();
@@ -61,7 +61,7 @@ class AntCache
      * @return bool True if the cache key has a corresponding cached value, false otherwise. Will also return false if caching is disabled.
      * @throws ParseException If there is an error parsing the AntCMS configuration file.
      */
-    public function isCached($key)
+    public function isCached(string $key)
     {
         $config = AntConfig::currentConfig();
         if ($config['enableCache']) {
@@ -76,11 +76,11 @@ class AntCache
      * Generates a unique cache key for the associated content and a salt value.
      * The salt is used to ensure that each cache key is unique to each component, even if multiple components are using the same source content but caching different results.
      * 
-     * @param mixed $content The content to generate a cache key for.
+     * @param string $content The content to generate a cache key for.
      * @param string $salt An optional salt value to use in the cache key generation. Default is 'cache'.
      * @return string The generated cache key.
      */
-    public function createCacheKey($content, $salt = 'cache')
+    public function createCacheKey(string $content, string $salt = 'cache')
     {
         /**
          * If the server is modern enough to have xxh128, use that. It is really fast and still produces long hashes

src/AntCMS/AntConfig.php

@@ -37,7 +37,7 @@ class AntConfig
      * @param string|null $key The key of the configuration item to retrieve. Use dot notation to specify nested keys.
      * @return mixed The configuration array or a specific value if the key is specified.
      */
-    public static function currentConfig($key = null)
+    public static function currentConfig(?string $key = null)
     {
         $config = AntYaml::parseFile(antConfigFile);
         if (is_null($key)) {
@@ -49,7 +49,12 @@ class AntConfig
     }
 
 
-    private static function getArrayValue($array, $keys)
+    /**
+     * @param array<mixed> $array 
+     * @param array<mixed> $keys 
+     * @return mixed 
+     */
+    private static function getArrayValue(array $array, array $keys)
     {
         foreach ($keys as $k) {
             if (isset($array[$k])) {
@@ -64,10 +69,10 @@ class AntConfig
     /**
      * Saves the AntCMS configuration
      * 
-     * @param array $config The config data to be saved.
+     * @param array<mixed> $config The config data to be saved.
      * @return void
      */
-    public static function saveConfig($config)
+    public static function saveConfig(array $config)
     {
         AntYaml::saveFile(antConfigFile, $config);
     }

src/AntCMS/AntKeywords.php

@@ -7,7 +7,12 @@ use AntCMS\AntConfig;
 
 class AntKeywords
 {
-    public function generateKeywords($content = '', $count = 15)
+    /**
+     * @param string $content 
+     * @param int $count 
+     * @return string 
+     */
+    public function generateKeywords(string $content = '', int $count = 15)
     {
         $cache = new AntCache();
         $cacheKey = $cache->createCacheKey($content, 'keywords');

src/AntCMS/AntMarkdown.php

@@ -15,7 +15,11 @@ use ElGigi\CommonMarkEmoji\EmojiExtension;
 
 class AntMarkdown
 {
-    public static function renderMarkdown($md)
+    /**
+     * @param string $md 
+     * @return string 
+     */
+    public static function renderMarkdown(string $md)
     {
         $cache = new AntCache();
         $cacheKey = $cache->createCacheKey($md, 'markdown');

src/AntCMS/AntPages.php

@@ -11,6 +11,7 @@ use AntCMS\AntTwig;
 
 class AntPages
 {
+    /** @return void  */
     public static function generatePages()
     {
         $pages = AntTools::getFileList(antContentPath, 'md', true);
@@ -32,12 +33,17 @@ class AntPages
         AntYaml::saveFile(antPagesList, $pageList);
     }
 
+    /** @return array<mixed>  */
     public static function getPages()
     {
         return AntYaml::parseFile(antPagesList);
     }
 
-    public static function generateNavigation($navTemplate = '')
+    /**
+     * @param string $navTemplate 
+     * @return string 
+     */
+    public static function generateNavigation(string $navTemplate = '')
     {
         $pages = AntPages::getPages();
         $cache = new AntCache;

src/AntCMS/AntPlugin.php

@@ -4,10 +4,15 @@ namespace AntCMS;
 
 abstract class AntPlugin
 {
+    /**
+     * @param array<string> $route 
+     * @return mixed 
+     */
     public function handlePluginRoute(array $route)
     {
         die("Plugin did not define a handlePluginRoute function");
     }
 
+    /** @return string  */
     abstract function getName();
 }

src/AntCMS/AntPluginLoader.php

@@ -6,6 +6,7 @@ use AntCMS\AntTools;
 
 class AntPluginLoader
 {
+    /** @return array<mixed>  */
     public function loadPlugins()
     {
         $plugins = array();

src/AntCMS/AntTools.php

@@ -4,7 +4,13 @@ namespace AntCMS;
 
 class AntTools
 {
-    public static function getFileList($dir, $extension = null, $returnPath = false)
+    /**
+     * @param string $dir 
+     * @param (null|string)|null $extension 
+     * @param null|bool $returnPath 
+     * @return array<string> 
+     */
+    public static function getFileList(string $dir, ?string $extension = null, ?bool $returnPath = false)
     {
         $dir = new \RecursiveDirectoryIterator($dir);
         $iterator = new \RecursiveIteratorIterator($dir);
@@ -17,7 +23,11 @@ class AntTools
         return $files;
     }
 
-    public static function repairFilePath($path)
+    /**
+     * @param string $path 
+     * @return string 
+     */
+    public static function repairFilePath(string $path)
     {
         $newPath = realpath($path);
         if (!$newPath) {
@@ -30,20 +40,18 @@ class AntTools
         return $newPath;
     }
 
+    /**
+     * Repairs a URL by replacing backslashes with forward slashes and removing duplicate slashes.
+     *
+     * @param string $url The URL to repair. Note: this function will not work correctly if the URL provided has its own protocol (like HTTS://).
+     * @return string The repaired URL
+     */
+    public static function repairURL(string $url)
+    {
+        $newURL = str_replace('\\\\', '/', $url);
+        $newURL = str_replace('\\', '/', $newURL);
+        $newURL = str_replace('//', '/', $newURL);
 
-/**
- * Repairs a URL by replacing backslashes with forward slashes and removing duplicate slashes.
- *
- * @param string $url The URL to repair. Note: this function will not work correctly if the URL provided has its own protocol (like HTTS://).
- * @return string The repaired URL
- */
-public static function repairURL($url)
-{
-    $newURL = str_replace('\\\\', '/', $url);
-    $newURL = str_replace('\\', '/', $newURL);
-    $newURL = str_replace('//', '/', $newURL);
-
-    return $newURL;
-}
-
+        return $newURL;
+    }
 }

src/AntCMS/AntTwig.php

@@ -6,6 +6,12 @@ use AntCMS\AntConfig;
 
 class AntTwig
 {
+    /**
+     * @param string $content 
+     * @param array<mixed> $params 
+     * @param string|null $theme 
+     * @return string 
+     */
     public function renderWithTiwg(string $content = '', array $params = array(), string $theme = null)
     {
         $twigCache = AntConfig::currentConfig('enableCache') ? AntCachePath : false;

src/AntCMS/AntYaml.php

@@ -7,18 +7,31 @@ use Symfony\Component\Yaml\Yaml;
 
 class AntYaml
 {
-    public static function parseFile($file)
+    /**
+     * @param string $file 
+     * @return array<mixed> 
+     */
+    public static function parseFile(string $file)
     {
         return Yaml::parseFile($file);
     }
 
-    public static function saveFile($file, $data)
+    /**
+     * @param string $file 
+     * @param array<mixed> $data 
+     * @return void 
+     */
+    public static function saveFile(string $file, array $data)
     {
         $yaml = Yaml::dump($data);
         file_put_contents($file, $yaml);
     }
 
-    public static function parseYaml($yaml){
+    /**
+     * @param string $yaml 
+     * @return array<mixed>|null 
+     */
+    public static function parseYaml(string $yaml){
         try {
             return Yaml::parse($yaml);
         } catch (ParseException $exception) {

src/Plugins/Admin/AdminPlugin.php

@@ -11,6 +11,10 @@ use AntCMS\AntTwig;
 
 class AdminPlugin extends AntPlugin
 {
+    /**
+     * @param array<string> $route 
+     * @return void
+     */
     public function handlePluginRoute(array $route)
     {
         AntAuth::checkAuth();
@@ -23,11 +27,9 @@ class AdminPlugin extends AntPlugin
         switch ($currentStep) {
             case 'config':
                 $this->configureAntCMS($route);
-                break;
 
             case 'pages':
                 $this->managePages($route);
-                break;
 
             default:
                 $antTwig = new AntTwig;
@@ -49,11 +51,16 @@ class AdminPlugin extends AntPlugin
         }
     }
 
+    /** @return string  */
     public function getName()
     {
         return 'Admin';
     }
 
+    /**
+     * @param array<string> $route 
+     * @return never 
+     */
     private function configureAntCMS(array $route)
     {
         $antCMS = new AntCMS;
@@ -113,6 +120,10 @@ class AdminPlugin extends AntPlugin
         exit;
     }
 
+    /**
+     * @param array<string> $route 
+     * @return never 
+     */
     private function managePages(array $route)
     {
         $antCMS = new AntCMS;
@@ -199,7 +210,11 @@ class AdminPlugin extends AntPlugin
         exit;
     }
 
-    private function boolToWord($value)
+    /**
+     * @param bool $value 
+     * @return string 
+     */
+    private function boolToWord(bool $value)
     {
         return boolval($value) ? 'true' : 'false';
     }

src/cron.php

@@ -1,5 +1,5 @@
 <?php
-$cacheFiles = glob(__DIR__ . DIRECTORY_SEPARATOR . 'Cache' . DIRECTORY_SEPARATOR . '*.cache');
+$cacheFiles = glob(__DIR__ . DIRECTORY_SEPARATOR . 'Cache' . DIRECTORY_SEPARATOR . '*.*');
 foreach($cacheFiles as $cacheFile){
   if(is_file($cacheFile)) {
     unlink($cacheFile);