Upgrading PHPUnit - "metadata in doc-comments is deprecated [...] use attributes instead"

> composer test

Metadata found in doc-comment for method
MyTest::it_loads_user_ok(). Metadata in
doc-comments is deprecated and will no
longer be supported in PHPUnit 12. Update
your test code to use attributes instead.

Recently I was working on some package updates for Laravel 11 compatibility. As part of this, the version of PHPUnit I was using was bumped from 9 to 11. I ran the tests, and then started getting warnings like the above. The tests all passed, but a lot of notices were clogging up my terminal.

This is happening because our test code previously looked something like this:

class MyTest extends TestCase
{
    /** @test */
    public function it_loads_the_user_ok()
    {
        ...
    }

The @test doc comment there meaning we don't need to add test into our function names for PHPUnit to pick them up and run them. However, support for these doc comments is being removed in PHPUnit 12, with deprecation warnings being shown in current versions.

From the PR covering this update:

Support for attributes in PHPUnit will be implemented like so:

  • PHPUnit 10 will first look for metadata in attributes before it looks at comments
  • When metadata is found in attributes, metadata in comments is ignored
  • Support for metadata in comments is closed for further development (bugs will be fixed, but no new functionality will be implemented based on annotations)
  • Support for metadata in comments will be deprecated in PHPUnit 11
  • Support for metadata in comments will be removed in PHPUnit 12

The solution is to use attributes to replace these comments. Our example above becomes:

use PHPUnit\Framework\Attributes\Test;

class MyTest extends TestCase
{
    #[Test]
    public function it_loads_the_user_ok()
    {
        ...
    }

In this case, the @test comment is replaced by a Test attribute, loaded from PHPUnit\Framework\Attributes\Test. Once the comments get swapped out for attributes, the warnings go away, and the test suite is nice and clean again!

A much cleaner test run!
A much cleaner test run!

The full list of replacements, and how they map from comment to attributes, is available on the PHPUnit PR.

Before and after
Before and after

PHPers Summit 2024 Speaker

PHPers Summit 2024

In June 2024, I'll be giving a talk at the PHPers Summit in Poznan, Poland. I'll be covering the quick wins available to backend developers who are asked to help with frontend speed issues - all the tips and tricks to improve load speed of the usual speed-hogs videos, fonts, and images!

Get your ticket now and I'll see you there!


Share This Article

Related Articles


Lazy loading background images to improve load time performance

Lazy loading of images helps to radically speed up initial page load. Rich site designs often call for background images, which can't be lazily loaded in the same way. How can we keep our designs, while optimising for a fast initial load?

Idempotency - what is it, and how can it help our Laravel APIs?

Idempotency is a critical concept to be aware of when building robust APIs, and is baked into the SDKs of companies like Stripe, Paypal, Shopify, and Amazon. But what exactly is idempotency? And how can we easily add support for it to our Laravel APIs?

Calculating rolling averages with Laravel Collections

Rolling averages are perfect for smoothing out time-series data, helping you to gain insight from noisy graphs and tables. This new package adds first-class support to Laravel Collections for rolling average calculation.

More