PHPUnit

PHPUnit 11

The PHPUnit development team is pleased to announce the immediate availability of PHPUnit 11. This release adds new features, modifies and removes existing functionality, and fixes bugs.

A detailed list of changes can be found here. The most significant changes are discussed below.

OMGWTFBBQ? I must upgrade to PHPUnit 11 immediately!

No, you do not.

Just because PHPUnit 11 has been released today does not mean that PHPUnit 9 or PHPUnit 10 will no longer work. While old versions of PHPUnit will eventually stop receiving bug fixes, we will keep them compatible with new versions of PHP for as long as possible.

We sincerely hope that you do not use the Death Star Version Constraint and therefore do not automatically and unintentionally upgrade to a new major version of PHPUnit.

Upgrading a dependency to a new major release must be a conscious decision that is part of a defined process. This process should include, at a minimum, reading an announcement like this and the ChangeLog.

PHPUnit 11 requires PHP 8.2 or later. If you are not using PHP 8.2 or PHP 8.3, you will not be able to use PHPUnit 11 right away.

We are confident that PHPUnit 11 works as intended, but in some respects it works differently than previous versions. For example, functionality that was only soft-deprecated in PHPUnit 10 is now hard-deprecated in PHPUnit 11. And functionality that was hard-deprecated in PHPUnit 10 has been removed in PHPUnit 11.

You should not even try to upgrade to PHPUnit 11 if you cannot run your test suite using PHPUnit 10.5 without getting deprecation warnings.

If the above does not put you off, then please: go ahead and upgrade! And should you encounter a problem, please report it.

Major Changes in PHPUnit 11

Test Doubles

We are cleaning up PHPUnit's functionality for programmatically creating test stubs and mock objects. We are doing this primarily to make working with test doubles easier and less confusing for developers using PHPUnit. But we are also doing this to reduce complexity in the implementation by removing features that are not as necessary as they were a decade or two ago (as well as features that probably should never have been implemented in the first place).

The methods for creating mock objects for abstract classes and traits were already soft-deprecated in PHPUnit 10, they are now hard-deprecated and will be removed in PHPUnit 12. Testing concrete classes in isolation from their abstract base classes (and vice versa) as well as testing traits in isolation from the classes that use them has not proven to be useful.

Several releases ago, we introduced special methods, such as createStub() and createMock(), for creating test stubs and mock objects, respectively. These methods allow developers to make their intentions clear in the test code they write. Need a test stub to isolate the code under test from a dependency? Use createStub() to create a test stub. Need to test communication between two objects? Use createMock() to create a mock object.

Configuring expectations on an object created with createStub() will trigger a deprecation warning in PHPUnit 11 and will not work in PHPUnit 12.

This presentation has more details on when test stubs and mock objects should be used.

Metadata

PHPUnit 10 introduced support for PHP 8 attributes to add metadata to test classes and test methods. Previously, annotations in special PHP comments called "docblocks" or "doc-comments" were the only way to add metadata to units of code.

In PHPUnit 11, the annotations that can be used in special PHP comments to add metadata to test classes and test methods are deprecated. Support for these annotations will be removed in PHPUnit 12.

Getting PHPUnit 11

We distribute a PHP Archive (PHAR) that contains everything you need in order to use PHPUnit. Alternatively, you may use Composer to download and install PHPUnit as well as its dependencies.

Here is a tutorial that gets you started.

Supported Versions

Detailed information on supported versions of PHPUnit is available here. Below is a summary as of February 2, 2024:

  • PHPUnit 11 receives bug fixes until February 6, 2026
  • PHPUnit 10 receives bug fixes until February 7, 2025
  • PHPUnit 8 and PHPUnit 9 no longer receive bug fixes

The versions listed above will be kept compatible with new PHP versions as long as possible.

Looking Forward

Here is the roadmap for the next year:

Follow PHPUnit in the Fediverse

Consider following @[email protected] to stay up to date with PHPUnit's development.