feat: Introduce Rector to upgrade code for PHP 8.1 (#2977)

- Add rector/rector:fix composer scripts and description
- Add Rector workflow
- Add rector check to GrumPHP

.github/workflows/php-rector.yml

@@ -0,0 +1,43 @@
+name: PHP Rector
+
+on:
+  push:
+    branches:
+      - master
+      - 2.x
+    paths:
+      - '**.php'
+      - '**composer.json'
+  pull_request:
+    branches:
+      - master
+      - 2.x
+    paths:
+      - '**.php'
+      - '**composer.json'
+    types:
+      - opened
+      - synchronize
+      - ready_for_review
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  php-cs:
+    name: PHP Rector
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install dependencies
+        uses: ./.github/actions/setup
+
+      - name: Get changed files
+        id: changed-files
+        uses: tj-actions/changed-files@v44
+
+      - name: Run Rector checks
+        if: steps.changed-files.outputs.all_changed_files != ''
+        run: ./vendor/bin/rector process --dry-run ${{ steps.changed-files.outputs.files }}

composer.json

@@ -55,6 +55,7 @@
     "phpstan/extension-installer": "^1.1",
     "phpstan/phpstan": "^1.7",
     "phpunit/phpunit": "^9.0",
+    "rector/rector": "^1.0",
     "squizlabs/php_codesniffer": "^3.0",
     "symplify/easy-coding-standard": "^12.0",
     "szepeviktor/phpstan-wordpress": "^1.1",
@@ -120,6 +121,8 @@
       "@test",
       "@cs"
     ],
+    "rector": "rector process --dry-run",
+    "rector:fix": "rector process",
     "test": [
       "@test:integration:acf",
       "@test:integration:coauthors-plus",
@@ -145,6 +148,8 @@
     "lint-composer": "Check composer.json for incorrect order and whitespace",
     "lint-composer:fix": "Fix composer.json for incorrect order and whitespace",
     "qa": "Run all quality assurance checks/tests",
+    "rector": "Check Rector rules without applying them",
+    "rector:fix": "Fix Rector rules",
     "test": "Run all integration tests with PHPUnit",
     "test:integration": "Run unit tests for Timber core",
     "test:integration:acf": "Run unit tests related to the ACF integration for Timber",

grumphp.yml

@@ -3,5 +3,6 @@ grumphp:
         composer_normalize: ~
         ecs: ~
         phplint: ~
+        rector: ~
         # phpstan:
         #     memory_limit: "-1"

phpstan.neon

@@ -8,6 +8,7 @@ parameters:
         - vendor/php-stubs/wp-cli-stubs/wp-cli-stubs.php
         - vendor/php-stubs/acf-pro-stubs/acf-pro-stubs.php
     excludePaths:
+        - rector.php
         - tests/*
         - docs/*
     ignoreErrors:

rector.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+use Rector\Config\RectorConfig;
+use Rector\Php80\Rector\Class_\StringableForToStringRector;
+use Rector\Php81\Rector\Array_\FirstClassCallableRector;
+
+return RectorConfig::configure()
+    ->withPaths([
+        __DIR__ . '/src',
+    ])
+    ->withPhpSets(
+        php81: true,
+    )
+    ->withPreparedSets(
+        // deadCode: true,
+        // codeQuality: true,
+        // earlyReturn: true,
+    )
+    ->withSkip([
+        FirstClassCallableRector::class,
+        StringableForToStringRector::class,
+    ]);

src/Archives.php

@@ -265,7 +265,7 @@ public function items($args = null)
             $limit = \absint($args['limit']);
             $limit = ' LIMIT ' . $limit;
         }
-        $order = \strtoupper($order);
+        $order = \strtoupper((string) $order);
         if ($order !== 'ASC') {
             $order = 'DESC';
         }
@@ -372,7 +372,7 @@ public function items($args = null)
                         $text = $result->ID;
                         if ($result->post_title) {
                             /** This filter is documented in wp-includes/post-template.php */
-                            $text = \strip_tags(\apply_filters('the_title', $result->post_title, $result->ID));
+                            $text = \strip_tags((string) \apply_filters('the_title', $result->post_title, $result->ID));
                         }
                         $output[] = $this->get_archives_link($url, $text);
                     }

src/Attachment.php

@@ -67,7 +67,7 @@ class Attachment extends Post
      *
      * @var integer|null
      */
-    protected ?int $size;
+    protected ?int $size = null;
 
     /**
      * Gets the src for an attachment.
@@ -136,10 +136,7 @@ public function path(): string
      */
     public function file(): string
     {
-        if (isset($this->file)) {
-            return $this->file;
-        }
-        return $this->file = (string) \get_post_meta($this->ID, '_wp_attached_file', true);
+        return $this->file ?? ($this->file = (string) \get_post_meta($this->ID, '_wp_attached_file', true));
     }
 
     /**
@@ -151,10 +148,7 @@ public function file(): string
      */
     public function file_loc(): string
     {
-        if (isset($this->file_loc)) {
-            return $this->file_loc;
-        }
-        return $this->file_loc = (string) \get_attached_file($this->ID);
+        return $this->file_loc ?? ($this->file_loc = (string) \get_attached_file($this->ID));
     }
 
     /**
@@ -278,10 +272,7 @@ public function size(): ?int
      */
     public function extension(): string
     {
-        if (isset($this->file_extension)) {
-            return $this->file_extension;
-        }
-        return $this->file_extension = \pathinfo($this->file(), PATHINFO_EXTENSION);
+        return $this->file_extension ?? ($this->file_extension = \pathinfo($this->file(), PATHINFO_EXTENSION));
     }
 
     /**
@@ -340,7 +331,6 @@ public function pathinfo()
      *
      * This method is used to retrieve the attachment metadata only when it's needed.
      *
-     * @param string|null $key
      * @return array|string|int|null
      */
     protected function metadata(?string $key = null)

src/Cache/KeyGenerator.php

@@ -5,10 +5,9 @@
 class KeyGenerator
 {
     /**
-     * @param mixed $value
      * @return string
      */
-    public function generateKey($value)
+    public function generateKey(mixed $value)
     {
         if (\is_a($value, 'Timber\Cache\TimberKeyGeneratorInterface')) {
             return $value->_get_cache_key();
@@ -20,7 +19,7 @@ public function generateKey($value)
 
         $key = \md5(\json_encode($value));
         if (\is_object($value)) {
-            $key = \get_class($value) . ';' . $key;
+            $key = $value::class . ';' . $key;
         }
 
         // Replace any of the reserved characters.

src/Cache/WPObjectCacheAdapter.php

@@ -6,17 +6,10 @@
 
 class WPObjectCacheAdapter
 {
-    private $cache_group;
-
-    /**
-     * @var Loader
-     */
-    private $timberloader;
-
-    public function __construct(Loader $timberloader, $cache_group = 'timber')
-    {
-        $this->cache_group = $cache_group;
-        $this->timberloader = $timberloader;
+    public function __construct(
+        private readonly Loader $timberloader,
+        private $cache_group = 'timber'
+    ) {
     }
 
     public function fetch($key)

src/Comment.php

@@ -2,6 +2,7 @@
 
 namespace Timber;
 
+use Stringable;
 use WP_Comment;
 
 /**
@@ -33,7 +34,7 @@
  * <p class="comment-attribution">- Sullivan Ballou</p>
  * ```
  */
-class Comment extends CoreEntity
+class Comment extends CoreEntity implements Stringable
 {
     /**
      * The underlying WordPress Core object.
@@ -42,7 +43,7 @@ class Comment extends CoreEntity
      *
      * @var WP_Comment|null
      */
-    protected ?WP_Comment $wp_object;
+    protected ?WP_Comment $wp_object = null;
 
     public $object_type = 'comment';
 
@@ -278,7 +279,7 @@ public function avatar($size = 92, $default = '')
      */
     public function content()
     {
-        return \trim(\apply_filters('comment_text', $this->comment_content));
+        return \trim((string) \apply_filters('comment_text', $this->comment_content));
     }
 
     /**
@@ -374,7 +375,7 @@ public function approved()
      */
     public function date($date_format = '')
     {
-        $df = $date_format ? $date_format : \get_option('date_format');
+        $df = $date_format ?: \get_option('date_format');
         $the_date = (string) \mysql2date($df, $this->comment_date);
         return \apply_filters('get_comment_date ', $the_date, $df);
     }
@@ -403,7 +404,7 @@ public function date($date_format = '')
      */
     public function time($time_format = '')
     {
-        $tf = $time_format ? $time_format : \get_option('time_format');
+        $tf = $time_format ?: \get_option('time_format');
         $the_time = (string) \mysql2date($tf, $this->comment_date);
         return \apply_filters('get_comment_time', $the_time, $tf);
     }
@@ -576,7 +577,7 @@ protected function avatar_host($email_hash)
      */
     protected function avatar_default($default, $email, $size, $host)
     {
-        if (\substr($default, 0, 1) == '/') {
+        if (\str_starts_with($default, '/')) {
             $default = \home_url() . $default;
         }
 
@@ -598,7 +599,7 @@ protected function avatar_default($default, $email, $size, $host)
             $default = '';
         } elseif ('gravatar_default' == $default) {
             $default = $host . '/avatar/?s=' . $size;
-        } elseif (empty($email) && !\preg_match('/^https?:\/\//', $default)) {
+        } elseif (empty($email) && !\preg_match('/^https?:\/\//', (string) $default)) {
             $default = $host . '/avatar/?d=' . $default . '&amp;s=' . $size;
         }
         return $default;
@@ -631,6 +632,6 @@ protected function avatar_out($default, $host, $email_hash, $size)
             $out
         );
 
-        return \str_replace('&#038;', '&amp;', \esc_url($out));
+        return \str_replace('&#038;', '&amp;', (string) \esc_url($out));
     }
 }

src/CommentThread.php

@@ -47,8 +47,6 @@
  */
 class CommentThread extends ArrayObject
 {
-    public $post_id;
-
     public $_orderby = '';
 
     public $_order = 'ASC';
@@ -60,10 +58,11 @@ class CommentThread extends ArrayObject
      * @param array|boolean $args    Optional. An array of arguments or false if initialization
      *                               should be skipped.
      */
-    public function __construct($post_id, $args = [])
-    {
+    public function __construct(
+        public $post_id,
+        $args = []
+    ) {
         parent::__construct();
-        $this->post_id = $post_id;
         if ($args || \is_array($args)) {
             $this->init($args);
         }

src/Core.php

@@ -27,10 +27,7 @@ abstract class Core
      */
     public function __isset($field)
     {
-        if (isset($this->$field)) {
-            return $this->$field;
-        }
-        return false;
+        return isset($this->$field);
     }
 
     /**
@@ -165,7 +162,7 @@ public function import($info, $force = false, $only_declared_properties = false)
      * @param string $key   The key of the meta field to update.
      * @param mixed  $value The new value.
      */
-    public function update($key, $value)
+    public function update($key, mixed $value)
     {
         Helper::deprecated('Timber\Core::update()', 'update_metadata()', '2.0.0');
         \update_metadata($this->object_type, $this->ID, $key, $value);

src/DateTimeHelper.php

@@ -89,7 +89,7 @@ public static function time_ago($from, $to = null, $format_past = null, $format_
             $format_future = \__('%s from now');
         }
 
-        $to = $to ?? \time();
+        $to ??= \time();
         $to = \is_numeric($to)
             ? new DateTimeImmutable('@' . $to, \wp_timezone())
             : new DateTimeImmutable($to, \wp_timezone());