DRAFT: Raise the modules' PHPStan level from 0 to 1

.github/workflows/code-quality.yaml

@@ -37,6 +37,29 @@ jobs:
       - name: Run code quality checks (on pull request)
         if: github.event_name == 'pull_request'
         run: ./.github/workflows/utilities/phpcs-pr ${{ github.base_ref }}
+  staticAnalysis:
+    runs-on: ubuntu-latest
+    name: PHPStan
+    steps:
+      - name: Checkout changes
+        uses: actions/checkout@v7
+
+      - name: Install PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: 8.2
+          extensions: curl, fileinfo, gd, mbstring, openssl, pdo, pdo_sqlite, sqlite3, xml, zip
+
+      - name: Install Composer dependencies
+        run: composer install --no-interaction --no-progress --no-scripts
+
+      - name: Reset modules
+        run: |
+          git reset --hard
+          git clean -fd
+
+      - name: Run static analysis
+        run: vendor/bin/phpstan analyse --no-progress --memory-limit=2G
   codeQualityJS:
     runs-on: ubuntu-latest
     name: JavaScript

composer.json

@@ -43,7 +43,8 @@
         "fakerphp/faker": "^1.9.2",
         "squizlabs/php_codesniffer": "^3.2",
         "php-parallel-lint/php-parallel-lint": "^1.0",
-        "dms/phpunit-arraysubset-asserts": "dev-add-phpunit-11-support"
+        "dms/phpunit-arraysubset-asserts": "dev-add-phpunit-11-support",
+        "larastan/larastan": "^3.6"
     },
      "repositories": [
         {

modules/backend/classes/Controller.php

@@ -307,6 +307,8 @@ public function run($action = null, $params = [])
          */
         $this->setNavigationContext($action, $params);
 
+        $result = null;
+
         /*
          * Execute AJAX event
          */

modules/backend/classes/FilterScope.php

@@ -56,6 +56,11 @@ class FilterScope
      */
     public $dependsOn;
 
+    /**
+     * @var mixed Default value for this filter scope.
+     */
+    public $default;
+
     /**
      * @var string Specifies contextual visibility of this form scope.
      */

modules/backend/classes/FormTabs.php

@@ -203,7 +203,7 @@ public function getAllFields()
     /**
      * Returns an icon for the tab based on the tab's name.
      * @param string $name
-     * @return string
+     * @return string|null
      */
     public function getIcon($name)
     {
@@ -216,7 +216,7 @@ public function getIcon($name)
      * Returns a tab pane CSS class.
      * @param string $index
      * @param string $label
-     * @return string
+     * @return string|null
      */
     public function getPaneCssClass($index = null, $label = null)
     {

modules/backend/classes/MainMenuItem.php

@@ -6,6 +6,8 @@
  * Class MainMenuItem
  *
  * @package Backend\Classes
+ *
+ * @phpstan-consistent-constructor
  */
 class MainMenuItem
 {

modules/backend/classes/QuickActionItem.php

@@ -4,6 +4,8 @@
  * Class QuickActionItem
  *
  * @package Backend\Classes
+ *
+ * @phpstan-consistent-constructor
  */
 class QuickActionItem
 {

modules/backend/classes/SideMenuItem.php

@@ -4,6 +4,8 @@
  * Class SideMenuItem
  *
  * @package Backend\Classes
+ *
+ * @phpstan-consistent-constructor
  */
 class SideMenuItem
 {

modules/backend/classes/WidgetBase.php

@@ -91,7 +91,7 @@ public function init()
 
     /**
      * Renders the widget's primary contents.
-     * @return string HTML markup supplied by this widget.
+     * @return string|null HTML markup supplied by this widget, or null when the widget renders nothing.
      */
     public function render()
     {

modules/backend/models/BrandSetting.php

@@ -20,6 +20,12 @@
  * @package winter\wn-backend-module
  * @author Alexey Bobkov, Samuel Georges
  * @author Winter CMS
+ *
+ * @mixin \System\Behaviors\SettingsModel
+ * @method static static instance()
+ * @method static bool isConfigured()
+ * @method static mixed get(string $key, mixed $default = null)
+ * @method static void resetDefault()
  */
 class BrandSetting extends Model
 {

modules/backend/models/EditorSetting.php

@@ -14,6 +14,12 @@
  *
  * @package winter\wn-backend-module
  * @author Alexey Bobkov, Samuel Georges
+ *
+ * @mixin \System\Behaviors\SettingsModel
+ * @method static static instance()
+ * @method static bool isConfigured()
+ * @method static mixed get(string $key, mixed $default = null)
+ * @method static void resetDefault()
  */
 class EditorSetting extends Model
 {

modules/backend/models/ImportModel.php

@@ -12,6 +12,8 @@
  *
  * @package winter\wn-backend-module
  * @author Alexey Bobkov, Samuel Georges
+ *
+ * @method \Winter\Storm\Database\Relations\AttachOne import_file()
  */
 abstract class ImportModel extends Model
 {

modules/backend/models/Preference.php

@@ -17,6 +17,12 @@
  *
  * @package winter\wn-backend-module
  * @author Alexey Bobkov, Samuel Georges
+ *
+ * @mixin \System\Behaviors\SettingsModel
+ * @method static static instance()
+ * @method static bool isConfigured()
+ * @method static mixed get(string $key, mixed $default = null)
+ * @method static void resetDefault()
  */
 class Preference extends Model
 {

modules/cms/classes/Asset.php

@@ -15,6 +15,8 @@
  *
  * @package winter\wn-cms-module
  * @author Alexey Bobkov, Samuel Georges
+ *
+ * @phpstan-consistent-constructor
  */
 class Asset extends Extendable
 {

modules/cms/classes/AutoDatasource.php

@@ -490,6 +490,8 @@ public function update(string $dirName, string $fileName, string $extension, str
      */
     public function delete(string $dirName, string $fileName, string $extension): bool
     {
+        $success = false;
+
         try {
             // Delete from only the active datasource
             if ($this->forceDeleting) {

modules/cms/classes/CmsCompoundObject.php

@@ -18,6 +18,8 @@
  *
  * @package winter\wn-cms-module
  * @author Alexey Bobkov, Samuel Georges
+ *
+ * @method \Winter\Storm\Halcyon\Collection get(array $columns = ['*'])
  */
 class CmsCompoundObject extends CmsObject
 {

modules/cms/classes/CmsException.php

@@ -67,6 +67,8 @@ public function __construct($message = null, $code = 100, ?Throwable $previous =
      */
     public function processCompoundObject(Throwable $exception)
     {
+        $result = false;
+
         switch ($this->code) {
             case 200:
                 $result = $this->processIni($exception);

modules/cms/classes/CmsObject.php

@@ -204,7 +204,7 @@ public static function inTheme($theme)
     public function save(?array $options = null)
     {
         try {
-            parent::save($options);
+            return parent::save($options);
         }
         catch (Exception $ex) {
             $this->throwHalcyonSaveException($ex);
@@ -322,6 +322,7 @@ public function getTwigCacheKey()
     /**
      * Converts an exception type thrown by Halcyon to a native CMS exception.
      * @param Exception $ex
+     * @return never
      */
     protected function throwHalcyonSaveException(Exception $ex)
     {

modules/cms/classes/CodeParser.php

@@ -193,7 +193,7 @@ public function source($page, $layout, $controller)
      * In some rare cases the cache file will not contain the class
      * name we expect. When this happens, destroy the corrupt file,
      * flush the request cache, and repeat the cycle.
-     * @return void
+     * @return array
      */
     protected function handleCorruptCache($data)
     {

modules/cms/classes/ComponentManager.php

@@ -81,7 +81,7 @@ protected function loadComponents()
      *     });
      *
      * @param callable $definitions
-     * @return array Array values are class names.
+     * @return void
      */
     public function registerComponents(callable $definitions)
     {
@@ -195,7 +195,7 @@ public function hasComponent($name)
      * @param array $properties The properties set by the Page or Layout.
      * @param bool $isSoftComponent Defines if this is a soft component.
      *
-     * @return ComponentBase The component object.
+     * @return ComponentBase|null The component object, or null for an unresolvable soft component.
      * @throws SystemException If the (hard) component cannot be found or is not registered.
      */
     public function makeComponent($name, $cmsObject = null, $properties = [], $isSoftComponent = false)

modules/cms/classes/ComponentPartial.php

@@ -12,6 +12,8 @@
  *
  * @package winter\wn-cms-module
  * @author Alexey Bobkov, Samuel Georges
+ *
+ * @phpstan-consistent-constructor
  */
 class ComponentPartial extends Extendable implements CmsObjectContract
 {

modules/cms/classes/Controller.php

@@ -32,6 +32,8 @@
  *
  * @package winter\wn-cms-module
  * @author Alexey Bobkov, Samuel Georges
+ *
+ * @phpstan-consistent-constructor
  */
 class Controller
 {

modules/cms/classes/Page.php

@@ -10,6 +10,8 @@
  *
  * @package winter\wn-cms-module
  * @author Alexey Bobkov, Samuel Georges
+ *
+ * @method static \Winter\Storm\Halcyon\Builder sortBy(string $column, string $direction = 'asc')
  */
 class Page extends CmsCompoundObject
 {

modules/cms/classes/Router.php

@@ -72,7 +72,7 @@ public function __construct(Theme $theme)
     /**
      * Finds a page by its URL. Returns the page object and sets the $parameters property.
      * @param string $url The requested URL string.
-     * @return \Cms\Classes\Page Returns \Cms\Classes\Page object or null if the page cannot be found.
+     * @return \Cms\Classes\Page|null Returns \Cms\Classes\Page object or null if the page cannot be found.
      */
     public function findByUrl($url)
     {
@@ -275,7 +275,7 @@ public function clearCache()
     /**
      * Sets the current routing parameters.
      * @param  array $parameters
-     * @return array
+     * @return void
      */
     public function setParameters(array $parameters)
     {

modules/cms/models/MaintenanceSetting.php

@@ -12,6 +12,12 @@
  *
  * @package winter\wn-cms-module
  * @author Alexey Bobkov, Samuel Georges
+ *
+ * @mixin \System\Behaviors\SettingsModel
+ * @method static static instance()
+ * @method static bool isConfigured()
+ * @method static mixed get(string $key, mixed $default = null)
+ * @method static void resetDefault()
  */
 class MaintenanceSetting extends Model
 {

modules/cms/models/ThemeExport.php

@@ -61,7 +61,7 @@ class ThemeExport extends Model
      */
     public function save(?array $options = null, $sessionKey = null)
     {
-        throw new ApplicationException(sprintf("The % model is not intended to be saved, please use %s instead", get_class($this), 'ThemeData'));
+        throw new ApplicationException(sprintf("The %s model is not intended to be saved, please use %s instead", get_class($this), 'ThemeData'));
     }
 
     public function getFoldersOptions()

modules/cms/models/ThemeImport.php

@@ -13,6 +13,8 @@
  *
  * @package winter\wn-cms-module
  * @author Alexey Bobkov, Samuel Georges
+ *
+ * @method \Winter\Storm\Database\Relations\AttachOne uploaded_file()
  */
 class ThemeImport extends Model
 {
@@ -66,7 +68,7 @@ class ThemeImport extends Model
      */
     public function save(?array $options = null, $sessionKey = null)
     {
-        throw new ApplicationException(sprintf("The % model is not intended to be saved, please use %s instead", get_class($this), 'ThemeData'));
+        throw new ApplicationException(sprintf("The %s model is not intended to be saved, please use %s instead", get_class($this), 'ThemeData'));
     }
 
     public function getFoldersOptions()

modules/system/classes/CombineAssets.php

@@ -521,7 +521,7 @@ protected function setHashOnCombinerFilters($hash)
     /**
      * Returns a deep hash on filters that support it.
      * @param array $assets List of asset files.
-     * @return void
+     * @return string
      */
     protected function getDeepHashFromAssets($assets)
     {

modules/system/classes/ImageResizer.php

@@ -40,6 +40,8 @@
  * @see System\Twig\Extension Twig filters for this class defined
  * @package winter\wn-system-module
  * @author Luke Towers
+ *
+ * @phpstan-consistent-constructor
  */
 class ImageResizer
 {

modules/system/classes/MediaLibrary.php

@@ -695,6 +695,8 @@ protected function scanFolderContents($fullFolderPath)
             } elseif ($content['type'] === 'dir') {
                 $type = MediaLibraryItem::TYPE_FOLDER;
                 $key = 'folders';
+            } else {
+                continue;
             }
 
             $libraryItem = $this->initLibraryItem($content, $type);

modules/system/classes/PluginBase.php

@@ -118,7 +118,7 @@ public function registerComponents()
     /**
      * Registers back-end navigation items for this plugin.
      *
-     * @return array
+     * @return array|null
      */
     public function registerNavigation()
     {
@@ -141,7 +141,7 @@ public function registerNavigation()
     /**
      * Registers back-end quick actions for this plugin.
      *
-     * @return array
+     * @return array|null
      */
     public function registerQuickActions()
     {
@@ -164,7 +164,7 @@ public function registerQuickActions()
     /**
      * Registers any back-end permissions used by this plugin.
      *
-     * @return array
+     * @return array|null
      */
     public function registerPermissions()
     {
@@ -177,7 +177,7 @@ public function registerPermissions()
     /**
      * Registers any back-end configuration links used by this plugin.
      *
-     * @return array
+     * @return array|null
      */
     public function registerSettings()
     {