willdurand/negotiation

Content Negotiation tools for PHP provided as a standalone library.

Friday, August 4, 2017
by couac
Repository
27 Watchers
687 Stars
14,063,149 Installations

PHP
99 Dependents
2 Suggesters
40 Forks
5 Open issues
49 Versions
7 % Grown

The README.md

Negotiation

, _(*1)

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!, _(*2)

Important: You are browsing the documentation of Negotiation 3.x+., _(*3)

Documentation for version 1.x is available here: Negotiation 1.x documentation., _(*4)

Documentation for version 2.x is available here: Negotiation 2.x documentation., _(*5)

Installation

The recommended way to install Negotiation is through Composer:, _(*6)

$ composer require willdurand/negotiation

Usage Examples

Media Type Negotiation

``` php $negotiator = new \Negotiation\Negotiator();, _(*7)

$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');, _(*8)

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

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


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

### Language Negotiation

``` php
<?php

$negotiator = new \Negotiation\LanguageNegotiator();

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

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

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

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

The LanguageNegotiator returns an instance of AcceptLanguage., _(*11)

Encoding Negotiation

``` php <?php, _(*12)

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


The `EncodingNegotiator` returns an instance of `AcceptEncoding`.

### Charset Negotiation

``` php
<?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., _(*14)

`Accept*` Classes

Accept and Accept* classes share common methods such as:, _(*15)

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.

Versioning

Negotiation follows Semantic Versioning., _(*16)

End Of Life

1.x

As of October 2016, branch 1.x is not supported anymore, meaning major version 1 reached end of life. Last version is: 1.5.0., _(*17)

2.x

As of November 2020, branch 2.x is not supported anymore, meaning major version 2 reached end of life. Last version is: 2.3.1., _(*18)

Stable Version

3.x (and `dev-master`)

Negotiation 3.0 has been released on November 26th, 2020. This is the current stable version and it is in sync with the main branch (a.k.a. master)., _(*19)

Unit Tests

Setup the test suite using Composer:, _(*20)

$ composer install --dev

Run it using PHPUnit:, _(*21)

$ phpunit

Contributing

See CONTRIBUTING file., _(*22)

Credits

Some parts of this library are inspired by:, _(*23)
- Symfony framework;
- FOSRest;
- PEAR HTTP2.
William Durand, _(*24)
@neural-wetware

License

Negotiation is released under the MIT License. See the bundled LICENSE file for details., _(*25)

The Versions

04/08 2017

2.x-dev

2.9999999.9999999.9999999-dev http://williamdurand.fr/Negotiation/

Content Negotiation tools for PHP provided as a standalone library.

library negotiation

Content Negotiation tools for PHP provided as a standalone library.

willdurand/negotiation

The README.md

Negotiation

Installation

Usage Examples

Media Type Negotiation

Encoding Negotiation

Accept* Classes

Versioning

End Of Life

1.x

2.x

Stable Version

3.x (and dev-master)

Unit Tests

Contributing

Credits

License

The Versions

2.x-dev

The Requires

The Development Requires

by William Durand

dev-master

The Requires

The Development Requires

by William Durand

3.0.0-alpha3

The Requires

The Development Requires

by William Durand

v2.3.1

The Requires

The Development Requires

by William Durand

3.0.0-alpha2

The Requires

The Development Requires

by William Durand

v2.3.0

The Requires

The Development Requires

by William Durand

3.0.0-alpha1

The Requires

The Development Requires

by William Durand

v2.2.1

The Requires

The Development Requires

by William Durand

v2.2.0

The Requires

The Development Requires

by William Durand

v2.1.0

The Requires

The Development Requires

by William Durand

v2.0.3

The Requires

The Development Requires

by William Durand

v2.0.2

The Requires

by William Durand

v2.0.1

The Requires

by William Durand

1.x-dev

The Requires

by William Durand

1.5.0

The Requires

by William Durand

v2.0.0

The Requires

by William Durand

`Accept*` Classes

3.x (and `dev-master`)