bear/accept

Provides content-negotiation using Accept* headers for BEAR.Sunday

1.0.0 2022-06-24 06:10 UTC

Requires

• php: ^7.4 || ^8.0
• aura/accept: ^4.0
• bear/package: ^1.14
• bear/sunday: ^1.6

Requires (Dev)

• ext-json: *
• doctrine/coding-standard: ^9.0
• phpstan/phpstan: ^1.7
• phpunit/phpunit: ^8.5.24 || ^9.5
• ray/aop: ^2.12.1
• squizlabs/php_codesniffer: ^3.7
• vimeo/psalm: ^4.23

MIT

• Akihito Koriyama

• content negotiation
• accept

README

Provides content-negotiation using Accept* headers for BEAR.Sunday

Composer install

$ composer require bear/accept

Module install

use Ray\Di\AbstractModule;
use Ray\Di\Scope;

class AppModule extends AbstractModule
{
    /**
     * {@inheritdoc}
     */
    protected function configure()
    {
        $available = [
            'Accept' => [
                'application/hal+json' => 'prod-hal-app',
                'application/json' => 'prod-app',
                'text/csv' => 'prod-csv-app',
                'cli' => 'prod-html-app'
            ],
            'Accept-Language' => [
                'en-US' => 'en',
                'ja-JP' => 'ja'
            ]
        ];
        // $available support 'Accept' and 'Accept-Language' key only
        $this->install(new AcceptModule($available));
    }
}

Accept specifies all of the available media in the format [$mediatype => $context]. cli is the context in case of console access. The renderer of the context of the media type matched by content negotiation is used for rendering the resource.

Accept-Language specifies all available languages in the format [$lang => $contextKey].

For example, if application/hal+json and ja-JPmatches, the $context is prod-hal-jp-app. (We set JpModule in App\Module folder and bind it for Japanese.)

Usage

Apply to the specified resource

Annotate the resource to do content negotiation with @Produces.

use use BEAR\Accept\Annotation\Produces;

/**
 * @Produces({"application/json", "text/csv"})
 */
public function onGet()

application/json and text/csv media type is available for this resource.　The Vary header is added automatically.

Apply to all resources

To perform content negotiation on all resources, prepare a special bootstrap file. This is especially useful when negotiating languages.

cn.php

require dirname(__DIR__) . '/vendor/autoload.php';

$available = [
    'Accept' => [
        'text/html' => 'prod-html-app',
        'application/hal+json' => 'prod-hal-app',
        'application/json' => 'prod-app',
        'cli' => 'cli-html-app'
    ],
    'Accept-Language' => [
        'ja' => 'ja',
        'en-US' => 'us'
    ]
];
$accept = new \BEAR\Accept\Accept($available);
[$context, $vary] = $accept($_SERVER);
//

Add a vary header in Bootstrap to enable caching when using content negotiation.

+    /* @global \BEAR\Resource\Vary $vary */
+    if (isset($vary)) {
+        $page->headers['Vary'] = $vary;
+    }
     $page->transfer($app->responder, $_SERVER);

Prepare the module of the DI setting necessary for each language.

use BEAR\Sunday\Module\Constant\NamedModule;

class JaModule extends AbstractModule
{
    /**
     * {@inheritdoc}
     */
    protected function configure()
    {
        $text = ['greeting' => 'こんにちは'];
        $this->install(new NamedModule($text));
    }
}