4 * This file is part of the Symfony package.
6 * (c) Fabien Potencier <fabien@symfony.com>
8 * This code is partially based on the Rack-Cache library by Ryan Tomayko,
9 * which is released under the MIT license.
10 * (based on commit 02d2b48d75bcb63cf1c0c7149c077ad256542801)
12 * For the full copyright and license information, please view the LICENSE
13 * file that was distributed with this source code.
16 namespace Symfony\Component\HttpKernel\HttpCache;
18 use Symfony\Component\HttpFoundation\Request;
19 use Symfony\Component\HttpFoundation\Response;
20 use Symfony\Component\HttpKernel\HttpKernelInterface;
21 use Symfony\Component\HttpKernel\TerminableInterface;
24 * Cache provides HTTP caching.
26 * @author Fabien Potencier <fabien@symfony.com>
28 class HttpCache implements HttpKernelInterface, TerminableInterface
34 private $surrogateCacheStrategy;
35 private $options = array();
36 private $traces = array();
41 * The available options are:
43 * * debug: If true, the traces are added as a HTTP header to ease debugging
45 * * default_ttl The number of seconds that a cache entry should be considered
46 * fresh when no explicit freshness information is provided in
47 * a response. Explicit Cache-Control or Expires headers
48 * override this value. (default: 0)
50 * * private_headers Set of request headers that trigger "private" cache-control behavior
51 * on responses that don't explicitly state whether the response is
52 * public or private via a Cache-Control directive. (default: Authorization and Cookie)
54 * * allow_reload Specifies whether the client can force a cache reload by including a
55 * Cache-Control "no-cache" directive in the request. Set it to ``true``
56 * for compliance with RFC 2616. (default: false)
58 * * allow_revalidate Specifies whether the client can force a cache revalidate by including
59 * a Cache-Control "max-age=0" directive in the request. Set it to ``true``
60 * for compliance with RFC 2616. (default: false)
62 * * stale_while_revalidate Specifies the default number of seconds (the granularity is the second as the
63 * Response TTL precision is a second) during which the cache can immediately return
64 * a stale response while it revalidates it in the background (default: 2).
65 * This setting is overridden by the stale-while-revalidate HTTP Cache-Control
66 * extension (see RFC 5861).
68 * * stale_if_error Specifies the default number of seconds (the granularity is the second) during which
69 * the cache can serve a stale response when an error is encountered (default: 60).
70 * This setting is overridden by the stale-if-error HTTP Cache-Control extension
73 public function __construct(HttpKernelInterface $kernel, StoreInterface $store, SurrogateInterface $surrogate = null, array $options = array())
75 $this->store = $store;
76 $this->kernel = $kernel;
77 $this->surrogate = $surrogate;
79 // needed in case there is a fatal error because the backend is too slow to respond
80 register_shutdown_function(array($this->store, 'cleanup'));
82 $this->options = array_merge(array(
85 'private_headers' => array('Authorization', 'Cookie'),
86 'allow_reload' => false,
87 'allow_revalidate' => false,
88 'stale_while_revalidate' => 2,
89 'stale_if_error' => 60,
94 * Gets the current store.
96 * @return StoreInterface $store A StoreInterface instance
98 public function getStore()
104 * Returns an array of events that took place during processing of the last request.
106 * @return array An array of events
108 public function getTraces()
110 return $this->traces;
114 * Returns a log message for the events of the last request processing.
116 * @return string A log message
118 public function getLog()
121 foreach ($this->traces as $request => $traces) {
122 $log[] = sprintf('%s: %s', $request, implode(', ', $traces));
125 return implode('; ', $log);
129 * Gets the Request instance associated with the master request.
131 * @return Request A Request instance
133 public function getRequest()
135 return $this->request;
139 * Gets the Kernel instance.
141 * @return HttpKernelInterface An HttpKernelInterface instance
143 public function getKernel()
145 return $this->kernel;
149 * Gets the Surrogate instance.
151 * @return SurrogateInterface A Surrogate instance
153 * @throws \LogicException
155 public function getSurrogate()
157 return $this->surrogate;
163 public function handle(Request $request, $type = HttpKernelInterface::MASTER_REQUEST, $catch = true)
165 // FIXME: catch exceptions and implement a 500 error page here? -> in Varnish, there is a built-in error page mechanism
166 if (HttpKernelInterface::MASTER_REQUEST === $type) {
167 $this->traces = array();
168 // Keep a clone of the original request for surrogates so they can access it.
169 // We must clone here to get a separate instance because the application will modify the request during
170 // the application flow (we know it always does because we do ourselves by setting REMOTE_ADDR to 127.0.0.1
171 // and adding the X-Forwarded-For header, see HttpCache::forward()).
172 $this->request = clone $request;
173 if (null !== $this->surrogate) {
174 $this->surrogateCacheStrategy = $this->surrogate->createCacheStrategy();
178 $this->traces[$this->getTraceKey($request)] = array();
180 if (!$request->isMethodSafe(false)) {
181 $response = $this->invalidate($request, $catch);
182 } elseif ($request->headers->has('expect') || !$request->isMethodCacheable()) {
183 $response = $this->pass($request, $catch);
184 } elseif ($this->options['allow_reload'] && $request->isNoCache()) {
186 If allow_reload is configured and the client requests "Cache-Control: no-cache",
187 reload the cache by fetching a fresh response and caching it (if possible).
189 $this->record($request, 'reload');
190 $response = $this->fetch($request, $catch);
192 $response = $this->lookup($request, $catch);
195 $this->restoreResponseBody($request, $response);
197 if (HttpKernelInterface::MASTER_REQUEST === $type && $this->options['debug']) {
198 $response->headers->set('X-Symfony-Cache', $this->getLog());
201 if (null !== $this->surrogate) {
202 if (HttpKernelInterface::MASTER_REQUEST === $type) {
203 $this->surrogateCacheStrategy->update($response);
205 $this->surrogateCacheStrategy->add($response);
209 $response->prepare($request);
211 $response->isNotModified($request);
219 public function terminate(Request $request, Response $response)
221 if ($this->getKernel() instanceof TerminableInterface) {
222 $this->getKernel()->terminate($request, $response);
227 * Forwards the Request to the backend without storing the Response in the cache.
229 * @param Request $request A Request instance
230 * @param bool $catch Whether to process exceptions
232 * @return Response A Response instance
234 protected function pass(Request $request, $catch = false)
236 $this->record($request, 'pass');
238 return $this->forward($request, $catch);
242 * Invalidates non-safe methods (like POST, PUT, and DELETE).
244 * @param Request $request A Request instance
245 * @param bool $catch Whether to process exceptions
247 * @return Response A Response instance
253 protected function invalidate(Request $request, $catch = false)
255 $response = $this->pass($request, $catch);
257 // invalidate only when the response is successful
258 if ($response->isSuccessful() || $response->isRedirect()) {
260 $this->store->invalidate($request);
262 // As per the RFC, invalidate Location and Content-Location URLs if present
263 foreach (array('Location', 'Content-Location') as $header) {
264 if ($uri = $response->headers->get($header)) {
265 $subRequest = Request::create($uri, 'get', array(), array(), array(), $request->server->all());
267 $this->store->invalidate($subRequest);
271 $this->record($request, 'invalidate');
272 } catch (\Exception $e) {
273 $this->record($request, 'invalidate-failed');
275 if ($this->options['debug']) {
285 * Lookups a Response from the cache for the given Request.
287 * When a matching cache entry is found and is fresh, it uses it as the
288 * response without forwarding any request to the backend. When a matching
289 * cache entry is found but is stale, it attempts to "validate" the entry with
290 * the backend using conditional GET. When no matching cache entry is found,
291 * it triggers "miss" processing.
293 * @param Request $request A Request instance
294 * @param bool $catch Whether to process exceptions
296 * @return Response A Response instance
300 protected function lookup(Request $request, $catch = false)
303 $entry = $this->store->lookup($request);
304 } catch (\Exception $e) {
305 $this->record($request, 'lookup-failed');
307 if ($this->options['debug']) {
311 return $this->pass($request, $catch);
314 if (null === $entry) {
315 $this->record($request, 'miss');
317 return $this->fetch($request, $catch);
320 if (!$this->isFreshEnough($request, $entry)) {
321 $this->record($request, 'stale');
323 return $this->validate($request, $entry, $catch);
326 $this->record($request, 'fresh');
328 $entry->headers->set('Age', $entry->getAge());
334 * Validates that a cache entry is fresh.
336 * The original request is used as a template for a conditional
337 * GET request with the backend.
339 * @param Request $request A Request instance
340 * @param Response $entry A Response instance to validate
341 * @param bool $catch Whether to process exceptions
343 * @return Response A Response instance
345 protected function validate(Request $request, Response $entry, $catch = false)
347 $subRequest = clone $request;
349 // send no head requests because we want content
350 if ('HEAD' === $request->getMethod()) {
351 $subRequest->setMethod('GET');
354 // add our cached last-modified validator
355 $subRequest->headers->set('if_modified_since', $entry->headers->get('Last-Modified'));
357 // Add our cached etag validator to the environment.
358 // We keep the etags from the client to handle the case when the client
359 // has a different private valid entry which is not cached here.
360 $cachedEtags = $entry->getEtag() ? array($entry->getEtag()) : array();
361 $requestEtags = $request->getETags();
362 if ($etags = array_unique(array_merge($cachedEtags, $requestEtags))) {
363 $subRequest->headers->set('if_none_match', implode(', ', $etags));
366 $response = $this->forward($subRequest, $catch, $entry);
368 if (304 == $response->getStatusCode()) {
369 $this->record($request, 'valid');
371 // return the response and not the cache entry if the response is valid but not cached
372 $etag = $response->getEtag();
373 if ($etag && \in_array($etag, $requestEtags) && !\in_array($etag, $cachedEtags)) {
377 $entry = clone $entry;
378 $entry->headers->remove('Date');
380 foreach (array('Date', 'Expires', 'Cache-Control', 'ETag', 'Last-Modified') as $name) {
381 if ($response->headers->has($name)) {
382 $entry->headers->set($name, $response->headers->get($name));
388 $this->record($request, 'invalid');
391 if ($response->isCacheable()) {
392 $this->store($request, $response);
399 * Unconditionally fetches a fresh response from the backend and
400 * stores it in the cache if is cacheable.
402 * @param Request $request A Request instance
403 * @param bool $catch Whether to process exceptions
405 * @return Response A Response instance
407 protected function fetch(Request $request, $catch = false)
409 $subRequest = clone $request;
411 // send no head requests because we want content
412 if ('HEAD' === $request->getMethod()) {
413 $subRequest->setMethod('GET');
416 // avoid that the backend sends no content
417 $subRequest->headers->remove('if_modified_since');
418 $subRequest->headers->remove('if_none_match');
420 $response = $this->forward($subRequest, $catch);
422 if ($response->isCacheable()) {
423 $this->store($request, $response);
430 * Forwards the Request to the backend and returns the Response.
432 * All backend requests (cache passes, fetches, cache validations)
433 * run through this method.
435 * @param Request $request A Request instance
436 * @param bool $catch Whether to catch exceptions or not
437 * @param Response $entry A Response instance (the stale entry if present, null otherwise)
439 * @return Response A Response instance
441 protected function forward(Request $request, $catch = false, Response $entry = null)
443 if ($this->surrogate) {
444 $this->surrogate->addSurrogateCapability($request);
447 // always a "master" request (as the real master request can be in cache)
448 $response = SubRequestHandler::handle($this->kernel, $request, HttpKernelInterface::MASTER_REQUEST, $catch);
450 // we don't implement the stale-if-error on Requests, which is nonetheless part of the RFC
451 if (null !== $entry && \in_array($response->getStatusCode(), array(500, 502, 503, 504))) {
452 if (null === $age = $entry->headers->getCacheControlDirective('stale-if-error')) {
453 $age = $this->options['stale_if_error'];
456 if (abs($entry->getTtl()) < $age) {
457 $this->record($request, 'stale-if-error');
464 RFC 7231 Sect. 7.1.1.2 says that a server that does not have a reasonably accurate
465 clock MUST NOT send a "Date" header, although it MUST send one in most other cases
466 except for 1xx or 5xx responses where it MAY do so.
468 Anyway, a client that received a message without a "Date" header MUST add it.
470 if (!$response->headers->has('Date')) {
471 $response->setDate(\DateTime::createFromFormat('U', time()));
474 $this->processResponseBody($request, $response);
476 if ($this->isPrivateRequest($request) && !$response->headers->hasCacheControlDirective('public')) {
477 $response->setPrivate();
478 } elseif ($this->options['default_ttl'] > 0 && null === $response->getTtl() && !$response->headers->getCacheControlDirective('must-revalidate')) {
479 $response->setTtl($this->options['default_ttl']);
486 * Checks whether the cache entry is "fresh enough" to satisfy the Request.
488 * @return bool true if the cache entry if fresh enough, false otherwise
490 protected function isFreshEnough(Request $request, Response $entry)
492 if (!$entry->isFresh()) {
493 return $this->lock($request, $entry);
496 if ($this->options['allow_revalidate'] && null !== $maxAge = $request->headers->getCacheControlDirective('max-age')) {
497 return $maxAge > 0 && $maxAge >= $entry->getAge();
504 * Locks a Request during the call to the backend.
506 * @return bool true if the cache entry can be returned even if it is staled, false otherwise
508 protected function lock(Request $request, Response $entry)
510 // try to acquire a lock to call the backend
511 $lock = $this->store->lock($request);
513 if (true === $lock) {
514 // we have the lock, call the backend
518 // there is already another process calling the backend
520 // May we serve a stale response?
521 if ($this->mayServeStaleWhileRevalidate($entry)) {
522 $this->record($request, 'stale-while-revalidate');
527 // wait for the lock to be released
528 if ($this->waitForLock($request)) {
529 // replace the current entry with the fresh one
530 $new = $this->lookup($request);
531 $entry->headers = $new->headers;
532 $entry->setContent($new->getContent());
533 $entry->setStatusCode($new->getStatusCode());
534 $entry->setProtocolVersion($new->getProtocolVersion());
535 foreach ($new->headers->getCookies() as $cookie) {
536 $entry->headers->setCookie($cookie);
539 // backend is slow as hell, send a 503 response (to avoid the dog pile effect)
540 $entry->setStatusCode(503);
541 $entry->setContent('503 Service Unavailable');
542 $entry->headers->set('Retry-After', 10);
549 * Writes the Response to the cache.
553 protected function store(Request $request, Response $response)
556 $this->store->write($request, $response);
558 $this->record($request, 'store');
560 $response->headers->set('Age', $response->getAge());
561 } catch (\Exception $e) {
562 $this->record($request, 'store-failed');
564 if ($this->options['debug']) {
569 // now that the response is cached, release the lock
570 $this->store->unlock($request);
574 * Restores the Response body.
576 private function restoreResponseBody(Request $request, Response $response)
578 if ($response->headers->has('X-Body-Eval')) {
581 if ($response->headers->has('X-Body-File')) {
582 include $response->headers->get('X-Body-File');
584 eval('; ?>'.$response->getContent().'<?php ;');
587 $response->setContent(ob_get_clean());
588 $response->headers->remove('X-Body-Eval');
589 if (!$response->headers->has('Transfer-Encoding')) {
590 $response->headers->set('Content-Length', \strlen($response->getContent()));
592 } elseif ($response->headers->has('X-Body-File')) {
593 // Response does not include possibly dynamic content (ESI, SSI), so we need
594 // not handle the content for HEAD requests
595 if (!$request->isMethod('HEAD')) {
596 $response->setContent(file_get_contents($response->headers->get('X-Body-File')));
602 $response->headers->remove('X-Body-File');
605 protected function processResponseBody(Request $request, Response $response)
607 if (null !== $this->surrogate && $this->surrogate->needsParsing($response)) {
608 $this->surrogate->process($request, $response);
613 * Checks if the Request includes authorization or other sensitive information
614 * that should cause the Response to be considered private by default.
616 * @return bool true if the Request is private, false otherwise
618 private function isPrivateRequest(Request $request)
620 foreach ($this->options['private_headers'] as $key) {
621 $key = strtolower(str_replace('HTTP_', '', $key));
623 if ('cookie' === $key) {
624 if (\count($request->cookies->all())) {
627 } elseif ($request->headers->has($key)) {
636 * Records that an event took place.
638 * @param Request $request A Request instance
639 * @param string $event The event name
641 private function record(Request $request, $event)
643 $this->traces[$this->getTraceKey($request)][] = $event;
647 * Calculates the key we use in the "trace" array for a given request.
649 * @param Request $request
653 private function getTraceKey(Request $request)
655 $path = $request->getPathInfo();
656 if ($qs = $request->getQueryString()) {
660 return $request->getMethod().' '.$path;
664 * Checks whether the given (cached) response may be served as "stale" when a revalidation
665 * is currently in progress.
667 * @param Response $entry
669 * @return bool true when the stale response may be served, false otherwise
671 private function mayServeStaleWhileRevalidate(Response $entry)
673 $timeout = $entry->headers->getCacheControlDirective('stale-while-revalidate');
675 if (null === $timeout) {
676 $timeout = $this->options['stale_while_revalidate'];
679 return abs($entry->getTtl()) < $timeout;
683 * Waits for the store to release a locked entry.
685 * @param Request $request The request to wait for
687 * @return bool true if the lock was released before the internal timeout was hit; false if the wait timeout was exceeded
689 private function waitForLock(Request $request)
692 while ($this->store->isLocked($request) && $wait < 100) {