api/symfony/Component/HttpKernel/HttpCache/HttpCache.yaml

name: HttpCache
class_comment: '# * Cache provides HTTP caching.

  # *

  # * @author Fabien Potencier <fabien@symfony.com>'
dependencies:
- name: Request
  type: class
  source: Symfony\Component\HttpFoundation\Request
- name: Response
  type: class
  source: Symfony\Component\HttpFoundation\Response
- name: HttpKernelInterface
  type: class
  source: Symfony\Component\HttpKernel\HttpKernelInterface
- name: TerminableInterface
  type: class
  source: Symfony\Component\HttpKernel\TerminableInterface
properties: []
methods:
- name: __construct
  visibility: public
  parameters:
  - name: kernel
  - name: store
  - name: surrogate
    default: 'null'
  - name: options
    default: '[]'
  comment: "# * Cache provides HTTP caching.\n# *\n# * @author Fabien Potencier <fabien@symfony.com>\n\
    # */\n# class HttpCache implements HttpKernelInterface, TerminableInterface\n\
    # {\n# public const BODY_EVAL_BOUNDARY_LENGTH = 24;\n# \n# private Request $request;\n\
    # private ?ResponseCacheStrategyInterface $surrogateCacheStrategy = null;\n# private\
    \ array $options = [];\n# private array $traces = [];\n# \n# /**\n# * Constructor.\n\
    # *\n# * The available options are:\n# *\n# *   * debug                  If true,\
    \ exceptions are thrown when things go wrong. Otherwise, the cache\n# *      \
    \                      will try to carry on and deliver a meaningful response.\n\
    # *\n# *   * trace_level            May be one of 'none', 'short' and 'full'.\
    \ For 'short', a concise trace of the\n# *                            main request\
    \ will be added as an HTTP header. 'full' will add traces for all\n# *       \
    \                     requests (including ESI subrequests). (default: 'full' if\
    \ in debug; 'none' otherwise)\n# *\n# *   * trace_header           Header name\
    \ to use for traces. (default: X-Symfony-Cache)\n# *\n# *   * default_ttl    \
    \        The number of seconds that a cache entry should be considered\n# *  \
    \                          fresh when no explicit freshness information is provided\
    \ in\n# *                            a response. Explicit Cache-Control or Expires\
    \ headers\n# *                            override this value. (default: 0)\n\
    # *\n# *   * private_headers        Set of request headers that trigger \"private\"\
    \ cache-control behavior\n# *                            on responses that don't\
    \ explicitly state whether the response is\n# *                            public\
    \ or private via a Cache-Control directive. (default: Authorization and Cookie)\n\
    # *\n# *   * skip_response_headers  Set of response headers that are never cached\
    \ even if a response is cacheable (public).\n# *                            (default:\
    \ Set-Cookie)\n# *\n# *   * allow_reload           Specifies whether the client\
    \ can force a cache reload by including a\n# *                            Cache-Control\
    \ \"no-cache\" directive in the request. Set it to ``true``\n# *             \
    \               for compliance with RFC 2616. (default: false)\n# *\n# *   * allow_revalidate\
    \       Specifies whether the client can force a cache revalidate by including\n\
    # *                            a Cache-Control \"max-age=0\" directive in the\
    \ request. Set it to ``true``\n# *                            for compliance with\
    \ RFC 2616. (default: false)\n# *\n# *   * stale_while_revalidate Specifies the\
    \ default number of seconds (the granularity is the second as the\n# *       \
    \                     Response TTL precision is a second) during which the cache\
    \ can immediately return\n# *                            a stale response while\
    \ it revalidates it in the background (default: 2).\n# *                     \
    \       This setting is overridden by the stale-while-revalidate HTTP Cache-Control\n\
    # *                            extension (see RFC 5861).\n# *\n# *   * stale_if_error\
    \         Specifies the default number of seconds (the granularity is the second)\
    \ during which\n# *                            the cache can serve a stale response\
    \ when an error is encountered (default: 60).\n# *                           \
    \ This setting is overridden by the stale-if-error HTTP Cache-Control extension\n\
    # *                            (see RFC 5861)."
- name: getStore
  visibility: public
  parameters: []
  comment: '# * Gets the current store.'
- name: getTraces
  visibility: public
  parameters: []
  comment: '# * Returns an array of events that took place during processing of the
    last request.'
- name: addTraces
  visibility: private
  parameters:
  - name: response
  comment: null
- name: getLog
  visibility: public
  parameters: []
  comment: '# * Returns a log message for the events of the last request processing.'
- name: getRequest
  visibility: public
  parameters: []
  comment: '# * Gets the Request instance associated with the main request.'
- name: getKernel
  visibility: public
  parameters: []
  comment: '# * Gets the Kernel instance.'
- name: getSurrogate
  visibility: public
  parameters: []
  comment: '# * Gets the Surrogate instance.

    # *

    # * @throws \LogicException'
- name: handle
  visibility: public
  parameters:
  - name: request
  - name: type
    default: HttpKernelInterface::MAIN_REQUEST
  - name: catch
    default: 'true'
  comment: null
- name: terminate
  visibility: public
  parameters:
  - name: request
  - name: response
  comment: null
- name: pass
  visibility: protected
  parameters:
  - name: request
  - name: catch
    default: 'false'
  comment: '# * Forwards the Request to the backend without storing the Response in
    the cache.

    # *

    # * @param bool $catch Whether to process exceptions'
- name: invalidate
  visibility: protected
  parameters:
  - name: request
  - name: catch
    default: 'false'
  comment: '# * Invalidates non-safe methods (like POST, PUT, and DELETE).

    # *

    # * @param bool $catch Whether to process exceptions

    # *

    # * @throws \Exception

    # *

    # * @see RFC2616 13.10'
- name: lookup
  visibility: protected
  parameters:
  - name: request
  - name: catch
    default: 'false'
  comment: '# * Lookups a Response from the cache for the given Request.

    # *

    # * When a matching cache entry is found and is fresh, it uses it as the

    # * response without forwarding any request to the backend. When a matching

    # * cache entry is found but is stale, it attempts to "validate" the entry with

    # * the backend using conditional GET. When no matching cache entry is found,

    # * it triggers "miss" processing.

    # *

    # * @param bool $catch Whether to process exceptions

    # *

    # * @throws \Exception'
- name: validate
  visibility: protected
  parameters:
  - name: request
  - name: entry
  - name: catch
    default: 'false'
  comment: '# * Validates that a cache entry is fresh.

    # *

    # * The original request is used as a template for a conditional

    # * GET request with the backend.

    # *

    # * @param bool $catch Whether to process exceptions'
- name: fetch
  visibility: protected
  parameters:
  - name: request
  - name: catch
    default: 'false'
  comment: '# * Unconditionally fetches a fresh response from the backend and

    # * stores it in the cache if is cacheable.

    # *

    # * @param bool $catch Whether to process exceptions'
- name: forward
  visibility: protected
  parameters:
  - name: request
  - name: catch
    default: 'false'
  - name: entry
    default: 'null'
  comment: '# * Forwards the Request to the backend and returns the Response.

    # *

    # * All backend requests (cache passes, fetches, cache validations)

    # * run through this method.

    # *

    # * @param bool          $catch Whether to catch exceptions or not

    # * @param Response|null $entry A Response instance (the stale entry if present,
    null otherwise)'
- name: isFreshEnough
  visibility: protected
  parameters:
  - name: request
  - name: entry
  comment: '# * Checks whether the cache entry is "fresh enough" to satisfy the Request.'
- name: lock
  visibility: protected
  parameters:
  - name: request
  - name: entry
  comment: '# * Locks a Request during the call to the backend.

    # *

    # * @return bool true if the cache entry can be returned even if it is staled,
    false otherwise'
- name: store
  visibility: protected
  parameters:
  - name: request
  - name: response
  comment: '# * Writes the Response to the cache.

    # *

    # * @throws \Exception'
- name: restoreResponseBody
  visibility: private
  parameters:
  - name: request
  - name: response
  comment: '# * Restores the Response body.'
- name: processResponseBody
  visibility: protected
  parameters:
  - name: request
  - name: response
  comment: null
- name: isPrivateRequest
  visibility: private
  parameters:
  - name: request
  comment: '# * Checks if the Request includes authorization or other sensitive information

    # * that should cause the Response to be considered private by default.'
- name: record
  visibility: private
  parameters:
  - name: request
  - name: event
  comment: '# * Records that an event took place.'
- name: getTraceKey
  visibility: private
  parameters:
  - name: request
  comment: '# * Calculates the key we use in the "trace" array for a given request.'
- name: mayServeStaleWhileRevalidate
  visibility: private
  parameters:
  - name: entry
  comment: '# * Checks whether the given (cached) response may be served as "stale"
    when a revalidation

    # * is currently in progress.'
- name: waitForLock
  visibility: private
  parameters:
  - name: request
  comment: '# * Waits for the store to release a locked entry.'
traits:
- Symfony\Component\HttpFoundation\Request
- Symfony\Component\HttpFoundation\Response
- Symfony\Component\HttpKernel\HttpKernelInterface
- Symfony\Component\HttpKernel\TerminableInterface
interfaces:
- HttpKernelInterface