Problem/Motivation

API page: https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Render%21...

The documentation for the Render API overview contains the following example code demonstrating how to use #cache with a render array.

Here's an example of what a #cache property might contain:

  '#cache' => [
    'keys' => ['entity_view', 'node', $node->id()],
    'contexts' => ['languages'],
    'tags' => ['node:' . $node->id()],
    'max-age' => Cache::PERMANENT,
  ],

I believe that this line 'tags' => ['node:' . $node->id()], should be 'tags' => $node->getCacheTags() instead. This demonstrates the best practice of using ::getCacheTags() for the entity instead of trying to memorize all possible cache tags you would need to include here.

I was personally getting hung up on trying to figure out what valid values for 'tags' would be. And I believe the answer is, I should haven't to know that because I can just use ::getCacheTags() for anything that implements \Drupal\Core\Cache\CacheableDependencyInterface

Proposed resolution

Update the code in documentation to use $node->getCacheTags() instead of the current example.

Remaining tasks

Update the docs.

API changes

None

Data model changes

None

Comments

eojthebrave created an issue. See original summary.

hardikpandya’s picture

Status: Active » Needs review
StatusFileSize
new515 bytes

Added Patch.

eojthebrave’s picture

Status: Needs review » Needs work

Hey @hardik.p thanks for taking a look at this.

+++ b/core/lib/Drupal/Core/Render/theme.api.php
@@ -369,7 +369,7 @@
- *     'tags' => ['node:' . $node->id()],
+ *     'tags' => ['node:' . $node->getCacheTags()],

You can do 'tags' => $node->getCacheTags() here. The getCacheTags method should return an array with all the appropriate tags for the entity in question. Which in this case basically works out to return ['node:' . $node->id()];

The idea is to get people used to using getCacheTags to retrieve the list rather than trying to memorize, and then essentially hard-code a list of cache tags like the example currently does.

yogeshmpawar’s picture

Assigned: Unassigned » yogeshmpawar
yogeshmpawar’s picture

Assigned: yogeshmpawar » Unassigned
Status: Needs work » Needs review
StatusFileSize
new519 bytes
new509 bytes

Changes made as per comment #3.

pankajsachdeva’s picture

Assigned: Unassigned » pankajsachdeva
pankajsachdeva’s picture

Assigned: pankajsachdeva » Unassigned
vegantriathlete’s picture

Issue tags: +dcco2017

Version: 8.4.x-dev » 8.5.x-dev

Drupal 8.4.0-alpha1 will be released the week of July 31, 2017, which means new developments and disruptive changes should now be targeted against the 8.5.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

michaellenahan’s picture

Issue tags: -dcco2017 +Vienna2017
cyberschorsch’s picture

Assigned: Unassigned » cyberschorsch
cyberschorsch’s picture

Status: Needs review » Reviewed & tested by the community

@yogesh-pawar
Thank you for creating the patch! I reviewed your patch and now the documentation is more clear .

Marking RTBC

cyberschorsch’s picture

Assigned: cyberschorsch » Unassigned

  • Gábor Hojtsy committed 0d239c4 on 8.5.x
    Issue #2877480 by Yogesh Pawar, hardik.p, eojthebrave, Cyberschorsch:...

  • Gábor Hojtsy committed 93ace15 on 8.4.x
    Issue #2877480 by Yogesh Pawar, hardik.p, eojthebrave, Cyberschorsch:...
gábor hojtsy’s picture

Status: Reviewed & tested by the community » Fixed

Thanks all for making sure this is correct. I agree documenting the best practice is important.

gábor hojtsy’s picture

Version: 8.5.x-dev » 8.4.x-dev

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.