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.

@michaelmoussa and @xtreamwayz — zend-expressive-router has been updated, as have each of the implementations. All have new minor releases. (In the case of the Aura implementation, several patch releases as well, as I discovered subtle differences in how v3 of Aura.Router works in comparison to v2!) I've also got functionality added to zend-expressive, though it's not as proposed: it's new, optional functionality via 2 new middleware (ImplicitHeadMiddleware and ImplicitOptionsMiddleware), which make use of the new zend-router features.

From what I can see, then, the only things still in play are the changes to zend-expressive-helper. Those do not impact zend-expressive, but will impact the skeleton application. Michael, let me know if there's anything I can do to assist in that release.

At this point, my plan is to wait until after the holidays for the 1.1 release, as there's a number of other moving parts that need to become stable before we can finish out.

@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.