gofabian / negotiation-middleware
PHP negotiation middleware for accept headers of PSR-7 requests. Uses the negotiation library willdurand/negotiation.
Installs: 74 507
Dependents: 3
Suggesters: 0
Security: 0
Stars: 10
Watchers: 3
Forks: 6
Open Issues: 3
Requires
- php: >=5.4.0
- psr/http-message: ^1.0
- willdurand/negotiation: ^2.0
Requires (Dev)
- phpunit/phpunit: ^4.8
- satooshi/php-coveralls: 0.6.1
Suggests
- slim/slim: The negotiation middleware is compatible to Slim 3.x
This package is not auto-updated.
Last update: 2024-10-26 18:59:57 UTC
README
The Negotiation Middleware is a PHP library that negotiates accept headers of HTTP requests. The middleware chooses the most fitting options by looking at the accepted values of client and server. It supports the headers accept, accept-language, accept-encoding and accept-charset.
This library is a middleware for the Slim framework 3 but may be used for any PHP code that uses HTTP messages conform to PSR-7. The Negotiation Middleware is based on the library from William Durand.
Installation
The recommended way to install the Negotiation Middleware is using Composer:
$ composer require gofabian/negotiation-middleware
Composer fetches all dependencies automatically. The Negotiation Middleware uses common standards and tries to reduce the number of required packages follwing the KISS principle:
- PHP 7.3+
- PSR-7
- willdurand/negotiation 3.x
- recommended: slim/slim 3.x
Usage
The first example describes how to use the Slim framework in combination with the Negotiation Middleware. The following examples are less detailed and bring specific aspects into focus.
Slim and the Negotiation Middleware
The most common way is to negotiate the media type. In this example the server accepts the media types text/html
and 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();
Let's have a look at incoming HTTP requests and the priority of accepted media types:
-
If the accept header includes
text/html
the HTTP response will bemedia type = text/html
. The first entry of the configured media types has the highest priority. -
If the accept header includes
application/json
but nottext/html
the HTTP response will bemedia type = application/json
. -
If the accept header is empty the HTTP response will be
media type = text/html
. By default the entry with highest priority will be chosen if the accept header does not exist. -
If the accept header is available but includes neither
application/json
nortext/html
the HTTP response will have status 406 "Not Acceptable".
Accept headers
In addition to media type the middleware negotiates language, charset and encoding:
$app->add(new NegotiationMiddleware([ 'accept' => ['text/html', 'application/json'], 'accept-language' => ['en', 'de-DE'], 'accept-encoding' => ['gzip'], 'accept-charset' => ['utf-8', 'ascii'] ]));
HTTP Status 406 - Not Acceptable
If the HTTP request contains an accept header but none of its values is accepted by the Negotiation Middleware the HTTP response will have the HTTP status 406 "Not Acceptable".
If the HTTP request does not contain an accept header the Negotiation Middleware will take the value with highest priority. Alternatively you can answer such requests with HTTP status 406, too:
$app->add(new NegotiationMiddleware( [ 'accept-language' => ['en', 'de-DE'] ], false // 406 status for empty accept headers ));
In this example the Negotiation Middleware will return HTTP status 406 if the HTTP request does not contain the accept header accept-language
.
Negotiation result
The Negotiation Middleware puts the negotiation result into an instance of AcceptProvider
and attaches it as an attribute to the PSR-7 HTTP request. The attribute name is negotiation
by default and may be set like this:
$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()); });
The easy way to access the negotiation results is to use the attached AcceptProvider
like this:
$result = $request->getAttribute('negotiation'); $result->getMediaType(); // these $result->getLanguage(); // getters $result->getCharset(); // return $result->getEncoding(); // strings
Alternatively you can get the original result objects of the negotiation library like this:
$result = $request->getAttribute('negotiation'); $result->getAccept(); // results $result->getAcceptLanguage(); // from $result->getAcceptCharset(); // negotiation $result->getAcceptEncoding(); // library
Have a look at the original documentation for more information.
Contributing
Please see CONTRIBUTING for details.
Credits
License
The MIT License (MIT). Please see License File for more information.