Router::reverse() docs missing, inclusion advice desired

[dreamingmind]

As discussed in this form thread, Router::reverse() is not included in the docs.

I'm interested in adding a section explaining it in docs/en/development/routing.rst

Before I begin I'm looking for input from any interested parties:

Since this document uses the term and concept of reverse routing extensively but does not mention this method, I'm not sure where in the flow of information to include a section on reverse() or how to discuss its behavior without seeming to contradicting or confused the issue.

Any input is welcome.

Routing is not one of the features I am strong on, so I'll be climbing a bit of a hill as I grapple with this document and its content.

My initial thoughts about including these changes

There seem to be 4 specific examples referring to reverse routing. Possibly each of these could include an example using reverse() and some discussion of its use.

And/Or

Beginners on the forum often struggle with the lack of context in the docs (as do I).

So I’m tempted to explain a little more about the why of this feature vs the methods shown. This is a grey area though since in general the Cake Docs just present facts, not reasons.

I don’t know if the .rst docs format allows for collapsible sections (like the detail blocks in the forum) but they would be an ideal place to tuck away a little explanation for users who wanted it.

If there is nothing like this, the page is very long and may benefit from having the from-array-to-url processes broken out to a different page.

And/Or

Mentions of this method and the technique of using the params array directly could be added to the HtmlHelper::link() doc and the PaginatorHelper where several methods can benefit.

[markstory]

Router::reverse() hasn't historically been in the docs because it isn't something that user-land code frequently uses. Broadly 'reverse routing refers to the process of converting URL arrays into URL strings, as it is the 'reverse' process of routing which converts URL strings into URL arrays. Unfortunately the format used by Router::url() differ a bit as a way to help optimize how passed parameters are handled.

I think including Router::reverse() in the docs is a great addition if we include the context on when/why one would use it over the other URL generation methods.

I don’t know if the .rst docs format allows for collapsible sections (like the detail blocks in the forum) but they would be an ideal place to tuck away a little explanation for users who wanted it

It does not. Using Router::reverse() could be included as a section below generating urls

We could also do a better job of giving more examples of how to generate URLs. I think your scenario of generating a URL for the current route could be achieved with:

$pass = $this->getRequest()->getAttribute('params')['pass'];
$this->Html->link('inactive', array_merge(['?' => $query], $pass));

But that isn't obvious from the docs.

[dreamingmind]

Ok. I'll see what I can make of it.

[dreamingmind]

This now relates to Pull Request #6739

[othercorey]

Added in #6739