2.4.1.1.13. Server caching

Important points:

  • When enabling caching, ensure that the site returns caching prohibition headers when working with its admin panel, otherwise such pages may be cached and become accessible to unauthorized users.
  • When using sessions, PHP automatically adds the Cache-Control header to responses, and caching does not work by default. For caching to work, the cache limiter value must be public (see session_cache_limiter).

How caching works

sequenceDiagram autonumber participant client as Client box Hosting participant cache as Cache participant site as Site end client->>cache: Request cache->>cache: Cache check alt Cache exists and is not ignored cache->>client: Response from cache else Cache is missing or being ignored cache->>site: Request end site->>site: Request processing alt Without storing in cache site->>client: Response else With storing in cache site->>cache: Response cache->>cache: Response caching cache->>client: Response end

When using caching, all server responses are stored in the cache, and when receiving new requests, instead of forwarding them to the site scripts for processing, a ready-made response is returned from the cache. Using caching helps to significantly reduce the load on the web server.

The page is not stored in the cache:

  • If the request contains:
    • The Cookie header with the nocache key with a non-empty value and not equal to 0.
    • GET parameter nocache with a non-empty value and not equal to 0.
    • The Authorization header with a non-empty value and not equal to 0.
  • If the response contains:
    • The X-Accel-Expires header with a value of 0.
    • The Set-Cookie header.
    • The Vary header with the special value *.
    • The Cache-Control header with any of the following values: max-age=0, private, no-store, no-cache.
  • If the "output_buffering" parameter is disabled in the "PHP settings" section (when buffering is disabled, nginx does not process data from the web server and cannot cache it).

The existing cache is ignored if the request contains the same headers/parameters that prevent the page from being cached (see above). ⚠️ The cache is not overwritten or deleted. For example, when request A was made, the page was stored in the cache, then request B was made with conditions for ignoring the cache — the cache was ignored and the page was returned by the site, if request C is made without conditions for ignoring the cache — the cache that was generated for request A will be returned.

Using the X-Cache-Status response header, you can monitor cache usage:

  • Page was returned by the site:
    • MISS — page was not in the cache.
    • BYPASS — cache was ignored (see above).
    • EXPIRED — cache lifetime has expired.
  • Page was returned from cache:
    • STALE — cache lifetime has expired, but the current version of the page could not be obtained from the site.
    • REVALIDATED — cache lifetime has expired, but it was revalidated using the If-Modified-Since or If-None-Match header.
    • UPDATING — cache lifetime has expired, but the page is being updated from the site.
    • HIT — page was returned from cache.

When the cache is ignored and the response contains the Cache-Control header, the status may be appended with an indication of the reason why the cache was ignored: /PRIVATE, /NO-CACHE, /NO-STORE, /MAX-AGE.

Caching settings

Server caching is configured in the "Site settings" section on the "Caching" tab:

  • Modes:
    • "Disabled" — caching is disabled.
    • "Enabled" — caching with GET parameters (for requests to the same page with different GET parameters and without them, different responses will be returned from the cache).
    • "Ignore request parameters" — caching with GET parameters ignored (for requests to the same page with different GET parameters or without them, the same response will be returned from the cache).
  • "Lifetime" — how many minutes after the last use cache will be deleted.
    • Selected individually. For sites with frequent content updates, you can use lower values; for sites with infrequent updates, you can use higher values.

Clear cache

In the "Site settings" section, on the "Caching" tab, click "Clear cache".

Content
    (4)