Переговоры о содержимом

Переговоры о содержимом — это способ определить, какой тип содержимого вернуть клиенту, основываясь на возможностях клиента и сервера. Это может быть использовано для определения, хочет ли клиент получить HTML или JSON, нужна ли картинка в формате jpg или png, какой тип сжатия поддерживается и многое другое. Это делается путем анализа четырех различных заголовков, каждый из которых может поддерживать несколько вариантов значений, каждый со своей приоритетностью. Попытка вручную сопоставить эти значения может быть довольно сложной. CodeIgniter предоставляет класс Negotiator для обработки этого за вас.

Загрузка класса

Вы можете загрузить экземпляр класса вручную через класс Service:

$negotiate = \Config\Services::negotiator();

Это позволит получить текущий экземпляр запроса и автоматически ввести его в класс Negotiator.

Этот класс не нужно загружать самостоятельно. Вместо этого к нему можно получить доступ через экземпляр запроса IncomingRequest. Хотя напрямую к нему получить доступ нельзя, вы легко можете получить доступ ко всем методам через метод negotiate():

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

При доступе таким образом, первый параметр — это тип содержимого, для которого вы пытаетесь найти соответствие, а второй — массив поддерживаемых значений.

Переговоры

В этом разделе мы обсудим 4 типа содержимого, которые могут быть предметом переговоров, и покажем, как это будет выглядеть, используя оба описанных выше метода доступа к переговорщику.

Медиа

Первый аспект, на который следует обратить внимание, — это обработка переговоров по «медиа». Они предоставляются заголовком Accept и являются одним из самых сложных заголовков. Типичный пример — клиент сообщает серверу, в каком формате он хочет получить данные. Это особенно распространено в API. Например, клиент может запросить данные в формате JSON от конечной точки API:

GET /foo HTTP/1.1
Accept: application/json

Теперь серверу необходимо предоставить список типов содержимого, которые он может предоставить. В этом примере API может возвращать данные в формате HTML, JSON или XML. Этот список должен быть предоставлен в порядке предпочтения:

$supported = [
    'application/json',
    'text/html',
    'application/xml',
];

$format = $request->negotiate('media', $supported);
// or
$format = $negotiate->media($supported);

В этом случае и клиент, и сервер могут договориться о форматировании данных как JSON, поэтому из метода negotiate возвращается «json». По умолчанию, если совпадение не найдено, возвращается первый элемент в массиве $supported. Однако в некоторых случаях вам может потребоваться обеспечить строгое соответствие формата. Если вы передадите true в качестве последнего значения, в случае отсутствия совпадения будет возвращена пустая строка:

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

Язык

Другое распространённое использование — определение языка, на котором должно быть предоставлено содержимое. Если вы используете сайт только на одном языке, это, очевидно, не повлияет, но любой сайт, который может предложить несколько переводов контента, найдёт это полезным, так как браузер, как правило, отправляет предпочтительный язык в заголовке Accept-Language:

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

В этом примере браузер предпочитает французский язык, а второй выбор — английский. Если ваш сайт поддерживает английский и немецкий языки, вы сделаете что-то вроде:

$supported = [
    'en',
    'de',
];

$lang = $request->negotiate('language', $supported);
// or
$lang = $negotiate->language($supported);

В этом примере «en» будет возвращено как текущий язык. Если совпадение не найдено, возвращается первый элемент в массиве $supported, поэтому это всегда должен быть предпочтительный язык.

Кодировка

Заголовок Accept-Encoding содержит наборы символов, которые предпочитает клиент, и используется для указания типа сжатия, который поддерживает клиент:

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

Ваш веб-сервер определит, какие типы сжатия вы можете использовать. Некоторые, например Apache, поддерживают только gzip:

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

См. больше информации на Wikipedia.

Набор символов

Желаемый набор символов передается через заголовок Accept-Charset:

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

По умолчанию, если совпадения не найдены, возвращается utf-8:

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