Php8.1 resolve json serializable return datatype deprecation

[MarkBaker]

Resolution for Issue #144

As of PHP 8.1, PHP adds return type declarations to the PHP native functions and interfaces.

For the JsonSerializable::jsonSerialize() interface method, the new signature is:

function jsonSerialize(): mixed {}

As this library still supports PHP 7.3, it is not possible to add this return type, as the mixed return type only became available in PHP 8.0.

As prior to PHP 8.0, attributes are ignored as if they were comments, it is safe to add the attribute to the library.

To prevent PHPCS tripping up over "something" existing between the function docblock and the declaration, PHPCS 3.6.0 should be used, which is the first PHPCS version with full PHP 8.0 syntax support in the sniffs; but that should be done as a separate PR.

[mnapoli]

Thank you for tackling this @MarkBaker!

Could we also drop support for PHP 7.3? People using PHP 7.3 will still be able to install the current version of php-enum anyway. That way we bump to PHP 7.4.

WDYT?

[MarkBaker]

I see no problem with that, even though my own libraries using this are PHP >=7.2 and will remain so at least until next year. This change doesn't create any BC break, but the previous versions are there anyway; and it's always good to give a little push to upgrade when a new version is .released, even if people aren't yet ready to take the bigger step to PHP 8.

[mnapoli]

Oh I realize that means we must bump to PHP 8.0, because mixed won't be supported on PHP 7.4 🤔 (or I'm missing something)

[MarkBaker]

Actually you don't need to bump to 8.0 and apply mixed as the return datatype for jsonSerialized, not with this change. With PHP 8.1, you would normally get the deprecated notice about the mismatch in the jsonSerialized() interface signature; but the #[\ReturnTypeWillChange] annotation suppresses that deprecation notice for PHP 8.1; for PHP 8.0, there's no deprecation notice to suppress because the interface signature does match, so the annotation does nothing (although it is still recognised as an annotation); for PHP < 8.0, the interface signature matches, and the annotation is simply treated as a comment line in the source.

So really the choice is yours: boost the minimum requirement to PHP7.4 for a 1.9.0 release, and modify the jsonSerialize() method signature to have a return datatype of mixed; or this annotation, which allows you to retain backward compatibility with PHP 7.3.

All I'm really doing is offering a choice of approaches.

[mnapoli]

Yep, thanks a lot for all these details, that is actionnable.

Let's merge this one for now, thank you!