nginx Caching

The nginx configuration by default enables static content caching via proxy_cache directives.

General operation

The configuration stores up to 1 GB of cached content under the zone zendphp.

The cache key includes: scheme, request method, host, and request URI.

Only HTTP GET and HEAD requests are cached.

nginx caches a response only if:

  • An Expires header with a future date or

  • A Cache-Control header with a non-zero max-age value is present.

Cache-Control directives are always honored:

Responses marked private, no-cache, or no-store are not cached.

nginx respects the ETag header.

Any response containing a Set-Cookie header is never cached.

Unless your PHP application sets Expires, Cache-Control, and/or ETag HTTP response headers, your content will not be cached.

You must explicitly configure these headers to enable caching.

Disable static content caching

You can disable static content caching by including the following in your vhost configuration:

Copy 
proxy_cache off;

If you include this within a location directive, it will only apply to the URLs matched in that directive, allowing you to selectively disable caching for a set of matching URLs.

Punch a hole in static content caching

To view uncached content, append a query string such as ?nocache to the request URL.

If you want to use a different query string argument, or, for instance, use a cookie or require an authorization header, you can change the proxy_cache_bypass directive in your vhost:

Copy 
procy_cache_bypass $cookie_nocache;     # Presence of a "nocache" cookie disables caching
procy_cache_bypass $cookie_PHPSESSID;   # Presence of a session cookie disables caching
proxy_cache_bypass $http_authorization; # Presence of an Authorization header disables caching

Use a custom cache key

A common requirement is to allow caching while distinguishing between logged-in and anonymous users.

You can accomplish that if you know the name of the cookie that indicates a PHP session identifier.

For this example, let's assume your PHP session ID key is PHPSESSID.

You could then use the following to set cache key to include that value:

Copy 
proxy_cache_key "$scheme$request_method$host$request_uri$cookie_PHPSESSID"

Instrument cache status

If you want to include the cache status as a client response header, you can add the header within your vhost:

Copy 
add_header X-Cache-Status $upstream_cache_status;

This will be populated with one of the following values:

  • MISS

  • BYPASS

  • EXPIRED

  • STALE

  • UPDATING

  • REVALIDATED

  • HIT