Merge pull request #2668 from timber/2.x-phpstan-level-2

2.x Fix PHPStan issues on level 2
timber · May 28, 2023 · f248f3c · f248f3c
2 parents b359316 + b2fbd01
commit f248f3c
Show file tree

Hide file tree

Showing 20 changed files with 210 additions and 71 deletions.
diff --git a/composer.json b/composer.json
@@ -69,6 +69,9 @@
     }
   },
   "autoload-dev": {
+    "psr-4": {
+      "TimberPHPStan\\": "tests/phpstan"
+    },
     "classmap": [
       "tests/"
     ],

diff --git a/phpstan.neon b/phpstan.neon
@@ -1,5 +1,5 @@
 parameters:
-    level: 1 # Increase until "max"
+    level: 2 # Increase until "max"
     paths:
         - src/
     scanFiles:
@@ -8,8 +8,16 @@ parameters:
     ignoreErrors:
         - '#Instantiated class Twig\\CacheExtension\\CacheStrategy\\GenerationalCacheStrategy not found.#'
         - '#Instantiated class Twig\\CacheExtension\\Extension not found.#'
+        - '#Method Timber\\Loader::_get_cache_extension\(\) has invalid return type Twig\\CacheExtension\\Extension.#'
         # Uses func_get_args()
         - '#^Function remove_filter invoked with [3456] parameters, 2-3 required\.$#'
         - '#^Function apply_filters invoked with [3456] parameters, 2 required\.$#'
+        # ACF
+        - '#Access to an undefined property ACF::\$fields\.#'
     #     # TODO Do not create a static instance of a non-final class.
     #     - '#^Unsafe usage of new static\(\)\.$#'
+services:
+    -
+        class: TimberPHPStan\WPNavMenuItemPost
+        tags:
+            - phpstan.broker.propertiesClassReflectionExtension
diff --git a/src/AccessesPostsLazily.php b/src/AccessesPostsLazily.php
@@ -29,12 +29,14 @@ trait AccessesPostsLazily
     private $factory;
 
     /**
+     * Realizes a lazy collection of posts.
+     *
      * For better performance, Post Collections do not instantiate `Timber\Post` objects
      * at query time. They instantiate each `Timber\Post` only as needed, i.e. while
      * iterating or for direct array access (`$coll[$i]`). Since specific `Timber\Post`
      * implementations may have expensive `::setup()` operations, this is usually
      * what you want, but not always. For example, you may want to force eager
-     * instantiation to front-load a collection to be cached. To eagerly instantiate
+     * instantiation to front-load a collection of posts to be cached. To eagerly instantiate
      * a lazy collection of objects is to "realize" that collection.
      *
      * @api
@@ -47,7 +49,7 @@ trait AccessesPostsLazily
      * }, HOUR_IN_SECONDS);
      *
      * foreach ($lazy_posts as $post) {
-     *   // This will incur the performance cost of Post::setup()
+     *   // This will incur the performance cost of Post::setup().
      * }
      *
      * // Contrast with:
@@ -64,7 +66,7 @@ trait AccessesPostsLazily
      *   // No additional overhead here.
      * }
      * ```
-     * @return \Timber\PostCollectionInterface the realized PostQuery
+     * @return \Timber\PostCollectionInterface The realized PostQuery.
      */
     public function realize(): self
     {

diff --git a/src/Core.php b/src/Core.php
@@ -168,16 +168,4 @@ public function update($key, $value)
         Helper::deprecated('Timber\Core::update()', 'update_metadata()', '2.0.0');
         update_metadata($this->object_type, $this->ID, $key, $value);
     }
-
-    /**
-     *
-     *
-     * @return array
-     */
-    public function get_method_values()
-    {
-        $ret = [];
-        $ret['can_edit'] = $this->can_edit();
-        return $ret;
-    }
 }
diff --git a/src/Factory/PagesMenuFactory.php b/src/Factory/PagesMenuFactory.php
@@ -4,7 +4,6 @@
 
 use Timber\CoreInterface;
 use Timber\PagesMenu;
-use WP_Term;
 
 /**
  * Internal API class for instantiating Menus
@@ -64,7 +63,6 @@ protected function get_menu_class($args): string
     /**
      * Build menu
      *
-     * @param WP_Term $term
      * @param array $args Optional. Args for get_pages().
      * @return CoreInterface
      */

diff --git a/src/Helper.php b/src/Helper.php
@@ -181,7 +181,7 @@ public static function start_timer()
     {
         $time = microtime();
         $time = explode(' ', $time);
-        $time = $time[1] + $time[0];
+        $time = (float) $time[1] + (float) $time[0];
         return $time;
     }
 
@@ -203,7 +203,7 @@ public static function stop_timer($start)
     {
         $time = microtime();
         $time = explode(' ', $time);
-        $time = $time[1] + $time[0];
+        $time = (float) $time[1] + (float) $time[0];
         $finish = $time;
         $total_time = round(($finish - $start), 4);
         return $total_time . ' seconds.';
@@ -254,7 +254,7 @@ public static function ob_function($function, $args = [null])
      * Output a value (string, array, object, etc.) to the error log
      *
      * @api
-     * @param mixed $arg that you want to error_log
+     * @param mixed $error The error that you want to error_log().
      * @return void
      */
     public static function error_log($error)

diff --git a/src/Image/Operation/Resize.php b/src/Image/Operation/Resize.php
@@ -238,5 +238,7 @@ public function run($load_filename, $save_filename)
             }
             // @codeCoverageIgnoreEnd
         }
+
+        return false;
     }
 }
diff --git a/src/ImageHelper.php b/src/ImageHelper.php
@@ -202,11 +202,11 @@ public static function is_svg($file_path)
      *
      * @api
      *
-     * @param string  $src
-     * @param int     $w
-     * @param int     $h
-     * @param string  $color
-     * @param bool    $force
+     * @param string      $src
+     * @param int         $w
+     * @param int         $h
+     * @param string|bool $color
+     * @param bool        $force
      * @return string
      */
     public static function letterbox($src, $w, $h, $color = false, $force = false)
@@ -302,6 +302,7 @@ public static function _delete_generated_if_image($post_id)
     {
         if (wp_attachment_is_image($post_id)) {
             $attachment = Timber::get_post($post_id);
+            /** @var \Timber\Attachment $attachment */
             if ($attachment->file_loc) {
                 ImageHelper::delete_generated_files($attachment->file_loc);
             }

diff --git a/src/Integration/CoAuthorsPlus/CoAuthorsPlusUser.php b/src/Integration/CoAuthorsPlus/CoAuthorsPlusUser.php
@@ -13,7 +13,7 @@ class CoAuthorsPlusUser extends User
      */
     protected $thumbnail;
 
-    public static function from_guest_author(\stdclass $coauthor)
+    public static function from_guest_author(\stdClass $coauthor)
     {
         $user = new static();
         $user->init($coauthor);
@@ -27,16 +27,16 @@ public static function from_guest_author(\stdclass $coauthor)
      */
     protected function init($coauthor = false)
     {
+        /**
+         * @var \stdClass $coauthor
+         */
         parent::init($coauthor);
+
         $this->id = $this->ID = (int) $coauthor->ID;
         $this->first_name = $coauthor->first_name;
         $this->last_name = $coauthor->last_name;
         $this->user_nicename = $coauthor->user_nicename;
         $this->description = $coauthor->description;
-
-        /**
-         * @property string name
-         */
         $this->display_name = $coauthor->display_name;
         $this->_link = get_author_posts_url(null, $coauthor->user_nicename);
     }

diff --git a/src/Menu.php b/src/Menu.php
@@ -112,7 +112,7 @@ class Menu extends CoreEntity
 
     /**
      * @internal
-     * @param \WP_Term   $wp_term the vanilla WP term object to build from
+     * @param \WP_Term   $menu The vanilla WordPress term object to build from.
      * @param array      $args Optional. Right now, only the `depth` is
      *                            supported which says how many levels of hierarchy should be
      *                            included in the menu. Default `0`, which is all levels.
@@ -269,13 +269,13 @@ public static function build(?WP_Term $menu, $args = []): ?self
      *
      * @api
      *
-     * @param int|string $slug    A menu slug, the term ID of the menu, the full name from the admin
+     * @param \WP_Term|null $term A menu slug, the term ID of the menu, the full name from the admin
      *                            menu, the slug of the registered location or nothing. Passing
      *                            nothing is good if you only have one menu. Timber will grab what
      *                            it finds.
-     * @param array      $args Optional. Right now, only the `depth` is
-     *                            supported which says how many levels of hierarchy should be
-     *                            included in the menu. Default `0`, which is all levels.
+     * @param array $args         Optional. Right now, only the `depth` is supported which says how
+     *                            many levels of hierarchy should be included in the menu. Default
+     *                            `0`, which is all levels.
      */
     final protected function __construct(?WP_term $term, array $args = [])
     {
@@ -320,7 +320,7 @@ public function wp_object(): ?WP_Term
     /**
      * Convert menu items into MenuItem objects
      *
-     * @param array $items
+     * @param array $menu_items
      * @return MenuItem[]
      */
     protected function convert_menu_items(array $menu_items): array

diff --git a/src/MenuItem.php b/src/MenuItem.php
@@ -136,7 +136,9 @@ final protected function __construct(WP_Post $data, $menu = null)
         $this->wp_object = $data;
         $this->menu = $menu;
 
-        $data = (object) $data;
+        /**
+         * @property string $title The nav menu item title.
+         */
         $this->title = $data->title;
 
         $this->import($data);

diff --git a/src/PagesMenu.php b/src/PagesMenu.php
@@ -191,9 +191,9 @@ public static function build($menu, $args = []): ?self
      * We need to set some properties so that we can use `wp_setup_nav_menu_item()` on the menu
      * items and a proper menu item hierarchy can be built.
      *
-     * @param \WP_Post $pages A post object.
+     * @param \WP_Post $post A post object.
      *
-     * @return array Updated post object.
+     * @return \WP_Post Updated post object.
      */
     protected function pre_setup_nav_menu_item($post)
     {

diff --git a/src/Pagination.php b/src/Pagination.php
@@ -177,7 +177,18 @@ public static function paginate_links($args = [])
                 ];
                 $dots = true;
             } else {
-                if ($args['show_all'] || ($n <= $args['start_size'] || ($args['current'] && $n >= $args['current'] - $args['mid_size'] && $n <= $args['current'] + $args['mid_size']) || $n > $args['total'] - $args['end_size'])) {
+                if (
+                    $args['show_all']
+                    || (
+                        $n <= (int) $args['start_size']
+                        || (
+                            $args['current']
+                            && $n >= (int) $args['current'] - (int) $args['mid_size']
+                            && $n <= (int) $args['current'] + (int) $args['mid_size']
+                        )
+                        || $n > (int) $args['total'] - (int) $args['end_size']
+                    )
+                ) {
                     $link = str_replace('%_%', 1 == $n ? '' : $args['format'], $args['base']);
                     $link = str_replace('%#%', $n, $link);
 

diff --git a/src/Post.php b/src/Post.php
@@ -858,9 +858,8 @@ public function css_class($class = '')
      * @return array
      * @codeCoverageIgnore
      */
-    public function get_method_values()
+    public function get_method_values(): array
     {
-        $ret = parent::get_method_values();
         $ret['author'] = $this->author();
         $ret['categories'] = $this->categories();
         $ret['category'] = $this->category();
@@ -958,9 +957,9 @@ public function categories()
     }
 
     /**
-     * Returns a category attached to a post
+     * Gets a category attached to a post.
      *
-     * If multiple categories are set, it will return just the first one
+     * If multiple categories are set, it will return just the first one.
      *
      * @api
      * @return \Timber\Term|null
@@ -971,6 +970,8 @@ public function category()
         if (count($cats) && isset($cats[0])) {
             return $cats[0];
         }
+
+        return null;
     }
 
     /**
@@ -1724,11 +1725,10 @@ public function pagination()
     }
 
     /**
-     * Finds any WP_Post objects and converts them to Timber\Posts
+     * Finds any WP_Post objects and converts them to Timber\Post objects.
      *
      * @api
-     * @param array|WP_Post $data
-     * @param string $class
+     * @param array|\WP_Post $data
      */
     public function convert($data)
     {
@@ -1853,6 +1853,8 @@ public function thumbnail()
         if ($tid) {
             return $this->factory()->from($tid);
         }
+
+        return null;
     }
 
     /**

diff --git a/src/PostArrayObject.php b/src/PostArrayObject.php
@@ -2,6 +2,7 @@
 
 namespace Timber;
 
+use ArrayObject;
 use JsonSerializable;
 
 /**
@@ -10,7 +11,7 @@
  *
  * @api
  */
-class PostArrayObject extends \ArrayObject implements PostCollectionInterface, JsonSerializable
+class PostArrayObject extends ArrayObject implements PostCollectionInterface, JsonSerializable
 {
     use AccessesPostsLazily;
 

diff --git a/src/Site.php b/src/Site.php
@@ -336,6 +336,8 @@ public function icon()
         if ($iid) {
             return Timber::get_post($iid);
         }
+
+        return null;
     }
 
     protected function icon_multisite($site_id)