PHPUnit 13.1: The Mandatory Shift to Attributes

Host: Hey everyone, welcome back to Allur! I’m your host, Alex Chan, and I am so glad you’re joining us today. If you’ve been in the PHP ecosystem for a while, you know that our tools are constantly evolving, usually in these nice, incremental steps. But every once in a while, a release comes along that feels less like a step and more like a... well, a bit of a "burn the ships" moment. Host: To help me break all of this down, I am joined today by Marco Rossi. Marco is a veteran backend architect and a long-time contributor to several open-source testing utilities in the PHP world. Marco, it is so great to have you on Allur. Guest: Thanks for having me, Alex! It’s an exciting—if a little bit chaotic—time to be talking about PHPUnit. People are definitely seeing those "skipped" test counts and realizing they have some homework to do. Host: Exactly! So, Marco, let’s jump right in. We’ve known attributes were coming since PHP 8.0, and PHPUnit has been gently nudging us this way for a few versions now. But 13.1 feels... aggressive. Why did Sebastian Bergmann and the team decide that *now* was the time to completely rip out docblock support? Guest: Yeah, it does feel like a "breaking" minor version, which is rare. But the "why" really comes down to technical debt. For years, PHPUnit had to include this fairly complex custom parser just to read comments. It was essentially using regex to find things like `@test` or `@group` inside a string. And as a developer, that’s always been a bit of a hack, right? It’s metadata living in a place the PHP engine doesn’t actually care about. Host: Right, it’s just a comment to the engine. Guest: Exactly. So by moving to native PHP 8 attributes, PHPUnit gets to delete all that legacy parsing code. It makes the framework leaner and faster. But more importantly for us as developers, attributes are first-class citizens. They get compiled into the opcache. They’re accessible via the Reflection API. And—this is my favorite part—your IDE actually knows what they are. No more "silently skipped" tests because you accidentally typed `@tset` instead of `@test`. Host: Oh man, I have definitely lost thirty minutes of my life to a typo in a docblock. That "aha" moment when you realize the test wasn't passing, it just wasn't *running*... it’s the worst. Guest: (Laughs) We’ve all been there! With attributes, your IDE can give you autocomplete and static analysis. It’s much more robust. Host: So, let's talk about the physical change. If I open up a test file today, what am I actually changing? It’s not just replacing a character, right? Guest: It’s a bit more than that. So, the old way, you’d have your docblock with `/** @test */`. Now, you’re using the PHP attribute syntax. So it’s `#` right above the method. But you also have to remember to import the attribute class at the top of your file. Host: Right, the `use` statement. Guest: Exactly. `use PHPUnit\Framework\Attributes\Test;`. And it's the same for everything else. `@group` becomes `#`. And data providers—this is a big one—become `#`. It’s much more explicit. It actually looks like code now, not just a hint for the editor. Host: I noticed in the release notes that things like environment requirements are moving there too. Like `#` or `#`. Is it harder to manage those now? Guest: Actually, I think it’s easier. It moves that logic out of the "comment realm" and into structured metadata. It’s very clear what the requirements are. One thing to watch out for, though, is that PHPUnit 13.1 is getting a lot stricter about *how* you write your data providers. They really want those to be static methods now. Host: Interesting! Why the push for static data providers? Guest: It’s mostly about state and performance. If the data provider is static, PHPUnit can figure out what tests it needs to run without necessarily instantiating the whole test class first. It keeps things clean. If you have a huge test suite, those little performance gains across thousands of tests really add up. Host: That makes sense. Now, let’s talk about something that caught my eye in the 13.1 docs: "Vigilant Mode." That sounds very... Batman. What is it actually doing? Guest: (Laughs) It does sound a bit intense, doesn't it? Basically, it’s a collection of settings in your `phpunit.xml` that forces you to be a "better" developer. One of the biggest ones is the "Risky Test" detection. It will fail a test if it executes but doesn't actually perform an assertion. Host: Oh, I love that. Because there’s nothing more dangerous than a green test that isn’t actually checking anything. Guest: Exactly! It’s a false sense of security. 13.1 also gets really cranky about unintentional output. So if you left a `var_dump` or an `echo` somewhere in your code, Vigilant Mode will catch that and fail the test. It forces you to keep your output clean. And then there are performance thresholds. You can actually set a time limit. Like, "If this unit test takes longer than 100 milliseconds, fail it." Host: Wow, that is a bold move. I can imagine some developers being a bit frustrated by that, but it really prevents that "integration test creep" where your unit test suite slowly becomes this five-minute monster. Guest: It really does. It’s about maintaining that fast feedback loop. If a unit test is slow, it’s usually a sign that it’s doing too much—maybe hitting a database or a file system when it should be mocking those things. Host: So, Marco, let’s get real for a second. Most of the people listening probably have hundreds, maybe thousands of tests using the old `@test` annotations. The thought of manually rewriting every single test header sounds... well, like a nightmare. Is there a better way? Guest: Oh, absolutely. Please, please do not do this by hand. You will lose your mind. The community has already solved this. There’s a tool called Rector—it’s a reconstructor tool for PHP—and they have specific rules for the PHPUnit 13 transition. You can literally run a single command, and it will go through your entire codebase, find the docblocks, convert them to attributes, and add the correct `use` statements at the top. Host: That is a life-saver. So the workflow is: run Rector, then turn on Vigilant Mode, and see what breaks? Guest: Precisely. Use Rector to handle the syntax, then use 13.1’s strictness to find the underlying issues in your test logic. It’s a great opportunity to do some "spring cleaning" on your codebase. Host: I love that. It’s like the framework is forcing us to level up. Before we wrap up, Marco, if someone is sitting there right now with a PHP 8.1 or 8.2 project, what’s the first step they should take today? Guest: First, check your PHPUnit version. If you’re on 10 or 11, you’re already seeing deprecation warnings. Don't ignore them. Second, get Rector installed. Run a dry run and see how much changes. And third, start making your data providers static. That’s usually the part that requires the most "human" thought during the upgrade. Host: Great advice. Marco, thank you so much for joining us and demystifying this. It sounds like a big change, but ultimately one that’s going to make our suites a lot faster and more reliable. Guest: Totally agree. Thanks for having me, Alex! Host: Of course! And thanks to all of you for tuning in to Allur. If you want to see examples of the new attribute syntax or find the Rector rules Marco mentioned, check out the show notes for links to the official PHPUnit documentation and the migration guides. This is a big shift, but it’s one that really brings PHP testing into the modern era.