README

Note: This library has some HTTP validation caching logic that Symfony includes. Specifically, Symfony can handle Conditional GET requests "out of the box." However, this library also includes support for Concurrency Control (for validating POST or PUT update requests).

The Situation

Frameworks don't often give you tools to control HTTP caching mechanisms, such as setting ETags or Last-Modified dates.

Goals

This package aims to help you with conditional HTTP requests, using validation caching mechanisms

Allow Validation Caching (using ETags with If-Match, If-None-Match as well as Last-Modified with If-Modified-Since, If-Unmodified-Since headers)
Help developers learn about HTTP and Caching, a topic which is often ignored

Installation

This is a Composer package, available on Packagist.

To install it, edit your composer.json file and add:

{
    "require": {
        "fideloper/conditionalrequest": "dev-master"
    }
}

The default install will include some Symfony and Laravel (Illuminate) libraries. However these don't necessarily need to be used.

To install:

$ composer install

To install with Phpunit and Mockery to hack on:

$ composer install --dev

Methods Available:

using ( ResourceInterface $resource ) - Use ResourceInterface, which sets the ETag and/or Last Modified date automatically
setEtag ( string $etag ) - Set the ETag for an entity "manually"
setLastModified* ( DateTime $lastModified ) - Set the last modified date for an entity "manually"
bool doGet () - Determine if your app should respond to a GET request with entity (the resource) or 304 Not Modified
bool doUpate () - Determine if your app should update the entity/resource in a PUT/POST request or respond with 412 Precondition Failed

Basic Usage:

Laravel/Symfony
Zend [Future]
"Pure" PHP [Future]

More Usage:

For more complete usage examples and explanation, see the Wiki.

Some Explanation

There are a few types of caching:

In-app caching (Memcache, Redis, other memory stores)
HTTP caching - gateway, proxy and private (aka browsers, and similar)

Making a response (web page, api-response, etc) cachable by third-parties is part of the HTTP cache mechanisms. Which cache mechanisms you use depends on your use case.

The HTTP spec defines 2 methods of HTTP caching:

Validation - save bandwidth by not having an origin server reply with a full message body (header-only response)
Expiration - to save round-trips to the origin server - a cache can potentially serve a response directly, saving the origin server from even knowing about the request

Validation caching

Validation Caching, done with if-* headers (mainly if-match, if-none-match, if-modified-since, if-unmodified-since) is useful for 2 things:

Conditional GET requests

A server can tell the request 'nothing has changed since you last checked'. The client then knows to use its last-known version of the resource (assuming the reuslt of prior requests). This is good for mobile APIs where the bandwidth of re-sending a message body can be saved via conditional requests.

A server can respond with the resource as normal, or return a 304 Not Modified response if the resource wasn't updated since the client last asked for it.

Concurrency Control

In a PUT (or possibly POST) request, a server can check if the resource being updated was changed since the requester last checked (solves the Lost Update Problem). This is good for APIs with a lot of writes (updates) to resources.

A server can respond with 412 Precondition Failed if the client requesting the update doesn't have the latest knowledge of the resource.

This library is coded to help with Validation Cacheing.

Expiration caching

Expiration caching, done with Expires, Cache-Control, Last-Modified and other headers, can aid in caching a response for the next user (or even for one specific user), saving your server(s) from some traffic load.

fideloper / conditionalrequest

Maintainers

Details