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

roderik created an issue. See original summary.

roderik’s picture

Issue summary: View changes

Version: 8.7.x-dev » 8.8.x-dev

Drupal 8.7.0-alpha1 will be released the week of March 11, 2019, which means new developments and disruptive changes should now be targeted against the 8.8.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

roderik’s picture

Issue summary: View changes
roderik’s picture

Issue summary: View changes
roderik’s picture

I 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

)

roderik’s picture

Issue summary: View changes
roderik’s picture

Issue summary: View changes
joachim’s picture

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

roderik’s picture

Sounds 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

  • not in CacheableResponse because that's too generic
  • not in CacheableRedirectResponse because that's hardly used anywhere (and I'm not super sure why it exists)
  • but in the abstract CacheableSecuredRedirectResponse (which does not extend either of the above, but is extended by TrustedRedirectResponse and LocalRedirectResponse).

Version: 8.8.x-dev » 8.9.x-dev

Drupal 8.8.0-alpha1 will be released the week of October 14th, 2019, which means new developments and disruptive changes should now be targeted against the 8.9.x-dev branch. (Any changes to 8.9.x will also be committed to 9.0.x in preparation for Drupal 9’s release, but some changes like significant feature additions will be deferred to 9.1.x.). For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 8.9.x-dev » 9.1.x-dev

Drupal 8.9.0-beta1 was released on March 20, 2020. 8.9.x is the final, long-term support (LTS) minor release of Drupal 8, which means new developments and disruptive changes should now be targeted against the 9.1.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 9.1.x-dev » 9.2.x-dev

Drupal 9.1.0-alpha1 will be released the week of October 19, 2020, which means new developments and disruptive changes should now be targeted for the 9.2.x-dev branch. For more information see the Drupal 9 minor version schedule and the Allowed changes during the Drupal 9 release cycle.

Version: 9.2.x-dev » 9.3.x-dev

Drupal 9.2.0-alpha1 will be released the week of May 3, 2021, which means new developments and disruptive changes should now be targeted for the 9.3.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.3.x-dev » 9.4.x-dev

Drupal 9.3.0-rc1 was released on November 26, 2021, which means new developments and disruptive changes should now be targeted for the 9.4.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.4.x-dev » 9.5.x-dev

Drupal 9.4.0-alpha1 was released on May 6, 2022, which means new developments and disruptive changes should now be targeted for the 9.5.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.5.x-dev » 10.1.x-dev

Drupal 9.5.0-beta2 and Drupal 10.0.0-beta2 were released on September 29, 2022, which means new developments and disruptive changes should now be targeted for the 10.1.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 10.1.x-dev » 11.x-dev

Drupal core is moving towards using a “main” branch. As an interim step, a new 11.x branch has been opened, as Drupal.org infrastructure cannot currently fully support a branch named main. New developments and disruptive changes should now be targeted for the 11.x branch, which currently accepts only minor-version allowed changes. For more information, see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 11.x-dev » main

Drupal core is now using the main branch as the primary development branch. New developments and disruptive changes should now be targeted to the main branch.

Read more in the announcement.