Provide PHP 8.1 compatibility

[matbech]

This silences the deprecated warnings in PHP 8.1:

• It creates polyfills for each of the ArrayObject, FastPriorityQueue, Parameters, PriorityList, PriorityQueue, SplQueue, and SplStack implementations. The new "legacy" implementations keep the same functionality as was present in previous versions, while the "PHP 8.1" implementations add typehints that are required in order to remove deprecation warnings under PHP 8.1 (PHP 8.1 deprecates the ability to define extensions of internal classes that change signatures in any way, even if they fulfill the contravariance/covariance rules.)
  • Autoloading rules alias the appropriate implementation to the original class name based on the PHP version in use.
• It adds __unserialize() and __serialize() implementations to all classes that previously implemented the Serializable interface. The Serializable implementations now consume these new methods to make them forwards compatible.
• Because of the polyfill implementations, a large number of code improvements were created to fix new issues flagged by Psalm due to the new class names. In most cases, these are adding type checking to ensure code will work correctly.

BC concerns

The PHP 8.1 implementations add typehints to signatures where they did not previously exist. In each case, these are compatible with the previous implementation, but they do pose breakage for anybody extending the classes and overriding the relevant methods. However, these would lead to deprecation warnings, and, in some cases, fatal errors under PHP 8.1.

Fixes #24

[weierophinney]

@matbech I'm making progress on the 8.1 compat, and should have a comprehensive patch to push tomorrow that builds on what you've done here. Thanks for getting this started!

[matbech]

@weierophinney Thank you for picking this up.

[weierophinney]

@laminas/technical-steering-committee I'd like a review on this one, as (a) laminas-stdlib is used everywhere, and (b) while I think the approach makes sense (as all potentially non-BC changes are restricted to PHP 8.1, where the code would break without the changes), it is a potential BC break. Additionally, if accepted, it will likely become the template for when we need to introduce PHP 8.1-specific functionality in other components.

[nikic]

The intended way to handle this problem is to annotate methods with the #[ReturnTypeWillChange] attribute, and then only change the signatures when you are able to (i.e. your next major version).

What is the motivation for not following that approach, and duplicating these class declarations instead? This seems like a lot of complication for unclear gain.

(PHP 8.1 deprecates the ability to define extensions of internal classes that change signatures in any way, even if they fulfill the contravariance/covariance rules.)

I don't get what this refers to. Extensions of internal classes should be following normal variance rules.

[weierophinney]

The intended way to handle this problem is to annotate methods with the #[ReturnTypeWillChange] attribute, and then only change the signatures when you are able to (i.e. your next major version).

What is the motivation for not following that approach, and duplicating these class declarations instead? This seems like a lot of complication for unclear gain.

It started because I was first getting CS failures (as in the tool just failed completely due to fatal errors), and then a whole bunch of new Psalm errors (due to signature differences), and then failure to run the test suite across all supported versions (due, again, to errors thrown because of deprecations being raised).

When running our test suite, we have error reporting report deprecations so we can spot issues like this early and adapt; it prevents issues later once deprecations in the engine are actually removed.

Essentially, I needed solutions that would work across all supported versions, while simultaneously ensuring that our code won't needlessly break in the future.

(PHP 8.1 deprecates the ability to define extensions of internal classes that change signatures in any way, even if they fulfill the contravariance/covariance rules.)

I don't get what this refers to. Extensions of internal classes should be following normal variance rules.

This was me misreading errors as I was trying to resolve everything; I later discovered that they do follow normal covariance/contravariance rules. So please ignore that statement.

[boesing]

I would prefer keeping changes at a minimum rather than duplicating code just to fulfill php upgrade requirements. if the codestyle tool fails, we might switch that rather than changing code in that way. if psalm has issues, we should find a way to make it understand annotations AND attributes (are we the only framework which uses psalm with docblock and attributes?).

So I would have expect to add a few attributes and we are ready for 8.1 but this escalated quickly. if all of this is needed to make our tools happy, thats odd

[weierophinney]

I would prefer keeping changes at a minimum rather than duplicating code just to fulfill php upgrade requirements. if the codestyle tool fails, we might switch that rather than changing code in that way.

I'll see if I can develop an alternative patch later today.

[weierophinney]

Closing in favor of #35 , which provides a simpler approach.