feat!: add append and prepend handler instead of reverse execution

[tflori]

see #580

BREAKING CHANGE: since pushHandler() was actually prepending handlers
it is now an alias for prependHandler but popHandler() is still
removing the last handler.

This should make the interface clearer: pushing (append) is now executed at the end while prepend is alias by the deprecated pushHandler() method.

People using the deprecated pushHandler() method and popHandler() should update the implementation to use shiftHandler() and prependHandler().

[staabm]

IMO we should be very careful, because pushHandler() is one of the most important whoops APIs

[tflori]

@staabm I guess that is the reason @denis-sokolov suggested to create new methods and mark this as deprecated.

Because of the reverse execution push was not actually appending handlers as the name indicates. The API is not changing but the naming to clear this out.

[denis-sokolov]

Wonderful PR, thank you!

Could you rename the handlerStack variable to handlerQueue? Since it’s not first in, first out anymore?

[tflori]

sure thing

[denis-sokolov]

🚀

[filips123]

pushHandler() should probably also trigger E_USER_DEPRECATED to inform users who still use it.

Also, shouldn't RunInterface also be updated?

[GrahamCampbell]

Adding methods to an interface is a major breaking change.

[filips123]

Ok, so it should be added in Whoops 3.0.
What about triggering E_USER_DEPRECATED on pushHandler().

[denis-sokolov]

The method will always work, there is no need to force users off it.

[filips123]

But it is deprecated, so it could maybe be removed in some future major version.

[icanhazstring]

Nice change 👍
I am fine with the depreciation warning. As in dev environment those warnings should pop up but not in production of course.

As an example: Zend did the same with the getServiceLocator method on controllers from v2 to v3. So this practice isn't new. So when it's deprecated, notify users about it using the warning and the @deprecated warning.

[denis-sokolov]

Beware that these changes have been partially reverted in 2.6.0, we should not have released them in a patch version. Please note the PR and the accomodating work was great, the fault is thoroughly on me. #639 (comment)