csp

Description

void csp ( mixed $csp1 [, mixed $... ] )

->csp() is used to add and combine various CSP directives, sources, flags, and modes.

Parameters

csp

The exact interpretation of csp is type dependent.

Array

A policy can be passed as an array. The syntax for which is as follows:

$csp = array(
    'directive-variant-1' => 'single-source',
    'directive-variant-2' => array('source1', 'source2'),
    'csp-flag-variant-1'  => null,
    'csp-flag-variant-2',
    'csp-flag-variant-3'  => array(null),
    'empty-directive'     => array()
);
$headers->csp($csp);

String

Perhaps more convenient for shorter policies, directives and values, or flags can be passed as ordered pairs of strings. The syntax as follows.

$headers->csp('directive-1', 'source', 'directive-2', 'source');
$headers->csp('directive-3', 'source');
$headers->csp('csp-flag-1', null);
$headers->csp('csp-flag-2');

Note that only one source may be passed per ordered pair, and a flag must either have null as a source, or have a non-string as its pair (nothing following is okay too).

For example, two csp flags could be declared in any of the following ways (where $csp is a csp array).

$headers->csp('flag-1', null, 'flag-2');

$headers->csp('flag-1');
$headers->csp('flag-2');

$headers->csp('flag-1', $csp, 'flag-2')

Though the final variant is non-ambiguous to SecureHeaders because it knows the type of $csp, it isn't the most readable of methods – someone reading the code may mistake $csp to be a string source value for flag-1. Though, because it is non-ambiguous it is still an accepted method.

Boolean

Passing the boolean true will put csp into report only mode for the following arguments (meaning that the browser will be told not to enforce anything in the argument list, but will report violations in the browser console, and will send reports to a reporting address if specified). Similarly, passing the boolean false will lock the mode of the current call of the csp function to being enforced.

If more that one boolean is present, the first will be taken as the mode, and subsequent booleans will be ignored.

Note that report only mode can also be achieved using cspro, which does not support its mode being changed to enforced.

Integer

Integers don't currently have a declared function. For now, they will be loosely casted as booleans and treated as above (meaning that an integer preceding a boolean will lock the mode of csp).

In future integers may be used to pass settings via bitwise operators, so take this functionality as a convenience for now which is subject to change. If you don't plan on reading the changelog between updates, then stay away from using integers to set the reporting mode of the csp function, as behaviour may change in the future.