HTTP Caching (ETags, Cache-Control)

Also Known As

TL;DR

Explanation

HTTP caching is controlled primarily by Cache-Control (max-age, no-cache, no-store, public/private), ETags (opaque hash of response content enabling conditional requests), and Last-Modified. Correct caching headers can eliminate round-trips entirely for static assets and reduce server load for API responses. In PHP, set cache headers explicitly with header() — framework responses typically provide helper methods. For dynamic content, use Vary headers to cache different representations correctly and implement conditional GET responses that return 304 Not Modified without a body.

Common Misconception

Why It Matters

Common Mistakes

• No Cache-Control header — browsers guess, often defaulting to no caching.
• Cache-Control: no-cache on truly static assets — forces revalidation on every request.
• Not using ETags or Last-Modified for dynamic content that rarely changes.
• Caching responses that contain user-specific data without Vary: Cookie or private directive.

Code Examples

// No cache headers — browser re-fetches on every navigation:
header('Content-Type: application/json');
echo json_encode($data);
// Should add: header('Cache-Control: public, max-age=300');
// Or for user data: header('Cache-Control: private, max-age=60');

// ETags — conditional GET, saves bandwidth
public function show(int $id): Response {
    $user = $this->users->find($id);
    $etag = md5($user->updatedAt->format('U'));

    if ($this->request->header('If-None-Match') === $etag) {
        return response('', 304); // Not Modified — no body sent
    }

    return response()->json($user)
        ->header('ETag', $etag)
        ->header('Cache-Control', 'private, must-revalidate');
}

// Static assets — immutable long cache
header('Cache-Control: public, max-age=31536000, immutable');

// API responses — short cache, must revalidate
header('Cache-Control: private, max-age=60, must-revalidate');

References

• ↗ https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching
• ↗ https://developers.google.com/web/fundamentals/performance/optimizing-content-efficiency/http-caching

Tags

Related Terms