Problem/Motivation
1 - As far as I know, it's dangerous (can lead to hard to trace bugs) to not add cacheability metadata into a response object.
2 - The current code structure leads people in the direction of forgetting to add the metadata, or not even knowing about this.
I'll illustrate that with an example which is me in 2017:
Say, I'm a simple contrib module developer. I have a route where I just want to do a quick thing and then issue a redirect, directly in my Controller, for some reason.
- I look around for a response object and find LocalRedirectResponse. And I find TrustedRedirectResponse, which just from the name sounds like I should be using it, because it's... trusted, right? (There are several other RedirectResponse objects and nothing really says which to use, but either of these ones feels most logical, I guess.)
- It accepts a string.
- I also see a Url object, which looks a bit daunting to me, but it has a toString(). This says something about bubbling metadata but I have no clue what that means and the code is impenetrable, so I ignore it in the end. (Note it doesn't say anything about the fact that unless I pass TRUE here, I could be causing caching-related bugs this way. The character string "cach" occurs zero times in the Url class.)
- So, great. I make a URL through Url::generateFromRoute()->toString() and pass it into my response.
- BOOM! LogicException. Which says something about "Leaked metadata" and "early rendering" which I don't understand.
- Reading the Url class and related code (UrlGenerator, GeneratedUrl...) just makes me feel lost.
- Web searches tell me to just do Url::generateFromRoute()->toString(TRUE)->getGeneratedUrl(), as per e.g. https://drupal.stackexchange.com/questions/187086/trustedresponseredirec... / #2630808-16: Response::getResponse() does not collect cacheability metadata from Url object
- I never find out that this is the wrong advice around totally ignoring cache metadata. There's no other info.
Almost two years later I find out what I should have done , and why. This is (Copypaste from https://www.lullabot.com/articles/early-rendering-a-lesson-in-debugging-...):
$url = $node->toUrl()->toString(TRUE);
// The generated URL string, as before.
$url_string = $url->getGeneratedUrl();
// Add the $url object as a dependency of [ the response ]
$response = new CacheableResponse($url_string, Response::HTTP_OK);
$response->addCacheableDependency($url);
Proposed resolution
We can help people prevent creating obscure bugs / not promoting flawed practices by making the following equivalent possible / hiding the parts of cacheability that they don't need to learn about if they just want to redirect somewhere:
$url = $node->toUrl()->toString(TRUE);
$response = new CacheableResponse($url, Response::HTTP_OK);
(Hmm... I am guessing this means we need to override the CacheableResponse constructor for this example to work, not just CacheableRedirectResponse. I guess... that makes sense? Not 100% sure.)
Alternative proposed resolution
After typing up this issue, I came across the following from Wim Leers in #2491981: There are too many ways to generate URLs and links:
Conclusions/notes
-> we can provide our own RedirectResponse class that does accept Url objects
And... I guess that's true; using Url would be just as good as good as a GeneratedUrl. Again not 100% sure though. (Maybe there's a case against
passing in ungenerated Urls which still have a dependency on some (UrlGenerator) service? That's too fuzzy for my experience level.)
Remaining tasks
You:
- Tell me if it makes sense
- tell me whether to use Url or GeneratedUrl
- tell me how we document additions to method parameters in minor versions of Drupal Core; I can't find that.
(Or provide a patch if you feel like it.)
Me: Provide a patch.
...which should also include a @see https://www.drupal.org/docs/8/api/responses/cacheableresponseinterface in CacheableResponseInterface, because that's excellent info.
User interface changes
None.
API changes
The above.
Data model changes
None.
Release notes snippet
TBD
Comments
Comment #2
roderikComment #4
roderikComment #5
roderikComment #6
roderikI also have a question to readers/reviewers of this issue, about something related.
Should we put an explicit recommendation in the code block of LocalRedirectResponse (for novice-ish developers like me) to think about whether your responses ever need to be cached, and to not use LocalRedirectResponse/TrustedRedirectResponse, but use RedirectResponse instead, if they never need to be cached? Because that can save you potential headaches?
(Reason being that returning cacheable responses
)
Comment #7
roderikComment #8
roderikComment #9
joachim commented> I am guessing this means we need to override the CacheableResponse constructor
Instead of that, we could add a ::fromUrl() static method. That would make it consistent with the Url class itself, which has various fromFoo() static methods.
Comment #10
roderikSounds good, I'll try to do that! (Unless people beat me to it. It may wait a bit, I'll be away for a week.)
Also, every time I try to determine where to implement this method, I get confused. But a public static method also makes that easier to choose. We should be doing it