Add PHPStan static analysis for the modules

.github/workflows/code-analysis.yaml

@@ -0,0 +1,51 @@
+name: Tests
+
+on:
+  pull_request:
+  push:
+    branches:
+      - 1.0
+      - 1.1
+      - 1.2
+      - wip/1.3
+      - develop
+
+concurrency:
+  group: phpstan-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  codeAnalysis:
+    runs-on: ubuntu-latest
+    name: Code Analysis
+    env:
+      extensions: curl, fileinfo, gd, mbstring, openssl, pdo, pdo_sqlite, sqlite3, xml, zip
+    steps:
+      - name: Checkout changes
+        uses: actions/checkout@v7
+
+      - name: Install PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: ${{ env.extensions }}
+          coverage: none
+
+      - name: Configure Composer GitHub token
+        run: composer config --global --auth github-oauth.github.com ${{ secrets.COMPOSER_GITHUB_TOKEN }}
+
+      - name: Install Composer dependencies
+        run: composer install --no-interaction --no-progress --no-scripts
+
+      # composer/installers places the module packages into modules/, which clobbers the
+      # checked-out module changes; restore the working tree the same way tests.yml does.
+      - name: Reset modules
+        run: |
+          git reset --hard
+          git clean -fd
+
+      - name: Clear phpstan cache
+        run: vendor/bin/phpstan clear-result-cache
+
+      - name: Analyse code
+        run: vendor/bin/phpstan analyse --memory-limit=2G --no-progress

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/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/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/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/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/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

@@ -66,7 +66,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/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()
     {

modules/system/classes/UpdateManager.php

@@ -655,7 +655,7 @@ public function rollbackPlugin(string $name, ?string $stopOnVersion = null)
      * @param string $name Plugin name.
      * @param string $hash Expected file hash.
      * @param boolean $installation Indicates whether this is a plugin installation request.
-     * @return self
+     * @return void
      */
     public function downloadPlugin($name, $hash, $installation = false)
     {
@@ -699,7 +699,7 @@ public function requestThemeDetails($name)
      * Downloads a theme from the update server.
      * @param string $name Theme name.
      * @param string $hash Expected file hash.
-     * @return self
+     * @return void
      */
     public function downloadTheme($name, $hash)
     {
@@ -896,7 +896,7 @@ public function requestChangelog()
     protected function write($component, ...$arguments)
     {
         if ($this->notesOutput !== null) {
-            with(new $component($this->notesOutput))->render(...$arguments);
+            (new $component($this->notesOutput))->render(...$arguments);
         }
 
         return $this;

modules/system/classes/VersionManager.php

@@ -614,7 +614,7 @@ protected function hasDatabaseHistory($code, $version, $script = null)
     protected function write($component, ...$arguments)
     {
         if ($this->notesOutput !== null) {
-            with(new $component($this->notesOutput))->render(...$arguments);
+            (new $component($this->notesOutput))->render(...$arguments);
         }
 
         return $this;

modules/system/classes/asset/BundleManager.php

@@ -261,6 +261,10 @@ public function registerBundle(string $name, array $definition): static
 
     /**
      * Registers a single bundle setup handler.
+     *
+     * The handler runs bound to the asset command invoking it, through Closure::call().
+     *
+     * @param-closure-this \System\Console\Asset\AssetCreate $closure
      */
     public function registerSetupHandler(string $name, Closure $closure): static
     {
@@ -271,6 +275,10 @@ public function registerSetupHandler(string $name, Closure $closure): static
 
     /**
      * Registers a single bundle scaffold handler.
+     *
+     * The handler runs bound to the asset command invoking it, through Closure::call().
+     *
+     * @param-closure-this \System\Console\Asset\AssetCreate $closure
      */
     public function registerScaffoldHandler(string $name, Closure $closure): static
     {

phpstan-bootstrap.php

@@ -0,0 +1,27 @@
+<?php
+
+/*
+ * Analysis bootstrap for PHPStan.
+ *
+ * The modules are loaded through Winter's own class loader rather than composer, so the same
+ * loader is registered here, mirroring modules/system/tests/bootstrap/app.php. Winter also
+ * registers global class aliases (Model, BackendAuth, and friends) while the application boots,
+ * and module code references the aliases directly, so the alias map is registered as well.
+ */
+require __DIR__ . '/vendor/autoload.php';
+
+$classLoader = new Winter\Storm\Support\ClassLoader(
+    new Winter\Storm\Filesystem\Filesystem(),
+    __DIR__,
+    __DIR__ . '/storage/framework/classes.php'
+);
+
+$classLoader->register();
+
+foreach (glob(__DIR__ . '/modules/*', GLOB_ONLYDIR) as $modulePath) {
+    $classLoader->autoloadPackage(basename($modulePath), $modulePath);
+}
+
+Illuminate\Foundation\AliasLoader::getInstance(
+    require __DIR__ . '/modules/system/aliases.php'
+)->register();

phpstan.neon.dist

@@ -0,0 +1,18 @@
+includes:
+    - vendor/larastan/larastan/extension.neon
+
+parameters:
+    paths:
+        - modules/system/classes
+        - modules/system/models
+        - modules/backend/classes
+        - modules/backend/models
+        - modules/cms/classes
+        - modules/cms/models
+    level: 0
+    bootstrapFiles:
+        - phpstan-bootstrap.php
+    scanDirectories:
+        - modules
+    treatPhpDocTypesAsCertain: false
+    disableSchemaScan: true