Presentation of minimum version is not clear (PHP 8 >= 8.5.0)

[GromNaN]

Hi. It's really helpful to indicate in which version a feature was added, but I think the display could be improved.

Affected page

https://www.php.net/manual/en/function.array-first.php

Current issue

When I read the PHP version constraint, it's not clear what version support the new function (PHP 8 or 8.5.0).

Suggested improvement

The presentation should be improved with a sentence like this:

Added in PHP 8.5.0

Additional context (optional)

PHP.watch only shows the version it was introduced:

[Girgias]

This might be a more a PhD related issue, as that's probably where the version.xml info is merged into the page.

[kamil-tekiela]

I agree it's difficult to read, but it's also difficult to design a better way. The function could have been added in a minor release. It could also have been removed in a minor release. How to clearly document it? It's not possible to just have a single version number as this would lose the information.

[GromNaN]

Upon searching, I found that this information is available as is in the document repository and not transformed for display in the website. https://github.com/php/doc-en/blob/ee5ee84013f11aaaf01b09484bc9aa3225379748/reference/array/versions.xml

What I don't understand is why we need to list all the major versions of PHP. We could just have

Added in PHP 4.0.6, Removed in PHP 9.0.0

[kamil-tekiela]

• What if it was added in PHP 4.0.6, but only added to PHP 5 in PHP 5.0.5, and removed in PHP 7.4.0?
• What if it was added in PHP 4.0.6, removed in 4.0.7, and added back in 4.0.8?

[GromNaN]

These edge cases don't seem to exist in the actual documentation data. Auditing all versions.xml files across en/reference/*/ shows:

Added in PHP 4.0.6, but only added to PHP 5 in PHP 5.0.5

No such entry exists. Whenever a function spans multiple major branches, the subsequent branches are always listed without a minimum version (e.g. PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8).

Added in PHP 4.0.6, removed in 4.0.7, added back in 4.0.8

No such entry exists either.

The existing patterns that do use < are straightforward removals like:

• PHP 4 >= 4.2.0, PHP 5 < 5.1.0 (dio_open)
• PHP 5, PHP 7 < 7.4.0 (fbird_* / interbase, mcrypt_*)
• PHP 4, PHP 5, PHP 7, PHP 8 with a separate removed="PHP 8" attribute (money_format, __autoload)

In all these cases, "Added in PHP X.Y.Z" would be sufficient and unambiguous. The extra major-version noise (PHP 5, PHP 7, PHP 8) conveys no information that isn't already implied by the minimum version.

[kamil-tekiela]

• https://www.php.net/manual/en/function.ldap-modify-batch.php
• https://www.php.net/manual/en/function.mb-check-encoding.php
• https://www.php.net/manual/en/reflectionfunctionabstract.getclosurecalledclass.php

[kamil-tekiela]

I agree with you. After doing some analysis, I believe this needs to be cleaned up. It's possible that when this was first added, the idea was that it should only list the versions it was added in, but with time, something went awry. As time goes on, this will only become increasingly difficult to read, e.g., PHP 9.

I think a simple approach would be enough:

1. Go through all the version.xml files and add an attribute "added", "removed", "deprecated" as applicable. For example, mb_check_encoding would have added="PHP 4.4.3, PHP 5.1.3" with no removed or deprecated.
2. Then in phd, we can adjust the code to check if added, deprecated, removed is present. If yes, we show that instead with the appropriate label.
3. Once everything is cleaned up, we can drop the "from" attribute as I doubt any other code relies on it, but this needs to be verified too. Maybe tools like PHPStorm or PHPStan read it automatically.

I don't know how to represent when an extension was boundled or unboundled to PECL.