Content Negotiation

Content negotiation is a way to determine what type of content to return to the client based on what the clientcan handle, and what the server can handle. This can be used to determine whether the client is wanting HTML or JSONreturned, whether the image should be returned as a jpg or png, what type of compression is supported and more. Thisis done by analyzing four different headers which can each support multiple value options, each with their own priority.Trying to match this up manually can be pretty challenging. CodeIgniter provides the Negotiator class thatcan handle this for you.

Loading the Class

You can load an instance of the class manually through the Service class:

  1. $negotiator = \Config\Services::negotiator();

This will grab the current request instance and automatically inject it into the Negotiator class.

This class does not need to be loaded on it’s own. Instead, it can be accessed through this request’s IncomingRequestinstance. While you cannot access it directly this way, you can easily access all of methods through the negotiate()method:

  1. $request->negotiate('media', ['foo', 'bar']);

When accessed this way, the first parameter is the type of content you’re trying to find a match for, while thesecond is an array of supported values.

Negotiating

In this section, we will discuss the 4 types of content that can be negotiated and show how that would look usingboth of the methods described above to access the negotiator.

Media

The first aspect to look at is handling ‘media’ negotiations. These are provided by the Accept header andis one of the most complex headers available. A common example is the client telling the server what format itwants the data in. This is especially common in API’s. For example, a client might request JSON formatted datafrom an API endpoint:

  1. GET /foo HTTP/1.1
  2. Accept: application/json

The server now needs to provide a list of what type of content it can provide. In this example, the API mightbe able to return data as raw HTML, JSON, or XML. This list should be provided in order of preference:

  1. $supported = [
  2.         'application/json',
  3.         'text/html',
  4.         'application/xml'
  5. ];
  6.  
  7. $format = $request->negotiate('media', $supported);
  8. // or
  9. $format = $negotiate->media($supported);

In this case, both the client and the server can agree on formatting the data as JSON so ‘json’ is returned fromthe negotiate method. By default, if no match is found, the first element in the $supported array would be returned.In some cases, though, you might need to enforce the format to be a strict match. If you pass true as thefinal value, it will return an empty string if no match is found:

  1. $format = $request->negotiate('media', $supported, true);
  2. // or
  3. $format = $negotiate->media($supported, true);

Language

Another common usage is to determine the language the content should be served in. If you are running only a singlelanguage site, this obviously isn’t going to make much difference, but any site that can offer up multiple translationsof content will find this useful, since the browser will typically send the preferred language along in the Accept-Languageheader:

  1. GET /foo HTTP/1.1
  2. Accept-Language: fr; q=1.0, en; q=0.5

In this example, the browser would prefer French, with a second choice of English. If your website supports Englishand German you would do something like:

  1. $supported = [
  2.         'en',
  3.         'de'
  4. ];
  5.  
  6. $lang = $request->negotiate('language', $supported);
  7. // or
  8. $lang = $negotiate->language($supported);

In this example, ‘en’ would be returned as the current language. If no match is found, it will return the first elementin the $supported array, so that should always be the preferred language.

Encoding

The Accept-Encoding header contains the character sets the client prefers to receive, and is used tospecify the type of compression the client supports:

  1. GET /foo HTTP/1.1
  2. Accept-Encoding: compress, gzip

Your web server will define what types of compression you can use. Some, like Apache, only support gzip:

  1. $type = $request->negotiate('encoding', ['gzip']);
  2. // or
  3. $type = $negotiate->encoding(['gzip']);

See more at Wikipedia.

Character Set

The desired character set is passed through the Accept-Charset header:

  1. GET /foo HTTP/1.1
  2. Accept-Charset: utf-16, utf-8

By default, if no matches are found, utf-8 will be returned:

  1. $charset = $request->negotiate('charset', ['utf-8']);
  2. // or
  3. $charset = $negotiate->charset(['utf-8']);