Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document return type of Iterator::accept() so that Symfony's DebugClassLoader does not trigger a deprecation warning #74

Merged
merged 1 commit into from
Dec 2, 2021

Conversation

lyrixx
Copy link
Contributor

@lyrixx lyrixx commented Dec 1, 2021

lyrixx added a commit to jolicode/JoliTypo that referenced this pull request Dec 1, 2021
This mitigate the following deprecation #72 (comment)
This could be reverted once sebastianbergmann/php-file-iterator#74
is merged and released.

Note that this does not forbid the component in version 6, but in this
case, PHP 8.0 is required, and so the attribute is not ignored.
@sebastianbergmann
Copy link
Owner

A missing @return bool annotation in a comment does not (and cannot) trigger a PHP deprecation.

@nicolas-grekas
Copy link

nicolas-grekas commented Dec 1, 2021

I can shed some light on the topic:

In order to help the community with adding return types, Symfony's DebugClassLoader triggers a deprecation when a child class doesn't declare a return type while a parent class/interface does.

Because we want this deprecation to be triggered to projects that run on PHP 7, this works by reading @return annotations.
This cannot rely on #[\ReturnTypeWillChange] because 1. attributes require PHP >= 8 and 2. #[\ReturnTypeWillChange] doesn't say what the tentative return type is for userland classes.

This works basically the same as #[\ReturnTypeWillChange], and it's not by mistake since I heavily contributed to the discussion that led to the attribute.

The TL;DR is: when #[\ReturnTypeWillChange] is used, it should also contain an @return annotation that tells the tentative type.

@sebastianbergmann
Copy link
Owner

Thank you for the explanation, Nicolas. But should Symfony's DebugClassLoader not limit itself to code it is responsible for?

@nicolas-grekas
Copy link

nicolas-grekas commented Dec 2, 2021

Symfony's DebugClassLoader is a generic tool that ppl can use to help move to native return types in a smooth way. There is no boundary that would define the code it is responsible for. We enable it by default in Symfony 5.4 because we figured out that's the best way to encourage everybody to adopt native return types (starting with userland apps first.)

@wouterj wrote a nice article about the process at https://wouterj.nl/2021/09/symfony-6-native-typing if you want to have a look (the article targets end users but the tool is also designed to help lib authors.)

DebugClassLoader as been designed to make this a win situation for everybody: if a codebase makes its return types super clear, then interpreting said codebase become very easy, and DebugClassLoader is able to make the most out of it, as could any other static/runtime analyzer.

Without the annotation, one has to either run the code on PHP 8.1 and use the getTentativeType(), or use some stub that duplicates the info. This PR makes it obvious what the return type is going to be, using local-only knowledge. If this is considered as an improvement (I do), then adding this annotation is worth it on its own. No need to mention DebugClassLoader to justify the change (but it's still nice to know there are nice practical corollaries to such a PR) :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants