Link to impersonation cookbook article

[ravage84]

I war reading DerEuroMark's recent article about his TinyAuth plugin, which mentions the impersonation feature built into the Authorization plugin and wanted to look up the API. After that, I wanted to look up the documentation for that feature.

Having the links in the API to the docs helps devs to find what they look for.

[jamisonbryant]

@see tags are typically reserved for linking related classes. I believe the @link tag would be more appropriate.

Also worth nothing that we rarely link anywhere except the main Cake website, the PHP docs, or a few IETF RFCs. I feel like linking between code and docs creates a potential fragility when either the docs get updated, or more methods get added that reference those docs. It will be a chore to keep up-to-date. What if URLs change? Also, we're specifically endorsing 'en' language by using these links, are we not?

[dereuromark]

The en part is fine imo. I would usually prefer latest/ for latest docs
That often solves the wrong urls.
But can also be a follow up topic.

[jamisonbryant]

The en part is fine imo

If others are fine with 'en', I am too, I just wanted to point it out since we're a multi-lingual framework.

I would usually prefer latest/ for latest docs

It seems those are not live yet, as I tried a few different URLs and they all 404'd.

[ravage84]

@see tags are typically reserved for linking related classes. I believe the @link tag would be more appropriate.

As far as the current guide of phpDoc goes, both, @seeand @link, can be used for that:

• https://docs.phpdoc.org/guide/references/phpdoc/tags/see.html
• https://docs.phpdoc.org/guide/references/phpdoc/tags/link.html

Also worth nothing that we rarely link anywhere except the main Cake website, the PHP docs, or a few IETF RFCs. I feel like linking between code and docs creates a potential fragility when either the docs get updated, or more methods get added that reference those docs. It will be a chore to keep up-to-date. What if URLs change? Also, we're specifically endorsing 'en' language by using these links, are we not?

I personally have added a few links like this in the framework code to the docs over the past 12 years or so.
Always in English because it's the most updated one and to the code-compatible version of the docs respectively.

A quick search for both annotations linking to the docs for the framework code:

• https://github.com/search?q=repo%3Acakephp%2Fcakephp+%22%40see+https%3A%2F%2Fbook.cakephp.org%22&type=code
• https://github.com/search?q=repo%3Acakephp%2Fcakephp+%22%40link+https%3A%2F%2Fbook.cakephp.org%22&type=code

But yeah, it's an small, added chore when things change, which they don't do that often.

Also, we could harmonize the use of @link or @see for that.

[LordSimal]

It seems those are not live yet, as I tried a few different URLs and they all 404'd.

I have the branch ready for the NGINX config to enable that feature, just need write permissions on the site-book repo to push the branch.

[LordSimal]

/latest URLs work now for the core book and all plugins books. See cakephp/site-book#1

[ravage84]

/latest URLs work now for the core book and all plugins books. See cakephp/site-book#1

Thanks!

Though, someone working with an older verion of the code, reading through the API, would be linked to the too new documentation.
Thus, I would prefer to keep it as proposed.