README

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

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

1.x 版本的文档在这里可用： Negotiation 1.x 文档。

2.x 版本的文档在这里可用： Negotiation 2.x 文档。

安装

推荐通过 Composer 安装 Negotiation。

$ 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 参数，则不包括 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

贡献

请参阅 贡献 文件。

致谢

• 本库的部分灵感来源于

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

• William Durand

• @neural-wetware

许可证

Negotiation 采用 MIT 许可证发布。有关详细信息，请参阅附带的 LICENSE 文件。