Improve documentation of handling of deprecations, notices, and warnings

[8ctopus]

I’m testing my packages for compatibility with PHP 8.4.1 and some dependencies trigger deprecation warnings.

Is there a way to configure PHPUnit to report deprecation warnings only for my package and ignore those from dependencies? In other words, ignore all deprecations within the vendor dir?

[sebastianbergmann]

Yes, this is possible. Unfortunately, not everything that is possible is already documented (well enough), but the some documentation is available here.

For the most common use case, you want to have this in your phpunit.xml configuration file:

<source ignoreIndirectDeprecations="true" restrictNotices="true" restrictWarnings="true">
    <include>
        <directory>src</directory>
    </include>
</source>

• <source><include><directory>src</directory></include></source> tells PHPUnit that you consider only code in the src directory as your own code (first-party code) (as well as your test code)
• Every thing else, for example code in vendor, is considered "now your own code" (third-party code)
• ignoreIndirectDeprecations="true" tells PHPUnit that you are only interested in E_DEPRECATED and E_USER_DEPRECATED that are triggered in your own code from your own code
• restrictNotices="true tells PHPUnit that you are only interested in E_NOTICE and E_USER_NOTICE triggered in your own code
• restrictWarnings="true tells PHPUnit that you are only interested in E_WARNING and E_USER_WARNING triggered in your own code

[8ctopus]

Thank you!

[laceysanderson]

Another great new piece of functionality which it would be great to highlight more on the docs for handling of deprecations is the #[IgnoreDeprecations']. Right now it is mentioned but more as a footnote that I missed on multiple careful reading of the docs 🙈

https://docs.phpunit.de/en/11.5/error-handling.html#expecting-deprecations-e-user-deprecated

I would have found it extremely helpful to see a note box discussing maintaining tests of deprecated code until removal and what best practice is. Based on the functionality added to PHPUnit and the ethos I see throughout the docs and the issue queue, I suspect best practice is to have this attribute AND expectUserDeprecationMessage() only on tests directly testing deprecated functionality? If so, maybe something like this notice box added to the section on expectUserDeprecationMessage() would ensure this page shows up in search results?

.. admonition:: Maintaining deprecated code until removal

   When deprecating functionality, we often run into the question of how to deal with the
   existing tests? In order to ensure deprecations caused by using deprecated methods throughout 
   your code are caught, best practice is to have phpunit configured to fail on deprecations 
   and then use the `#[IgnoreDeprecations']` attribute **only on tests directly testing the
   deprecated functionality**. This paired with usage of `expectUserDeprecationMessage()` allows
   you to keep these tests without failing the whole test suite, ensures the expected deprecation
   is being shown and ensures that any unexpected calls to these methods in other tests 
   still cause failure.