polymorphine/headers

HTTP Response headers middleware

0.1.2 2022-10-05 01:38 UTC

Requires

• php: ^7.4 || ^8.0
• psr/http-message: ^1.0
• psr/http-server-handler: ^1.0
• psr/http-server-middleware: ^1.0

Requires (Dev)

• polymorphine/dev: 0.2.*

MIT

• Shudd3r

README

HTTP Response headers middleware

Installation with Composer

composer require polymorphine/headers

Basic usage

Set-Cookie header

1. Instantiate a cookie builder using ResponseHeaders context:

   $headers     = new ResponseHeaders();
   $cookieSetup = new CookieSetup($headers);

   Alternatively, instantiating CookieSetup is possible with ResponseHeaders method:

   $cookieSetup = $context->cookieSetup();

2. Configure cookie with array of its directives/attributes (see CookieSetup::directives() method):

   $cookieSetup->directives([
       'Domain'   => 'example.com',
       'Path'     => '/admin',
       'Expires'  => new DateTime(...),
       'MaxAge'   => 1234,
       'Secure'   => true,
       'HttpOnly' => true,
       'SameSite' => 'Strict'
   ]);

   Modifying setup object is also possible with its builder methods:

   $cookieSetup->domain('example.com')
               ->path('/admin')
               ->expires(new DateTime(...))
               ->maxAge(1234)
               ->secure()
               ->httpOnly()
               ->sameSite('Strict');

3. Instantiate Cookie type object with its name:

   $cookie = $cookieSetup->cookie('MyCookie');

4. Send value:

   $cookie->send('value');

   or order to revoke cookie, so that it should not be sent with future requests:

   $cookie->revoke();

   Each cookie can send/revoke header only once

Directives and Attributes

Directives are used according to RFC6265 section about Set-Cookie header attributes (except relatively new SameSite directive). Their description might also be found at Mozilla Developer Network. Concise description with additional class logic is explained in docBlocks of mutator methods of CookieSetup class.

Here are some class-specific rules for setting those directives:

• Empty values and root path (/) might be omitted as they're same as default.
• SameSite allowed values are Strict or Lax, but Lax will be set for any non-empty value given.
• Expires and MaxAge are different ways to set the same cookie's expiry date. If both directives will be passed into constructor or directivesArray() method, last value will be used due to overwrite.

Cookie with predefined directives

CookieSetup has two alternative methods creating Cookie instance: CookieSetup::permanentCookie() and CookieSetup::sessionCookie().

• Permanent constructor sets long (5 years) expiry values (Expires and MaxAge)
• Session constructor sets security directives (HttpOnly and SameSite=Lax)