juliangut/negotiate

Negotiation middleware

, _(*1)

, _(*2)

Negotiate

Simple and flexible negotiation middleware using willdurand/negotiation, _(*3)

Installation

Composer

composer require juliangut/negotiate

Usage

Require composer autoload file, _(*4)

require './vendor/autoload.php';

use Jgut\Negotiate\Negotiator;
use Jgut\Negotiate\Scope\Language;
use Jgut\Negotiate\Scope\MediaType;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;

$scopes = [
    new MediaType(['text/html', 'application/json'], 'text/html'),
    new Language(['en', 'es']),
];
/* @var \Psr\Http\Message\ResponseFactoryInterface $responseFactory */

$middleware = new Negotiator($scopes, $responseFactory);
$middleware->setAttributeName('negotiationProvider');

// Request handler
new class () implements RequestHandlerInterface {
    public function handle(ServerRequestInterface $request): ResponseInterface
    {
        $negotiationProvider = $request->getAttribute('negotiationProvider');

        $negotiationProvider->get('Accept-Language'); // \Negotiation\Accept
        $negotiationProvider->getAcceptLanguage(); // \Negotiation\AcceptLanguage
        $negotiationProvider->getAcceptLanguageLine(); // Negotiated language string
        $negotiationProvider->getAcceptCharset(); // null, not defined

        // ...
    }
};

Scopes

Encapsulate negotiation in a context, for example media type or character set. Give it a list of priorities, and you are good to go, _(*5)

An optional second parameter controls behaviour if request header is empty or negotiation could not be determined successfully. If set, it will be used to create a \Negotiation\AcceptHeader, A \Jgut\Negotiation\NegotiatorException will be thrown and captured by the middleware otherwise, _(*6)

Middleware

Middleware requires a list of negotiation scopes. Negotiation will take place in the middleware, _(*7)

• If everything goes well request will have
  • Headers of each scope overridden with negotiation result
  • An attribute with a \Jgut\Negotiate\Provider object with the result of the whole negotiation
• If negotiation goes south
  • A 415 response will be returned if Content-Type header negotiation fails
  • A 406 response will be returned if any other negotiation fails

Migration from 1.x

• PHP minimum required version is PHP 8.0
• Scope's default should be specified in each constructor should it be needed
• Scope's negotiateRequest now returns modified request (internal change)

Contributing

Found a bug or have a feature request? Please open a new issue. Have a look at existing issues before., _(*8)

See file CONTRIBUTING.md, _(*9)

License

See file LICENSE included with the source code for a copy of the license terms., _(*10)