Merge pull request #42 from Yoast/develop

Release version 1.0.0
Yoast · Jun 21, 2021 · 5d257d5 · 5d257d5
2 parents c48e4cf + f74b143
commit 5d257d5
Show file tree

Hide file tree

Showing 64 changed files with 4,026 additions and 345 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -7,8 +7,8 @@
 #
 /.gitattributes export-ignore
 /.gitignore export-ignore
-/.travis.yml export-ignore
 /.cache/ export-ignore
+/.github/ export-ignore
 /.phpcs.xml.dist export-ignore
 /phpunit.xml.dist export-ignore
 /tests/ export-ignore

diff --git a/.github/workflows/cs.yml b/.github/workflows/cs.yml
@@ -0,0 +1,42 @@
+name: CS
+
+on:
+  # Run on all pushes and on all pull requests.
+  push:
+  pull_request:
+  # Allow manually triggering the workflow.
+  workflow_dispatch:
+
+jobs:
+  checkcs:
+    name: 'Basic CS and QA checks'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Install PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '7.4'
+          coverage: none
+          tools: cs2pr
+
+      # Install dependencies and handle caching in one go.
+      # @link https://github.com/marketplace/actions/install-composer-dependencies
+      - name: Install Composer dependencies
+        uses: "ramsey/composer-install@v1"
+
+      # Validate the composer.json file.
+      # @link https://getcomposer.org/doc/03-cli.md#validate
+      - name: Validate Composer installation
+        run: composer validate --no-check-all --strict
+
+      # Check the code-style consistency of the PHP files.
+      - name: Check PHP code style
+        continue-on-error: true
+        run: composer check-cs -- --report-full --report-checkstyle=./phpcs-report.xml
+
+      - name: Show PHPCS results in PR
+        run: cs2pr ./phpcs-report.xml
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -0,0 +1,106 @@
+name: Test
+
+on:
+  # Run on all pushes and on all pull requests.
+  push:
+  pull_request:
+  # Allow manually triggering the workflow.
+  workflow_dispatch:
+
+jobs:
+  #### TEST STAGE ####
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        php: ['5.4', '5.5', '5.6', '7.0', '7.1', '7.2', '7.3', '7.4', '8.0']
+        phpunit: ['auto']
+        experimental: [false]
+
+        include:
+          # Test against a version on the low-end of the PHPUnit versions supported for each PHP version.
+          # On PHP 5.4 and 5.5, only PHPUnit 4.x is supported and the lowest and the
+          # highest supported version would be the same.
+          # Using the Composer `--prefer-lowest` option is, unfortunately, not viable, as
+          # PHPUnit 4.8.36 doesn't have proper PHP restrictions, which means that it
+          # would always be installed as "low", which would break the builds for PHP 7.2+.
+          - php: '5.6'
+            phpunit: '5.7.21'
+            experimental: false
+          - php: '7.0'
+            phpunit: '5.7.27'
+            experimental: false
+          - php: '7.1'
+            phpunit: '5.7.21'
+            experimental: false
+          - php: '7.2'
+            phpunit: '6.3.1'
+            experimental: false
+          - php: '7.3'
+            phpunit: '7.2.7'
+            experimental: false
+          - php: '7.4'
+            phpunit: '8.1.6'
+            experimental: false
+          - php: '8.0'
+            phpunit: '8.5.16'
+            experimental: false
+          - php: '8.0'
+            phpunit: '9.3.0'
+            experimental: false
+
+          # Experimental builds.
+          - php: '8.1'
+            phpunit: 'auto'
+            experimental: true
+
+          - php: '8.0'
+            phpunit: '^10.0'
+            experimental: true
+
+    name: "Tests: PHP ${{ matrix.php }} - PHPUnit: ${{matrix.phpunit}}"
+
+    continue-on-error: ${{ matrix.experimental }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Install PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          coverage: none
+
+      - name: 'Composer: set PHPUnit version for tests'
+        if: ${{ matrix.phpunit != 'auto' }}
+        run: composer require --no-update phpunit/phpunit:"${{ matrix.phpunit }}"
+
+      # Install dependencies and handle caching in one go.
+      # @link https://github.com/marketplace/actions/install-composer-dependencies
+      - name: Install Composer dependencies for PHP < 8.1
+        if: ${{ matrix.php < 8.1 }}
+        uses: "ramsey/composer-install@v1"
+
+      # For PHP 8.1 and above, we need to install with ignore platform reqs as not all dependencies allow it yet.
+      - name: Install Composer dependencies for PHP >= 8.1
+        if: ${{ matrix.php >= 8.1 }}
+        uses: "ramsey/composer-install@v1"
+        with:
+          composer-options: --ignore-platform-reqs
+
+      - name: "Lint PHP files against parse errors - PHP < 7.0"
+        if: ${{ matrix.phpunit == 'auto' && matrix.php < 7.0 }}
+        run: composer lint-lt70
+
+      - name: "Lint PHP files against parse errors - PHP 7.x"
+        if: ${{ matrix.phpunit == 'auto' && startsWith( matrix.php, '7' ) }}
+        run: composer lint7
+
+      - name: "Lint PHP files against parse errors - PHP >= 8.0"
+        if: ${{ matrix.phpunit == 'auto' && matrix.php >= 8.0 }}
+        run: composer lint-gte80
+
+      - name: Run the unit tests
+        run: composer test
diff --git a/.phpcs.xml.dist b/.phpcs.xml.dist
@@ -33,9 +33,6 @@
 	#############################################################################
 	-->
 
-	<!-- Support PHP 5.6 or higher. -->
-	<config name="testVersion" value="5.6-"/>
-
 	<rule ref="Yoast">
 		<!-- Duplicate classes is by design and part of the cross-version compatibility mechanism. -->
 		<exclude name="Generic.Classes.DuplicateClassName"/>
@@ -48,11 +45,25 @@
 		<!-- Exclude some rules which are irrelevant.
 			 The code in this package is not run in the context of a WordPress plugin. -->
 		<exclude name="WordPress.DB"/>
+		<exclude name="WordPress.PHP.DevelopmentFunctions.error_log_var_export"/>
+		<exclude name="WordPress.PHP.DiscouragedPHPFunctions.system_calls_popen"/>
 		<exclude name="WordPress.Security"/>
 		<exclude name="WordPress.WP"/>
 		<exclude name="Yoast.Yoast.AlternativeFunctions"/>
 	</rule>
 
+	<!-- While PHPCompatibility is already included in the Yoast ruleset, it uses
+		 the PHPCompatibilityWP ruleset, which excludes rules polyfilled by WP.
+		 Setting the severity for all PHPCompatibility rules to 5 prevents WP
+		 polyfilled functionality from not being flagged in this repo. -->
+	<rule ref="PHPCompatibility">
+		<severity>5</severity>
+
+		<!-- These PHP 7.0+ classes are polyfilled for this repo. -->
+		<exclude name="PHPCompatibility.Classes.NewClasses.errorFound"/>
+		<exclude name="PHPCompatibility.Classes.NewClasses.typeerrorFound"/>
+	</rule>
+
 	<!-- Enforce PSR1 compatible namespaces. -->
 	<rule ref="PSR1.Classes.ClassDeclaration"/>
 
@@ -82,6 +93,25 @@
 	#############################################################################
 	-->
 
+	<!-- The polyfills for the PHP native exceptions can not have a namespace
+		 and making those the only files with a file comment would create more,
+		 not less inconsistency. -->
+	<rule ref="Yoast.Commenting.FileComment">
+		<exclude-pattern>/src/Exceptions/*Error\.php$</exclude-pattern>
+	</rule>
+
+	<!-- Deliberately empty Catch statements. -->
+	<rule ref="Generic.CodeAnalysis.EmptyStatement.DetectedCatch">
+		<exclude-pattern>/src/Helpers/ResourceHelper\.php$</exclude-pattern>
+		<exclude-pattern>/src/Polyfills/AssertClosedResource*\.php$</exclude-pattern>
+	</rule>
+
+	<!-- Targetted error silencing. This is okay. -->
+	<rule ref="WordPress.PHP.NoSilencedErrors">
+		<exclude-pattern>/src/Helpers/ResourceHelper\.php$</exclude-pattern>
+		<exclude-pattern>/src/Polyfills/AssertClosedResource*\.php$</exclude-pattern>
+	</rule>
+
 	<!-- The TestCase for PHPUnit 8+ will only ever be loaded on PHP 7.2+. -->
 	<!-- The TestListenerDefaultImplementation for PHPUnit 7+ will only ever be loaded on PHP 7.1+. -->
 	<rule ref="PHPCompatibility.FunctionDeclarations.NewReturnTypeDeclarations.voidFound">
@@ -115,4 +145,18 @@
 		<exclude-pattern>/tests/TestCases/TestCaseTestTrait\.php$</exclude-pattern>
 	</rule>
 
+	<!-- These fixtures for the assertEqualObject() tests will only be loaded on PHP 7+/8+ respectively. -->
+	<rule ref="PHPCompatibility.FunctionDeclarations.NewReturnTypeDeclarations">
+		<exclude-pattern>/tests/Polyfills/Fixtures/ChildValueObject\.php$</exclude-pattern>
+		<exclude-pattern>/tests/Polyfills/Fixtures/ValueObject\.php$</exclude-pattern>
+		<exclude-pattern>/tests/Polyfills/Fixtures/ValueObjectUnion\.php$</exclude-pattern>
+	</rule>
+	<rule ref="PHPCompatibility.FunctionDeclarations.NewParamTypeDeclarations.UnionTypeFound">
+		<exclude-pattern>/tests/Polyfills/Fixtures/ValueObjectUnion\.php$</exclude-pattern>
+		<exclude-pattern>/tests/Polyfills/Fixtures/ValueObjectUnionNoReturnType\.php$</exclude-pattern>
+	</rule>
+	<rule ref="PHPCompatibility.Operators.NewOperators.t_spaceshipFound">
+		<exclude-pattern>/tests/Polyfills/Fixtures/ValueObject\.php$</exclude-pattern>
+	</rule>
+
 </ruleset>
diff --git a/.travis.yml b/.travis.yml
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,14 +9,46 @@ This projects adheres to [Keep a CHANGELOG](http://keepachangelog.com/) and uses
 
 _Nothing yet._
 
+## [1.0.0] - 2021-06-21
+
+### Added
+* `Yoast\PHPUnitPolyfills\Polyfills\AssertClosedResource` trait to polyfill the `Assert::assertIsClosedResource()` and `Assert::assertIsNotClosedResource()` methods as introduced in PHPUnit 9.3.0. PR [#27].
+* `Yoast\PHPUnitPolyfills\Polyfills\AssertObjectEquals` trait to polyfill the `Assert::assertObjectEquals()` method as introduced in PHPUnit 9.4.0. PR [#38].
+    The behaviour of the polyfill closely matches the PHPUnit native implementation, but is not 100% the same.
+    Most notably, the polyfill will check the type of the returned value from the comparator method instead of the enforcing a return type declaration of the comparator method.
+* `Yoast\PHPUnitPolyfills\Polyfills\EqualToSpecializations` trait to polyfill the `Assert::equalToCanonicalizing()`, `Assert::equalToIgnoringCase()` and `Assert::equalToWithDelta()` methods as introduced in PHPUnit 9.0.0. PR [#28], props [Marc Siegrist].
+* Polyfills for the PHP native `Error` and `TypeError` classes as introduced in PHP 7.0. PR [#36].
+* README: FAQ section covering functionality removed from PHPUnit and usage with a Phar.
+
+### Changed
+* The minimum supported PHP version has been lowered to PHP 5.4 (was 5.5). PR [#19].
+* `XTestCase`: the visibility of the `setUpFixtures()` and the `tearDownFixtures()` methods has been changed to `protected` (was `public`). Issue [#10], PR [#20], props [Mark Baker] for reporting.
+* README: re-ordered the sections and various other improvements.
+* Initial preparation for PHPUnit 10.0 compatibility.
+* General housekeeping.
+
+### Fixed
+* Issue [#17] via PR [#18] - `AssertStringContainString`: PHPUnit < 6.4.2 would throw a _"mb_strpos(): empty delimiter"_ PHP warning when the `$needle` passed was an empty string. Props [Gary Jones].
+
+[#10]: https://github.com/Yoast/PHPUnit-Polyfills/issues/10
+[#17]: https://github.com/Yoast/PHPUnit-Polyfills/issues/17
+[#18]: https://github.com/Yoast/PHPUnit-Polyfills/pull/18
+[#19]: https://github.com/Yoast/PHPUnit-Polyfills/pull/19
+[#20]: https://github.com/Yoast/PHPUnit-Polyfills/pull/20
+[#27]: https://github.com/Yoast/PHPUnit-Polyfills/pull/27
+[#28]: https://github.com/Yoast/PHPUnit-Polyfills/pull/28
+[#36]: https://github.com/Yoast/PHPUnit-Polyfills/pull/36
+[#38]: https://github.com/Yoast/PHPUnit-Polyfills/pull/38
+
+
 ## [0.2.0] - 2020-11-25
 
 ### Added
 * `Yoast\PHPUnitPolyfills\TestListeners\TestListenerDefaultImplementation`: a cross-version compatible base implementation for `TestListener`s using snake_case method names to replace the PHPUnit native method names.
 * `Yoast\PHPUnitPolyfills\Helpers\AssertAttributeHelper` trait containing a `getProperty()` and a `getPropertyValue()` method.
     This is a stop-gap solution for the removal of the PHPUnit `assertAttribute*()` methods in PHPUnit 9.
     It is strongly recommended to refactor your tests/classes in a way that protected and private properties no longer be tested directly as they should be considered an implementation detail.
-	However, if for some reason the value of protected or private properties still needs to be tested, this helper can be used to get access to their value.
+    However, if for some reason the value of protected or private properties still needs to be tested, this helper can be used to get access to their value.
 * `Yoast\PHPUnitPolyfills\Polyfills\AssertNumericType` trait to polyfill the `Assert::assertFinite()`, `Assert::assertInfinite()` and `Assert::assertNan()` methods as introduced in PHPUnit 5.0.0.
 * `Yoast\PHPUnitPolyfills\Polyfills\ExpectException` trait to polyfill the `TestCase::expectException()`, `TestCase::expectExceptionMessage()`, `TestCase::expectExceptionCode()` and `TestCase::expectExceptionMessageRegExp()` methods, as introduced in PHPUnit 5.2.0 to replace the `Testcase::setExpectedException()` and the `Testcase::setExpectedExceptionRegExp()` method.
 * `Yoast\PHPUnitPolyfills\Polyfills\AssertFileDirectory` trait to polyfill the `Assert::assertIsReadable()`, `Assert::assertIsWritable()` methods and their file/directory based variations, as introduced in PHPUnit 5.6.0.
@@ -35,5 +67,10 @@ Initial release.
 
 
 [Unreleased]: https://github.com/Yoast/PHPUnit-Polyfills/compare/main...HEAD
+[1.0.0]: https://github.com/Yoast/PHPUnit-Polyfills/compare/0.2.0...1.0.0
 [0.2.0]: https://github.com/Yoast/PHPUnit-Polyfills/compare/0.1.0...0.2.0
 [0.1.0]: https://github.com/Yoast/PHPUnit-Polyfills/compare/e8f8b7a73737aa9a5974bd9c73d2bd8d09f69873...0.1.0
+
+[Gary Jones]: https://github.com/GaryJones
+[Marc Siegrist]: https://github.com/mergeMarc
+[Mark Baker]: https://github.com/MarkBaker