Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/willdurand/Negotiation
Content Negotiation tools for PHP.
https://github.com/willdurand/Negotiation
content-negotiation negotiation php
Last synced: about 3 hours ago
JSON representation
Content Negotiation tools for PHP.
- Host: GitHub
- URL: https://github.com/willdurand/Negotiation
- Owner: willdurand
- License: mit
- Created: 2013-01-18T19:28:50.000Z (almost 12 years ago)
- Default Branch: master
- Last Pushed: 2023-08-03T17:52:44.000Z (over 1 year ago)
- Last Synced: 2024-10-29T15:04:16.966Z (10 days ago)
- Topics: content-negotiation, negotiation, php
- Language: PHP
- Homepage: https://williamdurand.fr/Negotiation/
- Size: 340 KB
- Stars: 1,414
- Watchers: 27
- Forks: 62
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-php - Negotiation - A content negotiation library. (Table of Contents / API)
- awesome-rest - Negotiation - Content negotiation library. (Servers / PHP)
- awesome-php-cn - Negotiation - 内容协商库. (目录 / API)
- awesome-projects - Negotiation - A content negotiation library. (PHP / API)
- awesome-php - Negotiation - A content negotiation library. (Table of Contents / API)
README
Negotiation
===========
[](https://github.com/willdurand/Negotiation/actions?query=workflow%3A%22ci%22+branch%3Amaster)
[](https://packagist.org/packages/willdurand/Negotiation)
[](https://packagist.org/packages/willdurand/Negotiation)
**Negotiation** is a standalone library without any dependencies that allows you
to implement [content
negotiation](https://tools.ietf.org/html/rfc7231#section-5.3) in your
application, whatever framework you use. This library is based on [RFC
7231](https://tools.ietf.org/html/rfc7231). 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](https://github.com/willdurand/Negotiation/blob/1.x/README.md#usage).
>
> Documentation for version **2.x** is available here: [Negotiation 2.x
> documentation](https://github.com/willdurand/Negotiation/blob/2.x/README.md#usage).
Installation
------------
The recommended way to install Negotiation is through
[Composer](http://getcomposer.org/):
```bash
$ composer require willdurand/negotiation
```
Usage Examples
--------------
### Media Type Negotiation
``` php
$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
getBest($acceptLanguageHeader, $priorities);
$type = $bestLanguage->getType();
// $type == 'fu';
$quality = $bestLanguage->getQuality();
// $quality == 0.9
```
The `LanguageNegotiator` returns an instance of `AcceptLanguage`.
### Encoding Negotiation
``` php
getBest($acceptHeader, $priorities);
```
The `EncodingNegotiator` returns an instance of `AcceptEncoding`.
### Charset Negotiation
``` php
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 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](http://semver.org/).
### End Of Life
#### 1.x
As of October 2016, [branch
`1.x`](https://github.com/willdurand/Negotiation/tree/1.x) is not supported
anymore, meaning major version `1` reached end of life. Last version is:
[1.5.0](https://github.com/willdurand/Negotiation/releases/tag/1.5.0).
#### 2.x
As of November 2020, [branch
`2.x`](https://github.com/willdurand/Negotiation/tree/2.x) is not supported
anymore, meaning major version `2` reached end of life. Last version is:
[2.3.1](https://github.com/willdurand/Negotiation/releases/tag/v2.3.1).
### Stable Version
#### 3.x (and `dev-master`)
Negotiation [3.0](https://github.com/willdurand/Negotiation/releases/tag/3.0.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](CONTRIBUTING.md) file.
Credits
-------
* Some parts of this library are inspired by:
* [Symfony](http://github.com/symfony/symfony) framework;
* [FOSRest](http://github.com/FriendsOfSymfony/FOSRest);
* [PEAR HTTP2](https://github.com/pear/HTTP2).
* [William Durand](https://github.com/willdurand)
* [@neural-wetware](https://github.com/neural-wetware)
License
-------
Negotiation is released under the MIT License. See the bundled LICENSE file for
details.