Content Negotiation

Setting up your content negotiator with default settings is trivial:

use Aphiria\ContentNegotiation\ContentNegotiator;

$contentNegotiator = new ContentNegotiator();

This will create a negotiator with JSON, XML, HTML, and plain text media type formatters.

If you'd like to customize things like media type formatters and supported languages, you can override the defaults:

use Aphiria\ContentNegotiation\AcceptCharsetEncodingMatcher;
use Aphiria\ContentNegotiation\AcceptLanguageMatcher;
use Aphiria\ContentNegotiation\ContentNegotiator;
use Aphiria\ContentNegotiation\MediaTypeFormatterMatcher;
use Aphiria\ContentNegotiation\MediaTypeFormatters\JsonMediaTypeFormatter;
use Aphiria\ContentNegotiation\MediaTypeFormatters\XmlMediaTypeFormatter;

// Register whatever media type formatters you support
$mediaTypeFormatters = [
    new JsonMediaTypeFormatter(),
    new XmlMediaTypeFormatter()
];
$contentNegotiator = new ContentNegotiator(
    $mediaTypeFormatters, 
    new MediaTypeFormatterMatcher($mediaTypeFormatters),
    new AcceptCharsetEncodingMatcher(),
    new AcceptLanguageMatcher(['en'])
);

Now you're ready to start negotiating.

Let's build off the previous example and negotiate a request manually. Let's assume the raw request looked something like this:

POST https://example.com/users HTTP/1.1
Content-Type: application/json; charset=utf-8
Content-Language: en-US
Encoding: UTF-8
Accept: application/json, text/xml
Accept-Language: en-US, en
Accept-Charset: utf-8, utf-16

{"id":123,"email":"foo@example.com"}

Here's how we'd negotiate and deserialize the request body:

use Aphiria\ContentNegotiation\NegotiatedBodyDeserializer;
use App\Users\User;

$bodyDeserializer = new NegotiatedBodyDeserializer($contentNegotiator);
// Assume the request was already instantiated
$user = $bodyDeserializer->readRequestBodyAs(User::class, $request);
echo $user->id; // 123
echo $user->email; // "foo@example.com"

You can manually negotiate a response by inspecting the Accept, Accept-Charset, and Accept-Language headers. If those headers are missing, we default to using the first media type formatter that can write the response body.

Constructing a response with all the appropriate headers is a little involved when doing it manually, which is why Aphiria provides NegotiatedResponseFactory to handle it for you:

use Aphiria\ContentNegotiation\NegotiatedResponseFactory;
use Aphiria\Net\Http\HttpStatusCode;

$responseFactory = new NegotiatedResponseFactory($contentNegotiator);
// Assume $user is a POPO User object
$response = $responseFactory->createResponse($request, HttpStatusCode::Ok, rawBody: $user);

Our response will look something like the following:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Language: en-US
Content-Length: 36

{"id":123,"email":"foo@example.com"}

use Aphiria\ContentNegotiation\ILanguageMatcher;
use Aphiria\Net\Http\Formatting\RequestParser;
use Aphiria\Net\Http\IRequest;

final class QueryStringLanguageMatcher implements ILanguageMatcher
{
    public function __construct(private RequestParser $requestParser) {}

    public function getBestLanguageMatch(IRequest $request): ?string
    {
        $queryStringVars = $this->requestParser->parseQueryString($request);
        $bestLanguage = null;
        
        if ($queryStringVars->tryGet('locale', $bestLanguage)) {
            return $bestLanguage;
        }

        return null;
    }
}

Pass your language matcher into ContentNegotiator.

use Aphiria\ContentNegotiation\ContentNegotiator;

$languageMatcher = new QueryStringLanguageMatcher(new RequestParser());
$contentNegotiator = new ContentNegotiator(
    // ...
    languageMatcher: $languageMatcher
);