README

协商中间件 是一个 PHP 库，用于协商 HTTP 请求的接受头。中间件通过查看客户端和服务器接受的值来选择最合适的选择。它支持头 accept、accept-language、accept-encoding 和 accept-charset。

此库是 中间件，用于 Slim 框架 3，但也可能用于任何使用符合 PSR-7 的 HTTP 消息的 PHP 代码。协商中间件基于 William Durand 的库。

安装

推荐使用 Composer 安装协商中间件

$ composer require gofabian/negotiation-middleware

Composer 会自动获取所有依赖项。协商中间件使用通用标准，并尝试根据 KISS 原则 减少所需包的数量

• PHP 7.3+
• PSR-7
• willdurand/negotiation 3.x
• 推荐：slim/slim 3.x

使用方法

第一个例子描述了如何结合使用 Slim 框架和协商中间件。以下例子更详细，并关注具体方面。

Slim 和协商中间件

最常见的方式是协商媒体类型。在这个例子中，服务器接受媒体类型 text/html 和 application/json

<?php
use Gofabian\Negotiation\NegotiationMiddleware;

// create Slim app
$app = new \Slim\App;

// configure middleware
$app->add(new NegotiationMiddleware([
    'accept' => ['text/html', 'application/json']
]));

// use negotiated media type
$app->get('/mediatype', function ($request, $response, $args) {
    $negotiation = $request->getAttribute('negotiation');
    $mediaType = $negotiation->getMediaType();
    return $response->write("media type = " . $mediaType);
});

// run app
$app->run();

让我们看看传入的 HTTP 请求和 接受的媒体类型的优先级

• 如果接受头包括 text/html，则 HTTP 响应将是 media type = text/html。配置的媒体类型中的第一个条目具有最高优先级。

• 如果接受头包括 application/json 但不包括 text/html，则 HTTP 响应将是 media type = application/json。

• 如果接受头为空，则 HTTP 响应将是 media type = text/html。默认情况下，如果不存在接受头，将选择具有最高优先级的条目。

• 如果接受头存在但既不包括 application/json 也不包括 text/html，则 HTTP 响应将具有状态 406 "不可接受"。

接受头

除了 媒体类型 之外，中间件还协商 语言、字符集 和 编码。

$app->add(new NegotiationMiddleware([
    'accept' => ['text/html', 'application/json'],
    'accept-language' => ['en', 'de-DE'],
    'accept-encoding' => ['gzip'],
    'accept-charset' => ['utf-8', 'ascii']
]));

HTTP 状态 406 - 不可接受

如果 HTTP 请求包含接受头，但没有一个值被协商中间件接受，则 HTTP 响应将具有 HTTP 状态 406 "不可接受"。

如果 HTTP 请求不包含接受头，协商中间件将采用具有最高优先级的值。或者，您也可以用 HTTP 状态 406 响应此类请求

$app->add(new NegotiationMiddleware(
    [ 'accept-language' => ['en', 'de-DE'] ],
    false // 406 status for empty accept headers
));

在这个例子中，如果 HTTP 请求不包含接受头 accept-language，协商中间件将返回 HTTP 状态 406。

协商结果

协商中间件将协商结果放入AcceptProvider实例中，并将其作为属性附加到PSR-7 HTTP请求上。默认属性名为negotiation，可以设置如下

$app->add(new NegotiationMiddleware(
    [ 'accept' => ['text/xml'] ],
    true,
    'foo' // custom name
));

$app->get('/example', function($request, $response, $args) {
    $result = $request->getAttribute('foo');
    return $response->write($result->getMediaType());
});

访问协商结果的一种简单方法是使用附加的AcceptProvider，如下所示

$result = $request->getAttribute('negotiation');

$result->getMediaType();  // these
$result->getLanguage();   // getters
$result->getCharset();    // return
$result->getEncoding();   // strings

或者，您可以通过以下方式获取协商库的原生结果对象

$result = $request->getAttribute('negotiation');

$result->getAccept();          // results
$result->getAcceptLanguage();  // from
$result->getAcceptCharset();   // negotiation
$result->getAcceptEncoding();  // library

有关更多信息，请参阅原始文档。

贡献

请参阅CONTRIBUTING以获取详细信息。

鸣谢

• gofabian
• 所有贡献者

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可证文件。