Negotiation is a standalone library without any dependencies that allows you to implement content negotiation in your application, whatever framework you use. This library is based on RFC 7231. Negotiation is easy to use, and extensively unit tested!

Important: You are browsing the documentation of Negotiation 2.x. Documentation for version 1.x is available here: Negotiation 1.x documentation. You might also be interested in this: What's new in Negotiation 2?

The recommended way to install Negotiation is through Composer:

$ composer require willdurand/negotiation

$negotiator = new \Negotiation\Negotiator();

$acceptHeader = 'text/html, application/xhtml+xml, application/xml;q=0.9, */*;q=0.8';
$priorities   = array('text/html; charset=UTF-8', 'application/json', 'application/xml;q=0.5');

$mediaType = $negotiator->getBest($acceptHeader, $priorities);

$value = $mediaType->getValue();
// $value == 'text/html; charset=UTF-8'

The Negotiator returns an instance of Accept, or null if negotiating the best media type has failed.

<?php

$negotiator = new \Negotiation\LanguageNegotiator();

$acceptLangageHeader = 'en; q=0.1, fr; q=0.4, fu; q=0.9, de; q=0.2';
$priorities          = array('de', 'fu', 'en');

$bestLanguage = $negotiator->getBest($acceptLangageHeader, $priorities);

$type = $bestLanguage->getType();
// $type == 'fu';

$quality = $bestLanguage->getQuality();
// $quality == 0.9

The LanguageNegotiator returns an instance of AcceptLanguage.

<?php

$negotiator = new \Negotiation\EncodingNegotiator();
$encoding   = $negotiator->getBest($acceptHeader, $priorities);

The EncodingNegotiator returns an instance of AcceptEncoding.

<?php

$negotiator = new \Negotiation\CharsetNegotiator();

$acceptCharsetHeader = 'ISO-8859-1, UTF-8; q=0.9';
$priorities          = array('iso-8859-1;q=0.3', 'utf-8;q=0.9', 'utf-16;q=1.0');  

$bestCharset = $negotiator->getBest($acceptCharsetHeader, $priorities);

$type = $bestCharset->getType();
// $type == 'utf-8';

$quality = $bestCharset->getQuality();
// $quality == 0.81

The CharsetNegotiator returns an instance of AcceptCharset.

Accept and Accept* classes share common methods such as:

• getValue() returns the accept value (e.g. text/html; z=y; a=b; c=d)
• getNormalizedValue() returns the value with parameters sorted (e.g. text/html; a=b; c=d; z=y)
• getQuality() returns the quality if available (q parameter)
• getType() returns the accept type (e.g. text/html)
• getParameters() returns the set of parameters (excluding the q parameter if provided)
• getParameter() allows to retrieve a given parameter by its name. Fallback to a $default (nullable) value otherwise.
• hasParameter() indicates whether a parameter exists.

Setup the test suite using Composer:

$ composer install --dev

Run it using PHPUnit:

$ phpunit

See CONTRIBUTING file.

• Some parts of this library are inspired by:

  • Symfony framework;
  • FOSRest;
  • PEAR HTTP2.

• William Durand will+git@drnd.me

• @neural-wetware

Negotiation is released under the MIT License. See the bundled LICENSE file for details.