rfc-expressive-router-1.1.md

[RFC] zend-expressive-router (and related) changes for Expressive 1.1.

Proposed zend-expressive-router changes include:

• Adding a $path parameter to RouteResult::fromRouteMatch().

  What if instead we were to add a new static method, RouteResult::fromRoute(), and a new instance method, RouteResult::getRoute()? (as I have suggested in zendframework/zend-expressive#398)? This would allow consumers to then pull the path from the Route instead, and provide access to the path, name, allowed methods, options, etc. (e.g., $result->getRoute()->getPath())

  This could even be done in a new 1.3.0 minor release; users who depend on that new feature would need to update their project to pin to the new minor release or later; otherwise, everything continues working as normal.

• Removal of RouteResultObserverInterface and RouteResultSubjectInterface.

  These definitely require a major version bump.

• Changes to RouterInterface::generateUri() signature.

  This also definitely requires a major version bump.

What's interesting about these last two features, however, is that zend-expressive does not use them, which means that technically, it could pin to ^1.3 || ^2.0 safely. Additionally, because the router and template implementations are installed at the project level, users who update would not get the 2.0 version unless they also update the constraints for their given router and template implementations. In other words, there's no breakage.

This is true of the zend-expressive-helpers package as well; it's required by the project, which means that if the developer attempts to update their router and/or template implementation without also updating the zend-expressive-helpers library, Composer will either do nothing, or report the constraint conflict. If you run composer update, nothing happens. If you want the new versions of these, you either edit the composer.json to update constraints, or you do something like composer update "zendframework/zend-expressive-helpers:^3.0" "zendframework/zend-expressive-router:^2.0" "zendframework/zend-expressive-fastroute:^2.0" "zendframework/zend-expressive-platesrenderer:^2.0". This is something we can easily document in the migration guide.

As such, I think if we were to follow my recommendation about a new RouteResult::fromRoute() method, we could do the following:

• A 1.3.0 release of zend-expressive-router with the RouteResult change, as well as the other changes suggested in zendframework/zend-expressive#398.

• A 2.0.0 release of zend-expressive-router with the removal of the RouteResult*Interfaces, and the RouterInterface::generateUri() signature changes.

• New minor releases of each router implementation that pin to the zend-expressive-router 1.3.0 release (so we can make use of the stored Route in the RouteResult instance).

• New major releases of each router implementation that pin to the zend-expressive-router 2.0.0 release (so we can update the generateUri() signatures).

• New major release of zend-expressive-helpers pinning to zend-expressive-router's 2.0.0 release, so that we can update UrlHelper::__invoke() and make use of the new generateUri() signature.

• New major releases of zend-expressive-(twig|plates|zendview)renderer packages that pin to the new zend-expressive-helpers major release, so that they may update their own helpers.

Expressive 1.1 can then pin to zend-expressive-router ^1.3 || ^2.0, and pin each of the routers listed in the dev requirements to their latest v1 minor releases OR 2.0 series (e.g., "zendframework/zend-expressive-fastroute": "^1.3 || ^2.0"; as the functionality tested in zend-expressive is unrelated to the BC changes they introduce, we can do this). We would also update the skeleton to prefer the latest versions of each.

How does this sound?

I get comment notifications via https://giscus.co/, so feel free to comment here if desired. Once we reach consensus, we can start opening issues and updating the Expressive 1.1 project.

@weierophinney I responded to your e-mail from a few days back with some items to review for a couple of the releases.

I actually did not get any notifications for this Gist despite having Giscus authorized... I even checked my spam, so not sure what's going on...

I'm totally fine with continuing to collaborate via Gist for ease for formatting / posterity / etc., but if so, it'd probably be best to ping me via e-mail to check on a response until such time that the notifications work properly.