README

Negotiation 是一个没有依赖的独立库，允许您在应用程序中实现 内容协商，无论您使用什么框架。此库基于 RFC 7231。Negotiation 使用简单，并且经过广泛的单元测试！

重要： 您正在浏览 Negotiation 3.x+ 的文档。

版本 1.x 的文档在此处可用： Negotiation 1.x 文档。

版本 2.x 的文档在此处可用： Negotiation 2.x 文档。

安装

安装 Negotiation 的推荐方法是使用 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'

Negotiator 返回 Accept 的实例，或者在协商最佳媒体类型失败时返回 null。

语言协商

<?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

LanguageNegotiator 返回 AcceptLanguage 的实例。

编码协商

<?php

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

EncodingNegotiator 返回 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

CharsetNegotiator 返回 AcceptCharset 的实例。

Accept* 类

Accept 和 Accept* 类共享公共方法，例如

• getValue() 返回接受值（例如 text/html; z=y; a=b; c=d）
• getNormalizedValue() 返回带有参数排序的值（例如 text/html; a=b; c=d; z=y）
• getQuality() 如果存在，返回质量（q 参数）
• getType() 返回接受类型（例如 text/html）
• getParameters() 返回参数集（如果提供了 q 参数，则排除该参数）
• getParameter() 允许通过其名称检索给定参数。如果没有提供，则回退到 $default（可为空）值。
• hasParameter() 指示是否存在参数。

版本控制

Negotiation 遵循 语义版本控制。

生命周期结束

1.x

截至 2016 年 10 月，分支 1.x 已不再受支持，这意味着主要版本 1 已达到生命周期的结束。最后一个版本是： 1.5.0。

2.x

截至 2020 年 11 月，分支 2.x 已不再受支持，这意味着主要版本 2 已达到生命周期的结束。最后一个版本是： 2.3.1。

稳定版本

3.x（和 dev-master）

Negotiation 3.0 于 2020 年 11 月 26 日发布。这是 当前稳定版本，它与主分支（也称为 master）同步。

单元测试

使用 Composer 设置测试套件

$ composer install --dev

使用 PHPUnit 运行它

$ phpunit

贡献

请参阅 CONTRIBUTING 文件。

鸣谢

• 本库的一些部分受到以下项目的启发：

  • Symfony 框架；
  • FOSRest;
  • PEAR HTTP2.

• William Durand will+git@drnd.me

• @neural-wetware

许可证

Negotiation 以 MIT 许可证发布。有关详细信息，请参阅捆绑的 LICENSE 文件。