CINXE.COM

<!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" version="XHTML+RDFa 1.0" dir="ltr" xmlns:fb="http://ogp.me/ns/fb#" xmlns:og="http://ogp.me/ns#"> <head profile="http://www.w3.org/1999/xhtml/vocab"> <meta name="HandheldFriendly" content="true" /> <meta name="viewport" content="width=device-width" /> <meta name="MobileOptimized" content="width" />  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta name="description" content="Explore Drupal's Cache API features in-depth" /> <meta name="generator" content="Drupal 7 (https://www.drupal.org)" /> <link rel="image_src" href="https://www.drupal.org/sites/all/themes/bluecheese/images/og.jpg" /> <link rel="canonical" href="https://www.drupal.org/docs/8/api/cache-api/cache-api" /> <link rel="shortlink" href="https://www.drupal.org/node/1884796" /> <meta property="og:site_name" content="Drupal.org" /> <meta property="og:type" content="article" /> <meta property="og:url" content="https://www.drupal.org/docs/8/api/cache-api/cache-api" /> <meta property="og:title" content="Cache API" /> <meta property="og:description" content="Drupal's Cache API enables the storage of data that may require a significant amount of time to calculate. This cached data can have various lifespans; it can be kept indefinitely, set to expire after a specified duration, or configured to expire when related data changes. The following sections go into more detail on each feature. For a brief run-down, see also the Cache API page from the API documentation. Cacheability metadata Cacheability metadata, a fundamental concept within Drupal, ensures efficient caching." /> <meta property="og:updated_time" content="2023-10-27T08:42:46+00:00" /> <meta property="article:published_time" content="2013-01-10T02:13:48+00:00" /> <meta property="article:modified_time" content="2023-10-27T08:42:46+00:00" /> <title>Cache API | Cache API | Drupal Wiki guide on Drupal.org</title> <link type="text/css" rel="stylesheet" href="/files/advagg_css/css__vwdslBVX8xVWQ4hx4mWxIC59-lKGPldWkMIm435ispk__msT4O19F5udTbXsVQpyNk2EFYlbaoLwufqq_ZcdDcB0__YaNGWokqa69Wq8hHbkE322PVJ8I-GmpfBsT8LGsMpcI.css" media="all" /> <link type="text/css" rel="stylesheet" href="/files/advagg_css/css__Xi-PZpvKTY78w7l1WNsqwUA52MIupHJebCMiX34Ugt0__D_EUHDAfEQdxcLiSDY7hREUWkG1Ge56_h2z3Er8V188__YaNGWokqa69Wq8hHbkE322PVJ8I-GmpfBsT8LGsMpcI.css" media="all" /> <link type="text/css" rel="stylesheet" href="/files/advagg_css/css__WF0PRotZAhCcl0aJjY5W2LYj8UwiYuB2dZEFluOh3Tc__FviX13FUB-Ppa2XB29BUIJQZ1Wg-F5XiDE7XD5y7mjQ__YaNGWokqa69Wq8hHbkE322PVJ8I-GmpfBsT8LGsMpcI.css" media="all" /> <link type="text/css" rel="stylesheet" href="/files/advagg_css/css__Fx0_w1L9q3nwzXnALG7UfjLF34FGYgJTz636-GWbM6k__0jWLTEHP3h5U5RcXuZcFhf0DdvRdzP3_wzCVNT015Ls__YaNGWokqa69Wq8hHbkE322PVJ8I-GmpfBsT8LGsMpcI.css" media="all" /> <link type="text/css" rel="stylesheet" href="/files/advagg_css/css__pWCOPcaPe71p3QyGrAeqEd6dwL_n27prYOjnWQj4jVI__fR6RV6fh70jWL18FMzdVQpGUyYT8iL9Vw8wnms1DdQA__YaNGWokqa69Wq8hHbkE322PVJ8I-GmpfBsT8LGsMpcI.css" media="all" /> <link type="text/css" rel="stylesheet" href="/files/advagg_css/css__mlCLWKqAJJ-E-mMVCEmFp-7SE_XsgAxpf7HS-FcVqB0__7Tgy6u_PBeTp3b4s5UumhQPx9mJ_jhs1Z-WvSrqxAHk__YaNGWokqa69Wq8hHbkE322PVJ8I-GmpfBsT8LGsMpcI.css" media="all" /> <link type="text/css" rel="stylesheet" href="/files/advagg_css/css__QPp1snPjYt_xYr0c_V0IORcEElkIUBBBrvOB4ZE0Gnw__8jkPtXCYcQv4spuNwtiMBMbZXgCS-2GouDqwnCBDPRE__YaNGWokqa69Wq8hHbkE322PVJ8I-GmpfBsT8LGsMpcI.css" media="all" /> </head> <body class="html not-front not-logged-in no-sidebars page-node page-node- page-node-1884796 node-type-documentation drupalorg-site-main panels-layout og-context og-context-node og-context-node-2817909" > <div id="skip-link" tabindex="-1"> <a class="element-invisible element-focusable" href="#content">Skip to main content</a> <a class="element-invisible element-focusable skip-link-search" href="#search-block-form">Skip to search</a> </div> <div class="region region-page-top"> <noscript aria-hidden="true"><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-W36H8DW" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript> <div id="drupalorg-crosssite-gdpr">Can we use first and third party cookies and web beacons to <a href="https://www.drupal.org/terms">understand our audience, and to tailor promotions you see</a>?<br><button class="yes">Yes, please</button><button class="no">No, do not track me</button></div> </div> <div id="nav-header"> <div class="menu-nav"> <a class="nav-btn" id="nav-open-btn" href="#block-system-main-menu"><img src="/sites/all/themes/bluecheese/images/icon-w-menu.svg" alt="Main menu"></a> </div> <nav id="navigation-inner" class="container-12" role="navigation"> <div class="region region-navigation"> <div id="block-system-main-menu" class="block block-system block-menu"> <div class="block-inner"> <div class="content"> <div class="menu-block"><ul class="menu button"><li class="first leaf"><a href="/home" title="Drupal.org home page">Drupal.org home</a></li> <li class="expanded"><a href="/about" title="">Why Drupal?</a><div class="menu-block"><ul class="menu button"><li class="first leaf"><a href="/about" title="Learn about Drupal">About Drupal</a></li> <li class="leaf"><a href="/docs/getting-started/understanding-drupal/overview-of-drupal" title="">Platform overview</a></li> <li class="leaf"><a href="/about/11" title="">Drupal 11</a></li> <li class="leaf"><a href="/features/content-authoring" title="">Content Authoring</a></li> <li class="leaf"><a href="/features/content-as-a-service" title="">Content as a Service</a></li> <li class="leaf"><a href="/features/decoupled" title="">Decoupled</a></li> <li class="leaf"><a href="/features/accessibility" title="">Accessibility</a></li> <li class="leaf"><a href="/features/marketing-automation" title="">Marketing Automation</a></li> <li class="leaf"><a href="/features/multilingual" title="">Multilingual</a></li> <li class="leaf"><a href="/features/security" title="">Security</a></li> <li class="leaf"><a href="/features/personalization" title="">Personalization</a></li> <li class="leaf"><a href="/case-studies" title="View case studies to see how your peers have built success on Drupal">Case studies</a></li> <li class="leaf"><a href="https://www.drupal.org/association/beyond-the-build" title="">Video series</a></li> <li class="last leaf"><a href="/about/in-the-news" title="">News</a></li> </ul></div></li> <li class="expanded"><a href="/industries" title="Examples of solutions built on Drupal">Use cases</a><div class="menu-block"><ul class="menu button"><li class="first leaf"><a href="/developers" title="">For Developers</a></li> <li class="leaf"><a href="/marketers" title="Why marketers should choose Drupal for their ambitious digital experiences">For Marketers</a></li> <li class="leaf"><a href="/industries/ecommerce" title="">E-commerce</a></li> <li class="leaf"><a href="/industries/education" title="">Education</a></li> <li class="leaf"><a href="/industries/fintech" title="">FinTech</a></li> <li class="leaf"><a href="/industries/government" title="">Government</a></li> <li class="leaf"><a href="/industries/healthcare" title="">Healthcare</a></li> <li class="leaf"><a href="/industries/hightech" title="">High Tech</a></li> <li class="leaf"><a href="/industries/nonprofit" title="">Nonprofit</a></li> <li class="leaf"><a href="/industries/retail" title="">Retail</a></li> <li class="last leaf"><a href="/industries/travel" title="">Travel</a></li> </ul></div></li> <li class="expanded"><a href="/documentation" title="Resources to help you on your Drupal journey">Resources</a><div class="menu-block"><ul class="menu button"><li class="first leaf"><a href="/docs/getting-started/installing-drupal" title="">Installing Drupal</a></li> <li class="leaf"><a href="/documentation" title="Drupal Documentation">Documentation</a></li> <li class="leaf"><a href="/docs/user_guide/en/index.html" title="The Drupal 8 user guide will get you up to speed in no time">User guide</a></li> <li class="leaf"><a href="/docs/official_docs/local-development-guide" title="">Local Development Guide</a></li> <li class="leaf"><a href="/security" title="Find information about security releases for Drupal">Security</a></li> <li class="leaf"><a href="/news" title="News about the Drupal ecosystem">News</a></li> <li class="leaf"><a href="/planet" title="">Blog</a></li> <li class="last leaf"><a href="/about/drupal-7/d7eol/partners" title="Find help for your Drupal 7 migration">Migrate from D7</a></li> </ul></div></li> <li class="expanded"><a href="/drupal-services" title="Buy Drupal Products and Services">Services</a><div class="menu-block"><ul class="menu button"><li class="first leaf"><a href="/drupal-services" title="View the Drupal service provider marketplace">Find an Agency Partner</a></li> <li class="leaf"><a href="/hosting" title="Find trusted Drupal hosting providers">Find Integrations & Hosting</a></li> <li class="leaf"><a href="/training" title="Find expert Drupal training">Find Drupal Training</a></li> <li class="leaf"><a href="/association/become-a-drupal-certified-partner" title="">Become a Certified Partner</a></li> <li class="last leaf"><a href="/about/drupal-7/d7eol/migration-resource-center/enterprise" title="">Find a D7 migration partner</a></li> </ul></div></li> <li class="expanded"><a href="/community" title="Drupal Community">Community</a><div class="menu-block"><ul class="menu button"><li class="first leaf"><a href="/community/contributor-guide" title="">How to Contribute</a></li> <li class="leaf"><a href="/community" title="View the community portal and find all the ways you can contribute to Drupal">About the Community</a></li> <li class="leaf"><a href="/support" title="">Support</a></li> <li class="leaf"><a href="/project/governance" title="">Community Governance</a></li> <li class="last leaf"><a href="https://jobs.drupal.org" title="">Jobs/Careers</a></li> </ul></div></li> <li class="expanded"><a href="/community/events" title="Find Drupal Events around the world, from the official DrupalCons, to community Camps and Meet-Ups">Events</a><div class="menu-block"><ul class="menu button"><li class="first leaf"><a href="https://events.drupal.org/barcelona2024" title="">DrupalCon Barcelona 2024</a></li> <li class="leaf"><a href="https://events.drupal.org/singapore2024" title="">DrupalCon Singapore 2024</a></li> <li class="leaf"><a href="https://events.drupal.org/atlanta2025" title="">DrupalCon Atlanta 2025</a></li> <li class="last leaf"><a href="/community/events" title="">Community Events</a></li> </ul></div></li> <li class="expanded"><a href="/download" title="Download and Extend Drupal">Download</a><div class="menu-block"><ul class="menu button"><li class="first collapsed"><a href="/download" title="Build your solution on Drupal">Download</a></li> <li class="leaf"><a href="/project/modules" title="Find modules to extend Drupal to meet any need">Modules</a></li> <li class="leaf"><a href="/project/themes" title="Browse themes as a starting point for making your Drupal site your own">Themes</a></li> <li class="leaf"><a href="/project/distributions" title="Use a distribution to start with a version of Drupal customized to purpose">Distributions</a></li> <li class="leaf"><a href="/project/issues" title="Dive into the issues queues and contribute back to Drupal">Issue queues</a></li> <li class="last leaf"><a href="https://git.drupalcode.org/project/drupal" title="">Browse Repository</a></li> </ul></div></li> <li class="expanded"><a href="/association" title="About the Drupal Association - the non-profit that supports the Drupal project">Give</a><div class="menu-block"><ul class="menu button"><li class="first leaf"><a href="/association" title="Learn about the Drupal Association - the nonprofit that supports the Drupal project">Drupal Association</a></li> <li class="leaf"><a href="/association/organization-membership" title="Learn more about the organizations that support the Drupal Association and our mission">Become an Organization Member</a></li> <li class="leaf"><a href="/association/become-a-drupal-certified-partner" title="">Become a Certified Partner</a></li> <li class="leaf"><a href="/association/RippleMakers" title="">Become a Ripple Maker</a></li> <li class="leaf"><a href="/association/donate" title="">Make a Donation</a></li> <li class="leaf"><a href="/association/discover-drupal" title="">Discover Drupal</a></li> <li class="last leaf"><a href="https://www.drupal.org/swag?utm_source=drupalorg&utm_medium=banner&utm_campaign=drupal_swag_shop_2020_09_17" title="Purchase Drupal merchandise and be the coolest kid on the block">Drupal Swag Shop</a></li> </ul></div></li> <li class="last expanded"><a href="/try-drupal" title="Try Drupal">Demo</a><div class="menu-block"><ul class="menu button"><li class="first leaf"><a href="/try-drupal" title="Demo Drupal online with a Drupal platform partner">Demo online</a></li> <li class="last leaf"><a href="/download" title="">Download</a></li> </ul></div></li> </ul></div><a class="close-btn" href="#top">Return to content</a> </div> </div> </div> <div id="block-search-form" class="block block-search"> <div class="block-inner"> <div class="content"> <form action="/docs/8/api/cache-api/cache-api" method="post" id="search-block-form" accept-charset="UTF-8"><div><div class="container-inline"> <h2 class="element-invisible">Search form</h2> <div class="form-item form-type-textfield form-item-search-block-form"> <label class="element-invisible" for="edit-search-block-form--2">Search </label> <input placeholder="Search…" type="text" id="edit-search-block-form--2" name="search_block_form" value="" size="15" maxlength="128" class="form-text" /> </div> <div class="form-actions form-wrapper" id="edit-actions"><input alt="Search" type="image" id="edit-submit" name="submit" value="Search" src="/sites/all/themes/bluecheese/images/icon-w-search.svg" class="form-submit" /></div><input type="hidden" name="form_build_id" value="form-uBI_zsUMYGVDKnXJjvN_mekeowF2pCrc024YB9ycSwo" /> <input type="hidden" name="form_id" value="search_block_form" /> </div> </div></form> </div> </div> </div> <div id="block-system-user-menu" class="block block-system block-menu"> <div class="block-inner"> <div class="content"> <div class="menu-block"><ul class="menu"><li class="button default"><a href="#block-system-user-menu"><img src="https://www.drupal.org/sites/all/themes/bluecheese/images/icon-w-user.svg" alt="Log in, view profile, and more"></a><ul><li class="first leaf"><a href="/user/login?destination=node/1884796" title="">Log in</a></li> <li class="last leaf"><a href="/user/register?destination=node/1884796" title="">Create account</a></li> </ul></li></ul></div> </div> </div> </div> </div> </nav> </div> <div id="header" class="clearfix"> <div id="header-inner" class="container-12 clearfix"> <div id="header-left"> <div id="site-name"><a href="/documentation">Documentation</a></div> </div> <div id="header-right"> <div class="region region-header"> <div id="block-drupalorg-search-documentation" class="block block-drupalorg"> <div class="block-inner"> <div class="content"> <form class="container-inline" action="/docs/8/api/cache-api/cache-api" method="post" id="drupalorg-documentation-search-form" accept-charset="UTF-8"><div><input type="hidden" name="form_build_id" value="form-ShMGe8n-dmJQkk2TjLeYfOsPDLuV7JFQbYRlE7ukOkw" /> <input type="hidden" name="form_id" value="drupalorg_documentation_search_form" /> <div class="form-item form-type-textfield form-item-drupalorg-documentation-search-form"> <label class="element-invisible" for="edit-drupalorg-documentation-search-form--2">Search </label> <input placeholder="Search documentation…" type="text" id="edit-drupalorg-documentation-search-form--2" name="drupalorg_documentation_search_form" value="" size="15" maxlength="128" class="form-text" /> </div> <div class="form-actions form-wrapper" id="edit-actions--2"><input alt="Search" type="image" id="edit-submit--2" name="submit" value="Search" src="/sites/all/themes/bluecheese/images/icon-w-search.svg" class="form-submit" /></div></div></form> </div> </div> </div> </div> </div> </div> </div> <div id="banner" data-nosnippet> <div class="region region-banner"> <div id="block-drupalorg-announcements" class="block block-drupalorg"> <div class="block-inner"> <div class="content"> <div class="announcement"><img class="photo" src="https://www.drupal.org/files/styles/grid-2-2x-square/public/announcements/drupalcon-hexagon-icon-280X280px_2.png?itok=Oxf_7ZRC" width="280" height="280" alt="Announcement icon" title="Announcement icon" />Early Bird Registration for DrupalCon Atlanta is now open! By registering during our Early Bird Registration window, you’ll save $100. This window ends on 19 January 2025 and will go by quickly, so don’t wait!</div> <div class="cta"><a href="https://web.cvent.com/event/f3a4f9b8-0efa-44cf-a939-b80869a939af/summary" class="global-announce-banner dc-singapore-registration">Register now to save $100</a></div> </div> </div> </div> </div> </div> <div id="page" class="clearfix"> <div class="breadbox"><nav class="breadcrumb container-12"><span><a href="/docs/develop">Develop</a></span><span><a href="/docs/develop/drupal-apis">Drupal APIs</a></span><span><a href="/docs/drupal-apis/cache-api">Cache API</a></span></nav></div> <div id="main" role="main"> <div id="content" class="clearfix"> <div id="content-inner" class="clearfix"> <div class="region region-content"> <div id="block-system-main" class="block block-system"> <div class="block-inner"> <div class="content"> <div class="panelizer-view-mode node node-full node-documentation node-1884796"> <div class="panel-display hydra panel-layout clearfix " > <div class="container preface clearfix panel-panel"> <div class="container-inner preface-inner panel-panel-inner"> </div> </div> <div class="container content clearfix"> <div class="container-inner content-inner panel-panel-inner"> <div class="column-content-region top-right-content column panel-panel"> <div class="column-content-region-inner top-right-content-inner column-inner panel-panel-inner"> <div class="panel-pane pane-block pane-drupalorg-carbon-ad-sidebar" > <div class="pane-content"> <script async type="text/javascript" src="//cdn.carbonads.com/carbon.js?serve=CKYIEKJI&placement=drupalorg" id="_carbonads_js"></script><div class="ad-explanation description">Advertising sustains the DA. Ads are hidden for members. <a href="/association/individual-membership">Join today</a></div> </div> </div> <div class="panel-separator"></div><div class="panel-pane pane-block pane-table-of-contents-toc-w-3y7froeoqmgrpcmgnphqwt4pi3" id="on-this-page" > <h3 class="pane-title"> On this page </h3> <div class="pane-content"> <div class="item-list"><ul class="anchor-list"><li class="anchor-list__item h2-tag first"><a href="/docs/8/api/cache-api/cache-api#s-cacheability-metadata" class="toc-link toc-link-invalid-id active">Cacheability metadata</a></li> <li class="anchor-list__item h2-tag last"><a href="/docs/8/api/cache-api/cache-api#s-practical-how-youll-typically-use-the-cache-api" class="toc-link toc-link-invalid-id active">Practical: how you'll typically use the Cache API</a></li> </ul></div> </div> </div> <div class="panel-separator"></div><div class="panel-pane pane-block pane-og-menu-og-single-menu-block" id="cache-api" > <h2 class="pane-title"> <a href="/docs/drupal-apis/cache-api">Cache API</a> </h2> <div class="pane-content"> <ul class="menu"><li class="first leaf active-trail"><a href="/docs/8/api/cache-api/cache-api" class="active-trail active">Cache API</a></li> <li class="leaf"><a href="/docs/drupal-apis/cache-api/cache-tags">Cache tags</a></li> <li class="leaf"><a href="/docs/drupal-apis/cache-api/cache-contexts">Cache contexts</a></li> <li class="leaf"><a href="/docs/drupal-apis/cache-api/cache-max-age">Cache max-age</a></li> <li class="leaf"><a href="/docs/drupal-apis/cache-api/cache-tags-varnish">Cache tags + Varnish</a></li> <li class="leaf"><a href="/docs/8/api/cache-api/cacheabledependencyinterface-friends">CacheableDependencyInterface & friends</a></li> <li class="leaf"><a href="/docs/8/api/cache-api/cacheableresponseinterface">CacheableResponseInterface</a></li> <li class="last leaf"><a href="/docs/8/api/cache-api/access-checkers-cacheability">Access checkers + cacheability</a></li> </ul> </div> </div> <div class="panel-separator"></div><div class="panel-pane pane-node-links" > <div class="pane-content"> </div> </div> </div> </div> <div class="column-content-region left-content column panel-panel "> <div class="column-content-region-inner left-content-inner column-inner panel-panel-inner"> <div class="panel-pane pane-node-title" > <div class="pane-content"> <h1>Cache API</h1> </div> </div> <div class="panel-separator"></div><div class="panel-pane pane-node-updated" id="last-updated-on" > <span class="pane-title"> Last <a href="/node/1884796/discuss">updated</a> on </span> <div class="pane-content"> 27 October 2023 </div> </div> <div class="panel-separator"></div><div class="panel-pane pane-entity-field pane-node-field-documentation-status" > <div class="pane-content"> <div class="field field-name-field-documentation-status field-type-list-text field-label-hidden"><div class="field-items"><div class="field-item even"><p class="deprecated">This documentation <strong>needs work</strong>. See "Help improve this page" in the sidebar.</p></div></div></div> </div> </div> <div class="panel-separator"></div><div class="panel-pane pane-entity-field pane-node-body" > <div class="pane-content"> <div class="field field-name-body field-type-text-with-summary field-label-hidden"><div class="field-items"><div class="field-item even"><p>Drupal's Cache API enables the storage of data that may require a significant amount of time to calculate. This cached data can have various lifespans; it can be kept indefinitely, set to expire after a specified duration, or configured to expire when related data changes. The following sections go into more detail on each feature.</p> <p>For a brief run-down, see also the <a href="https://api.drupal.org/api/drupal/core%21core.api.php/group/cache/8" rel="nofollow">Cache API</a> page from the API documentation.</p> <h2 id="s-cacheability-metadata"><a class="toc-anchor" title="Permalink to this headline" href="#s-cacheability-metadata"></a>Cacheability metadata</h2> <p>Cacheability metadata, a fundamental concept within Drupal, ensures efficient caching. It is associated with all elements that can be rendered or influence the rendering process, encompassing a wide range of items from <a href="https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Access%21AccessResult.php/class/AccessResult/8" rel="nofollow">access results</a> to <a href="https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Entity%21EntityInterface.php/interface/EntityInterface/8" rel="nofollow">entities</a> and <a href="https://www.drupal.org/node/2480761" rel="nofollow">URLs</a>. This metadata includes the information and rules that guide the caching and management of cached data, determining when and how content can be cached and ensuring effective cache invalidation. As a result, it leads to improved website performance and efficiency.</p> <p>Cacheability metadata comprises three key properties:</p> <dl> <dt><a href="/developing/api/8/cache/tags" rel="nofollow">Cache Tags</a></dt> <dd> <p>These represent dependencies on data managed by Drupal, such as entities and configuration. When any of these dependencies change, Drupal knows to invalidate or update the cached content, ensuring that your site's data remains up-to-date.</p> </dd> <dt><a href="/developing/api/8/cache/contexts" rel="nofollow">Cache Contexts</a></dt> <dd>These handle variations based on the request context. For instance, they account for variations in content that might be influenced by factors like the user's role or language. Cache contexts enable Drupal to serve personalized content efficiently.</dd> <dt><a href="/developing/api/8/cache/max-age" rel="nofollow">Cache Max-Age</a></dt> <dd>This property is responsible for time-sensitive caching. It defines the duration for which content remains valid in the cache before it needs to be re-fetched. Cache max-age ensures that content remains relevant and reduces the load on your server by minimizing unnecessary recalculations.</dd> </dl> <h2 id="s-practical-how-youll-typically-use-the-cache-api"><a class="toc-anchor" title="Permalink to this headline" href="#s-practical-how-youll-typically-use-the-cache-api"></a>Practical: how you'll typically use the Cache API</h2> <p>Typically, your code will end up rendering things (blocks, entities, and so on) and your controllers will return render arrays or responses. So, usually, you won't be interacting with the Cache API directly. Instead you'll be using:</p> <dl> <dt>Render caching (aka fragment caching)</dt> <dd>The Render API uses cacheability metadata embedded in render arrays to perform caching (aka render caching). Therefore, the Cache API should not be used to interact with the render cache (neither to retrieve cache items nor to create new ones).</dd> <dd>See <a href="/developing/api/8/render/arrays/cacheability" rel="nofollow">Cacheability of render arrays</a>.</dd> <dt>Response caching</dt> <dd>The cacheability metadata used by the Render API (see the previous section) bubbles all the way up to Response objects (usually a <code class="language-php">HtmlResponse</code>) that implement <code class="language-php">CacheableResponseInterface</code>.</dd> <dd>The cacheability metadata on these Response objects is what allows Drupal 8 to ship with <a href="https://www.drupal.org/documentation/modules/internal_page_cache" rel="nofollow">Page Cache</a> and <a href="https://www.drupal.org/documentation/modules/dynamic_page_cache" rel="nofollow">Dynamic Page Cache</a> enabled by default, because it allows them to work transparently: they are always up-to-date and always vary appropriately.</dd> <dd>See <a href="/developing/api/8/cache/cacheable-response-interface" rel="nofollow"><code class="language-php">CacheableResponseInterface</code></a>.</dd> </dl></div></div></div> </div> </div> </div> </div> <div class="column-content-region bottom-right-content column panel-panel"> <div class="column-content-region-inner bottom-right-content-inner column-inner panel-panel-inner"> <div class="panel-pane pane-views-panes pane-documentation-help-improve-pane" id="help-improve-this-page" > <h2 class="pane-title"> Help improve this page </h2> <div class="pane-content"> <div class="view view-documentation-help view-id-documentation_help view-display-id-improve_pane view-dom-id-70177f0dc121d037de8d2c82c86f9800"> <div class="view-content"> <div class="views-row views-row-1 views-row-odd views-row-first views-row-last"> <span class="views-field views-field-field-documentation-status"> <strong class="views-label views-label-field-documentation-status">Page status: </strong> <span class="field-content">Needs work</span> </span> <div class="views-field views-field-nothing"> <span class="field-content"><br /><strong>You can:</strong><br /> <ul> <li>Log in, click <a href="/node/1884796/edit">Edit</a>, and edit this page</li> <li>Log in, click <a href="/node/1884796/discuss">Discuss</a>, update the Page status value, and suggest an improvement</li> <li>Log in and <a href="/node/add/project-issue/documentation?title=Suggestion%20for%3A%20%281884796%29%20Cache%20API">create a Documentation issue</a> with your suggestion</li> </ul></span> </div> </div> </div> </div> </div> </div> </div> </div> </div> </div> <div class="container footer clearfix panel-panel"> <div class="container-inner footer-inner panel-panel-inner"> </div> </div> </div> </div> </div> </div> </div> </div> </div> </div>  </div>  </div>  <div id="footer" role="contentinfo"> <div class="region region-footer"> <div id="block-drupalorg-documentation-license" class="block block-drupalorg"> <div class="block-inner"> <div class="content"> Drupal’s online documentation is © 2000-2024 by the individual contributors and can be used in accordance with the <a href="/terms">Creative Commons License, Attribution-ShareAlike 2.0</a>. PHP code is distributed under the <a href="https://www.gnu.org/licenses/old-licenses/gpl-2.0.html">GNU General Public License</a>. </div> </div> </div> <div id="block-drupalorg-crosssite-infra-partner" class="block block-drupalorg-crosssite"> <div class="block-inner"> <div class="content"> <a href="https://tag1consulting.com" >Infrastructure management for Drupal.org provided by <img src="/files/cta/graphic/tag1_wht.svg" alt="Tag1 logo" ></a> <br /> <span style="font-size: .65em;"><a href="https://d7es.tag1.com/">Need a Drupal 7 extended support partner? Consider Tag1.</a></span> </div> </div> </div> <div id="block-drupalorg-crosssite-drupalorg-footer" class="block block-drupalorg-crosssite"> <div class="block-inner"> <div class="content"> <h4 class="element-invisible">News items</h4><ul class="drupal-news"><li class="0 first"><a href="https://www.drupal.org/news">News</a></li> <li class="1"><a href="https://www.drupal.org/planet" title="News from Drupal community members">Planet Drupal</a></li> <li class="2"><a href="https://www.drupal.org/about/media-kit/social-media" title="Drupal on social media">Social media</a></li> <li class="3"><a href="https://www.drupal.org/subscribe">Sign up for Drupal news</a></li> <li class="4"><a href="https://www.drupal.org/security" title="Announcements from the Drupal Security Team">Security advisories</a></li> <li class="5 last"><a href="https://jobs.drupal.org/" title="Drupal Jobs">Jobs</a></li> </ul><h4 class="element-invisible">Our community</h4><ul class="community"><li class="0 first"><a href="https://www.drupal.org/community">Community</a></li> <li class="1"><span><a href="https://www.drupal.org/drupal-services" title="People and organizations offering Drupal services">Services</a>, <a href="https://www.drupal.org/training" title="People and organizations offering Drupal training">Training</a> & <a href="https://www.drupal.org/hosting" title="Organizations offering Drupal hosting">Hosting</a></span></li> <li class="2"><a href="https://www.drupal.org/community/contributor-guide">Contributor guide</a></li> <li class="3"><a href="https://groups.drupal.org/groups" title="groups.drupal.org">Groups & meetups</a></li> <li class="4"><a href="https://events.drupal.org" title="Upcoming and past DrupalCons">DrupalCon</a></li> <li class="5 last"><a href="https://www.drupal.org/dcoc" title="Drupal code of conduct">Code of conduct</a></li> </ul><h4 class="element-invisible">Documentation</h4><ul class="get-started"><li class="0 first"><a href="https://www.drupal.org/documentation" title="Documentation for working with Drupal">Documentation</a></li> <li class="1"><a href="https://www.drupal.org/docs">Drupal Guide</a></li> <li class="2"><a href="https://www.drupal.org/docs/user_guide/en/index.html">Drupal User Guide</a></li> <li class="3"><a href="https://www.drupal.org/documentation/develop">Developer docs</a></li> <li class="4 last"><a href="https://api.drupal.org/" title="Drupal API reference">API.Drupal.org</a></li> </ul><h4 class="element-invisible">Drupal code base</h4><ul class="download-extend"><li class="0 first"><a href="https://www.drupal.org/download">Download & Extend</a></li> <li class="1"><a href="https://www.drupal.org/project/drupal" title="Download the latest version of the Drupal software">Drupal core</a></li> <li class="2"><a href="https://www.drupal.org/project/project_module" title="Download add-on features and functionality">Modules</a></li> <li class="3"><a href="https://www.drupal.org/project/project_theme" title="Download pre-designed styles for Drupal">Themes</a></li> <li class="4 last"><a href="https://www.drupal.org/project/project_distribution" title="Download a pre-packaged Drupal site">Distributions</a></li> </ul><h4 class="element-invisible">Governance of community</h4><ul class="about"><li class="0 first"><a href="https://www.drupal.org/about">About</a></li> <li class="1"><a href="https://www.drupal.org/about/features/accessibility" title="Our committment to accessibility">Web accessibility</a></li> <li class="2"><a href="https://www.drupal.org/association" title="About the Drupal Association">Drupal Association</a></li> <li class="3"><a href="https://www.drupal.org/drupalorg" title="About Drupal.org">About Drupal.org</a></li> <li class="4"><a href="https://www.drupal.org/terms" title="Drupal.org terms of service">Terms of service</a></li> <li class="5 last"><a href="https://www.drupal.org/privacy" title="Drupal.org privacy policy">Privacy policy</a></li> </ul> </div> </div> </div> <div id="block-block-77" class="block block-block"> <div class="block-inner"> <div class="content"> <p>Drupal is a <a href="/about/trademark">registered trademark</a> of <a href="https://dri.es">Dries Buytaert</a>.</p> </div> </div> </div> </div> </div> <div class="region region-page-bottom"> <script type="text/javascript"> (function(){ window._pxAppId = 'PXVnPBBfwe'; window._pxParam2 = ''; window._pxParam3 = '0'; var p = document.getElementsByTagName('script')[0], s = document.createElement('script'); s.async = 1; s.src = '/VnPBBfwe/init.js'; p.parentNode.insertBefore(s,p); }()); </script> <noscript> <div style="position:fixed; top:0; left:0; display:none" width="1" height="1"> <img src="/VnPBBfwe/xhr/api/v1/collector/noScript.gif?appId=PXVnPBBfwe"> </div> </noscript> </div> <script type="text/javascript" src="/files/advagg_js/js__B0FBwiP97ZnD38IFraZus4upS4KVkMXI3ou0fJ2ZXGA__pPDESRJz9GHsxqQIwQ_V8xnFYEH5jipG2eicsfrdWCs__YaNGWokqa69Wq8hHbkE322PVJ8I-GmpfBsT8LGsMpcI.js" defer="defer"></script>    <script type="text/javascript" src="/files/advagg_js/js__79M6UrZjAw3oNGnUjsWip12JsvnUZmJGA3h9LI0kuzE__J0sbXAJNry2-C_ZL2xd0RdVuzwTLvwN-UisIv5RNCvU__YaNGWokqa69Wq8hHbkE322PVJ8I-GmpfBsT8LGsMpcI.js" defer="defer" onload="if(jQuery.isFunction(jQuery.holdReady)){jQuery.holdReady(true);}"></script>  <script type="text/javascript" src="/files/advagg_js/js__pqoYaVR8NVhof-vNXe50j2TKhFv__IihVag_h4G6kus__B4mbn4wICLQjWm1m3-z1kw8F1FtP0cDAHKp00Xy_-88__YaNGWokqa69Wq8hHbkE322PVJ8I-GmpfBsT8LGsMpcI.js" defer="defer"></script> <script type="text/javascript" src="/files/advagg_js/js__H5AFmq1RrXKsrazzPq_xPQPy4K0wUKqecPjczzRiTgQ__wor4r9P8YTtQ7p6fbywTetZ47Z_orumIfrrhgxrpLus__YaNGWokqa69Wq8hHbkE322PVJ8I-GmpfBsT8LGsMpcI.js" defer="defer" onload=" function advagg_mod_1() { // Count how many times this function is called. advagg_mod_1.count = ++advagg_mod_1.count || 1; try { if (advagg_mod_1.count <= 40) { init_drupal_core_settings(); // Set this to 100 so that this function only runs once. advagg_mod_1.count = 100; } } catch(e) { if (advagg_mod_1.count >= 40) { // Throw the exception if this still fails after running 40 times. throw e; } else { // Try again in 1 ms. window.setTimeout(advagg_mod_1, 1); } } } function advagg_mod_1_check() { if (window.init_drupal_core_settings && window.jQuery && window.Drupal) { advagg_mod_1(); } else { window.setTimeout(advagg_mod_1_check, 1); } } advagg_mod_1_check();"></script> <script type="text/javascript" src="/files/advagg_js/js__Oc0wwB7MVRfxtYw6EQM7d9sXj9PAQePoWSzQJ0uTk6c__iXqOGoaPhZHCPEspUr5BC8BwOx5P8B11xv7VOhoUii8__YaNGWokqa69Wq8hHbkE322PVJ8I-GmpfBsT8LGsMpcI.js" defer="defer"></script> <script type="text/javascript" src="/files/advagg_js/js__FabcJ6qluktliDejymsuV-FqaN_HyMKGe93c2rO9Ky0__el1ZLGkKneOoCS6OWa01WHuIEsTsXZ46MRLCF390Fbw__YaNGWokqa69Wq8hHbkE322PVJ8I-GmpfBsT8LGsMpcI.js" defer="defer"></script> <script type="text/javascript" src="/files/advagg_js/js__YT6D1B_BKxvm6JCH_t9sZNI5L6yITa_DlU5QcSlOkAU__OXobH7d1IP1o3WABlniIrU_-pcJacVSIPUv9bpD-6pQ__YaNGWokqa69Wq8hHbkE322PVJ8I-GmpfBsT8LGsMpcI.js" defer="defer"></script> <script type="text/javascript" src="/files/advagg_js/js__xNXZEl6CREO_N4cX50nXAG3o3PPW1f2SzBBHY8rEKV8__vTuPvw9kFyhvW1mq6Cl_PG3exxZo1gi4hMxmKe9QZUI__YaNGWokqa69Wq8hHbkE322PVJ8I-GmpfBsT8LGsMpcI.js" defer="defer"></script> <script type="text/javascript" src="/files/advagg_js/js__pLKQd4r7OrHglE7Qkqw53K2UXCqQdhqQ9v0cz7hMCQY__OErfYuQdGbFHcCoLoUW_ESSvaumApNojzjJit8-2xcw__YaNGWokqa69Wq8hHbkE322PVJ8I-GmpfBsT8LGsMpcI.js" defer="defer"></script> <script type="text/javascript" src="/files/advagg_js/js__hHUWFbMAa11eJtx5V0ym9o0YBsB1udk34qUT5wr1ihI__ntICfIdx3SsBpfvYB8AF0VuFk7gZjQgBaS1C9CyMj6o__YaNGWokqa69Wq8hHbkE322PVJ8I-GmpfBsT8LGsMpcI.js" defer="defer"></script> <script type="text/javascript"> <![CDATA[//><!]]> </script> <script type="text/javascript" src="/files/advagg_js/js__2k0CJ3KAQNFTFab3y6ZvNtxs3HLons0Brq7VwvPSkKo__RYlZCliQTuN7U7I5I1Xhn1dAop17g2hAft1wVGgKHGA__YaNGWokqa69Wq8hHbkE322PVJ8I-GmpfBsT8LGsMpcI.js" defer="defer"></script> <script type="text/javascript" src="/files/advagg_js/js__vj0LjvNwl-3K1P9LGT4BGuXCZcAovYsVlVmoJN3TMRg__KW8SiGceRY3sjIKVrffDjf2MK4A5Vp3EDDxVO-4pegI__YaNGWokqa69Wq8hHbkE322PVJ8I-GmpfBsT8LGsMpcI.js" defer="defer"></script> </body> </html>