Improve PhpStorm's auto-complete of "DriverInterface" method arguments

[uuf6429]

The changes are fully backword compatible.

[codecov]

Codecov Report

Merging #847 (e96bbea) into master (2bec260) will not change coverage.
The diff coverage is n/a.

@@            Coverage Diff            @@
##             master     #847   +/-   ##
=========================================
  Coverage     98.50%   98.50%           
  Complexity      345      345           
=========================================
  Files            23       23           
  Lines          1002     1002           
=========================================
  Hits            987      987           
  Misses           15       15           

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[uuf6429]

@stof / @aik099 any chance getting this PR merged?

Sadly, I keep ending up adding such attributes at the driver level, which only benefits the drivers themselves (and would be redundant with this PR merged).

[aik099]

Merging, thank you @uuf6429 .

Please explain the difference in working with DriverInterface with/without having these PhpStorm-specific attributes available.

[uuf6429]

Please explain the difference in working with DriverInterface with/without having these PhpStorm-specific attributes available.

If you mean why those attributes are useful:

Participating IDEs* (mainly JetBrains) should be able to highlight such parameters, which improves developer experience for maintainers but also direct driver users.

(instead of a plain green text for the entire strings)

At the moment, it works for me already, because the IDE realises that I'm using the classic driver, which already has those attributes.

For driver maintainers, unless they add the attributes themselves, they also will not get that hinting. These attributes are useful for driver maintainers as well, since drivers tend to call such methods themselves.

Hope that answers your question, let me know if you meant something else.

*theoretically, anyone can make use of those attributes, since they're available as a composer package.

[stof]

Projects should almost never use the driver directly though. They are expected to work with the high-level Mink API.

[uuf6429]

@stof agreed, I believe there are other cases in mink where it makes sense to support that.

For example, in my current project, we developed our own selector/locator system with slightly better DX that is still based on mink:

(maybe at one point I'll make it into a mink PR)

---

In any case, I believe those attributes are low-effort/impact quick wins.

[aik099]

@uuf6429 , at least you can create an issue in Mink with that idea. This way at it won't be forgotten.