PHPUnit

PHPUnit 12

The PHPUnit development team is pleased to announce the immediate availability of PHPUnit 12. 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 12 immediately!

No, you do not.

Just because PHPUnit 12 has been released today does not mean that PHPUnit 10 or PHPUnit 11 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 12 requires PHP 8.3 or later. If you are not using PHP 8.3 or PHP 8.4, you will not be able to use PHPUnit 12 right away.

We are confident that PHPUnit 12 works as intended, but in some respects it works differently than previous versions.

For example, functionality that was only soft-deprecated in PHPUnit 11 is now hard-deprecated in PHPUnit 12. And functionality that was hard-deprecated in PHPUnit 11 has been removed in PHPUnit 12. You can find details about deprecations here:

You should not even try to upgrade to PHPUnit 12 if you cannot run your test suite using PHPUnit 11.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 12

Test Doubles

We cleaned up PHPUnit's functionality for programmatically creating test stubs and mock objects. We did this primarily to make working with test doubles easier and less confusing for developers using PHPUnit. But we also did 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 have been removed. 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, createStub() and createMock(), for example, to create 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.
This presentation has more details on when test stubs and mock objects should be used.

Configuring expectations on an object created with createStub() did already not have an effect anymore since PHPUnit 10 and triggered a deprecation since PHPUnit 11. In PHPUnit 12 this is no longer possible.

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 support for the annotations that can be used in special PHP comments to add metadata to test classes and test methods was deprecated. Support for using annotations has now been removed and you need to migrate your tests from annotations to attributes.

Getting PHPUnit 12

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 7, 2025:

  • PHPUnit 12 receives bug fixes until February 5, 2027
  • PHPUnit 11 receives bug fixes until February 6, 2026
  • PHPUnit 10 and older versions 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.