willdurand / negotiation
Content Negotiation tools for PHP provided as a standalone library.
Installs: 92 999 611
Dependents: 167
Suggesters: 2
Security: 0
Stars: 1 414
Watchers: 27
Forks: 62
Open Issues: 9
Requires
- php: >=7.1.0
Requires (Dev)
- symfony/phpunit-bridge: ^5.0
- 3.1.0
- dev-master / 3.0.x-dev
- 3.0.0
- 3.0.0-alpha3
- 3.0.0-alpha2
- 3.0.0-alpha1
- 2.x-dev
- v2.3.1
- v2.3.0
- v2.2.1
- v2.2.0
- v2.1.0
- v2.0.3
- v2.0.2
- v2.0.1
- v2.0.0
- v2.0.0-alpha1
- 1.x-dev
- 1.5.0
- 1.4.0
- 1.3.4
- 1.3.3
- 1.3.2
- 1.3.1
- 1.3.0
- 1.2.x-dev
- 1.2.5
- 1.2.4
- 1.2.3
- 1.2.2
- 1.2.1
- 1.2.0
- 1.1.x-dev
- 1.1.2
- 1.1.1
- 1.1.0
- 1.0.x-dev
- 1.0.5
- 1.0.4
- 1.0.3
- 1.0.2
- 1.0.1
- 1.0.0
- 0.0.8
- 0.0.7
- 0.0.6
- 0.0.5
- 0.0.4
- 0.0.3
- 0.0.2
- 0.0.1
This package is auto-updated.
Last update: 2024-10-29 03:58:41 UTC
README
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 3.x+.
Documentation for version 1.x is available here: Negotiation 1.x documentation.
Documentation for version 2.x is available here: Negotiation 2.x documentation.
Installation
The recommended way to install Negotiation is through Composer:
$ composer require willdurand/negotiation
Usage Examples
Media Type 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.
Language Negotiation
<?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
.
Encoding Negotiation
<?php $negotiator = new \Negotiation\EncodingNegotiator(); $encoding = $negotiator->getBest($acceptHeader, $priorities);
The EncodingNegotiator
returns an instance of AcceptEncoding
.
Charset Negotiation
<?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*
Classes
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 theq
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.
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.
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.
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
).
Unit Tests
Setup the test suite using Composer:
$ composer install --dev
Run it using PHPUnit:
$ phpunit
Contributing
See CONTRIBUTING file.
Credits
-
Some parts of this library are inspired by:
- Symfony framework;
- FOSRest;
- PEAR HTTP2.
License
Negotiation is released under the MIT License. See the bundled LICENSE file for details.