Cache Control With Kohana 3

I recently did some work with cache control in Kohana and found the documentation a little thin out there, so I thought I would share what I learned.

Kohana has nice built in functionality for ETag validations, so you don't really need to roll your own cache headers.

If you need to brush up on web caching in general, I would recommend a quick read of Caching Tutorial for Web Authors and Webmasters, an excellent and concise reference.

Setup

For the purposes of this example, I'm creating a small controller which will use a short string as it's response body. The implementation here is trivial.

response->body( 'Hello, world!' );
    }

  } // Controller_Example

Let's look at the headers that are returned by default. Your headers may vary, so adjust accordingly.

If you look at the response headers from this request, you will note that there no Cache-Control, Last-Modified or ETag headers are returned. That gives us a blank slate to work with.

ETag

An ETag is a unique identifier string describing your content for cache validation. ETags have an advantage over Last-Modified headers in that there is no need to worry about clock synchronization. The server can determine how to generate ETags in any manner it desires.

The Response object in Kohana provides two methods useful for ETag based caching. The first is Response::generate_etag(), the second is Response::check_cache().

Response::generate_etag()

This method uses the sha1 hash to create a unique ETag based on the content of the rendered response. Because it renders and hashes the response before returning a result, there is a memory and CPU time hit, which increases with the size of your response.

Response::check_cache()

This method is the one we will use directly, as it compares the ETag of the response to request headers and takes the appropriate action.

It's signature is ($etag = NULL, Request $request = NULL). This is a bit odd, because although both are NULL by default, and the Request parameter is second, it is not optional while $etag is.

If you provide NULL for $etag the method will use Response::generate_etag() to get a valid ETag. As mentioned above, this is not always the optimal choice, so if you have a unique identifier that you can provide, you should.

Since this is a simplistic example, I will let Response::generate_etag() create my ETag value.

response->check_cache( null, $this->request );
    }

    public function action_index () {
      $this->response->body( 'Hello, world!' );
    }

  } // Controller_Example

Let's see the response headers for this version. We now have an ETag header, at the very bottom.

If we refresh the page again, we see that the browser sends an "If-None-Match" request header, which Response::check_cache() compares to the ETag. Finding that they match, the method returns a 304 response and immediately exits the script, causing the browser to use the cached version and saving the time it would take to send those bytes.

To demonstate how the ETag is generated let's modify our response body so that it returns new content for every request (well, every second at least).

response->check_cache( null, $this->request );
    }

    public function action_index () {
      $this->response->body( 'Hello, world at ' . date( DATE_RSS ) . '!' );
    }

  } // Controller_Example

After refreshing we get a new body, and a new ETag, breaking the cache and re-sending the entire page.

Remember, if you implement this, you should try to use an alternate ETag value if you can.

Cache Control

ETags aren't useful without a Cache-Control header, but you can set that yourself with Response::headers(), just be aware that Response::check_cache() will append must-revalidate to your header value, so don't add that part yourself.

response->headers( 'cache-control', 'private' );
      $this->response->check_cache( null, $this->request );
    }

    public function action_index () {
      $this->response->body( 'Hello, world at ' . date( DATE_RSS ) . '!' );
    }

  } // Controller_Example

Hopefully that clears up how to use the built in browser cache handling in Kohana 3, please leave your own tips or experiences in the comments!