Restore CI for PHP 7.1+ with versioned PHPUnit configs and PHPStan cleanup

.github/workflows/ci.yml

@@ -16,19 +16,45 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        php: [
-            7.1,
-            7.2,
-            7.3
-            7.4,
-            8.0,
-            8.1,
-            8.2,
-            8.3,
-            8.4,
-            8.5
-        ]
-        composer: [basic]
+        # Keep the "modern" leg on PHPUnit 9 until the suite is upgraded for
+        # PHPUnit 10+, so CI currently stops at PHP 8.4.
+        include:
+          - php: '7.1'
+            composer: basic
+            phpunit: '^7.5'
+            phpunit_config: phpunit.legacy.xml.dist
+          - php: '7.2'
+            composer: basic
+            phpunit: '^8.5'
+            phpunit_config: phpunit.legacy.xml.dist
+          - php: '7.3'
+            composer: basic
+            phpunit: '^9.6'
+            phpunit_config: phpunit.xml.dist
+          - php: '7.4'
+            composer: basic
+            phpunit: '^9.6'
+            phpunit_config: phpunit.xml.dist
+          - php: '8.0'
+            composer: basic
+            phpunit: '^9.6'
+            phpunit_config: phpunit.xml.dist
+          - php: '8.1'
+            composer: basic
+            phpunit: '^9.6'
+            phpunit_config: phpunit.xml.dist
+          - php: '8.2'
+            composer: basic
+            phpunit: '^9.6'
+            phpunit_config: phpunit.xml.dist
+          - php: '8.3'
+            composer: basic
+            phpunit: '^9.6'
+            phpunit_config: phpunit.xml.dist
+          - php: '8.4'
+            composer: basic
+            phpunit: '^9.6'
+            phpunit_config: phpunit.xml.dist
     timeout-minutes: 10
     steps:
       - name: Checkout code
@@ -57,6 +83,7 @@ jobs:
 
       - name: Install dependencies
         run: |
+          composer require --dev --no-update "phpunit/phpunit:${{ matrix.phpunit }}"
           if [[ "${{ matrix.composer }}" == "lowest" ]]; then
             composer update --prefer-dist --no-interaction --prefer-lowest --prefer-stable
           fi;
@@ -70,7 +97,7 @@ jobs:
       - name: Run tests
         run: |
           mkdir -p build/logs
-          XDEBUG_MODE=coverage php vendor/bin/phpunit -c phpunit.xml.dist
+          XDEBUG_MODE=coverage php vendor/bin/phpunit -c "${{ matrix.phpunit_config }}"
 
       - name: Run phpstan
         continue-on-error: true

phpstan.neon

@@ -1,7 +1,14 @@
 parameters:
+    # Analyze against the minimum supported runtime so PHP 7.1 compatibility
+    # issues are caught even when phpstan itself runs on a newer PHP in CI.
+    phpVersion: 70100
     level: 8
     paths:
         - %currentWorkingDirectory%/src/
+    excludePaths:
+        # This file is only loaded on PHP 8.1+ by JsonSerializableReturnTypeTrait.php.
+        # It defines the same trait name, so excluding it prevents a duplicate-symbol error.
+        - %currentWorkingDirectory%/src/JsonSerializableReturnTypeTraitPhp81.php
     reportUnmatchedIgnoredErrors: false
     ignoreErrors:
         # false-positive?

phpunit.legacy.xml.dist

@@ -0,0 +1,21 @@
+<?xml version="1.0"?>
+<phpunit>
+  <filter>
+    <whitelist processUncoveredFilesFromWhitelist="true">
+      <directory suffix=".php">./src/</directory>
+      <exclude>
+        <!-- Loaded conditionally by JsonSerializableReturnTypeTrait.php on PHP 8.1+;
+             including it unconditionally here would re-declare the trait on PHP < 8.1. -->
+        <file>./src/JsonSerializableReturnTypeTraitPhp81.php</file>
+      </exclude>
+    </whitelist>
+  </filter>
+  <logging>
+    <log type="coverage-clover" target="build/logs/clover.xml"/>
+  </logging>
+  <testsuites>
+    <testsuite name="Stringy">
+      <directory>tests</directory>
+    </testsuite>
+  </testsuites>
+</phpunit>

phpunit.xml.dist

@@ -4,6 +4,11 @@
     <include>
       <directory suffix=".php">./src/</directory>
     </include>
+    <exclude>
+      <!-- Loaded conditionally by JsonSerializableReturnTypeTrait.php on PHP 8.1+;
+           including it unconditionally here would re-declare the trait on PHP < 8.1. -->
+      <file>./src/JsonSerializableReturnTypeTraitPhp81.php</file>
+    </exclude>
     <report>
       <clover outputFile="build/logs/clover.xml"/>
     </report>

src/JsonSerializableReturnTypeTrait.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Stringy;
+
+if (\PHP_VERSION_ID < 80100) {
+    trait JsonSerializableReturnTypeTrait
+    {
+        /**
+         * Returns value which can be serialized by json_encode().
+         *
+         * @psalm-mutation-free
+         *
+         * @return string The current value of the $str property
+         */
+        public function jsonSerialize()
+        {
+            return (string) $this;
+        }
+    }
+} else {
+    require_once __DIR__ . '/JsonSerializableReturnTypeTraitPhp81.php';
+}

src/JsonSerializableReturnTypeTraitPhp81.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Stringy;
+
+trait JsonSerializableReturnTypeTrait
+{
+    /**
+     * Returns value which can be serialized by json_encode().
+     *
+     * PHP 8.1+ deprecates omitting the jsonSerialize() return type when
+     * implementing JsonSerializable, but PHP 7.1 cannot parse the attribute.
+     *
+     * @psalm-mutation-free
+     *
+     * @return string The current value of the $str property
+     */
+    #[\ReturnTypeWillChange]
+    public function jsonSerialize()
+    {
+        return (string) $this;
+    }
+}

src/StaticStringy.php

@@ -18,8 +18,8 @@
  * @method static string[] chars(string $stringInput, ?string $encoding = null)
  * @method static Stringy collapseWhitespace(string $stringInput, ?string $encoding = null)
  * @method static bool   contains(string $stringInput, string $needle, bool $caseSensitive = true, ?string $encoding = null)
- * @method static bool   containsAll(string $stringInput, array $needle, bool $caseSensitive = true, ?string $encoding = null)
- * @method static bool   containsAny(string $stringInput, string $needle, bool $caseSensitive = true, ?string $encoding = null)
+ * @method static bool   containsAll(string $stringInput, string[] $needle, bool $caseSensitive = true, ?string $encoding = null)
+ * @method static bool   containsAny(string $stringInput, string[] $needle, bool $caseSensitive = true, ?string $encoding = null)
  * @method static int    count(string $stringInput, ?string $encoding = null)
  * @method static int    countSubstr(string $stringInput, string $substring, bool $caseSensitive = true, ?string $encoding = null)
  * @method static Stringy dasherize(string $stringInput, ?string $encoding = null)
@@ -32,8 +32,8 @@
  * @method static Stringy first(string $stringInput, int $n, ?string $encoding = null)
  * @method static bool   hasLowerCase(string $stringInput, ?string $encoding = null)
  * @method static bool   hasUpperCase(string $stringInput, ?string $encoding = null)
- * @method static Stringy htmlDecode(string $stringInput, int $flags = ENT_COMPAT, ?string $encoding = null)
- * @method static Stringy htmlEncode(string $stringInput, int $flags = ENT_COMPAT, ?string $encoding = null)
+ * @method static Stringy htmlDecode(string $stringInput, int $flags, ?string $encoding = null)
+ * @method static Stringy htmlEncode(string $stringInput, int $flags, ?string $encoding = null)
  * @method static Stringy humanize(string $stringInput, ?string $encoding = null)
  * @method static int|bool indexOf(string $stringInput, string $needle, int $offset = 0, ?string $encoding = null)
  * @method static int|bool indexOfLast(string $stringInput, string $needle, int $offset = 0, ?string $encoding = null)
@@ -71,12 +71,12 @@
  * @method static Stringy removeXss(string $stringInput, ?string $encoding = null)
  * @method static Stringy repeat(string $stringInput, int $multiplier, ?string $encoding = null)
  * @method static Stringy replace(string $stringInput, string $search, string $replacement, bool $caseSensitive, ?string $encoding = null)
- * @method static Stringy replaceAll(string $stringInput, array $search, string $replacement, bool $caseSensitive, ?string $encoding = null)
+ * @method static Stringy replaceAll(string $stringInput, string[] $search, string|string[] $replacement, bool $caseSensitive, ?string $encoding = null)
  * @method static Stringy reverse(string $stringInput, ?string $encoding = null)
  * @method static Stringy safeTruncate(string $stringInput, int $length, string $substring = '', ?string $encoding = null)
  * @method static Stringy shuffle(string $stringInput, ?string $encoding = null)
  * @method static Stringy shortenAfterWord(string $stringInput, int $length, string $strAddOn)
- * @method static Stringy slugify(string $stringInput, string $separator = '-', string $language = 'en', array $replacements = [], ?string $encoding = null)
+ * @method static Stringy slugify(string $stringInput, string $separator = '-', string $language = 'en', array<string, string> $replacements = [], ?string $encoding = null)
  * @method static Stringy stripeCssMediaQueries(string $stringInput)
  * @method static Stringy stripeEmptyHtmlTags(string $stringInput)
  * @method static Stringy utf8ify(string $stringInput)

src/Stringy.php

@@ -33,6 +33,8 @@
  */
 class Stringy implements \ArrayAccess, \Countable, \IteratorAggregate, \JsonSerializable
 {
+    use JsonSerializableReturnTypeTrait;
+
     /**
      * An instance's string.
      *
@@ -2503,21 +2505,6 @@ public function isWhitespace(): bool
         return $this->isBlank();
     }
 
-    /**
-     * Returns value which can be serialized by json_encode().
-     *
-     * EXAMPLE: <code>
-     * </code>
-     *
-     * @psalm-mutation-free
-     *
-     * @return string The current value of the $str property
-     */
-    public function jsonSerialize(): mixed
-    {
-        return (string) $this;
-    }
-
     /**
      * Convert the string to kebab-case.
      *
@@ -4988,6 +4975,8 @@ public function urlEncodeRaw(): self
      * @return static
      *                <p>Object whose $str has been converted to an URL slug.</p>
      *
+     * @phpstan-param ASCII::*_LANGUAGE_CODE $language
+     *
      * @psalm-suppress ImpureMethodCall :/
      */
     public function urlify(

tests/StringyStrictTest.php

@@ -1909,7 +1909,11 @@ public function testAppendRandomStringProducesCorrectChars()
     {
         $result = S::create('')->appendRandomString(8, 'abc');
         static::assertSame(8, $result->length());
-        static::assertMatchesRegularExpression('/^[abc]{8}$/', $result->toString());
+        if (\method_exists(__CLASS__, 'assertMatchesRegularExpression')) {
+            static::assertMatchesRegularExpression('/^[abc]{8}$/', $result->toString());
+        } else {
+            static::assertRegExp('/^[abc]{8}$/', $result->toString());
+        }
     }
 
     public function testAddUniqueIdentifier()

tests/StringyTest.php

@@ -1907,7 +1907,11 @@ public function testAppendRandomStringProducesCorrectChars()
     {
         $result = S::create('')->appendRandomString(8, 'abc');
         static::assertSame(8, $result->length());
-        static::assertMatchesRegularExpression('/^[abc]{8}$/', $result->toString());
+        if (\method_exists(__CLASS__, 'assertMatchesRegularExpression')) {
+            static::assertMatchesRegularExpression('/^[abc]{8}$/', $result->toString());
+        } else {
+            static::assertRegExp('/^[abc]{8}$/', $result->toString());
+        }
     }
 
     public function testAddUniqueIdentifier()