CodeIgniter v4.7 API

Negotiate
in package

Application

Class Negotiate

Provides methods to negotiate with the HTTP headers to determine the best type match between what the application supports and what the requesting server wants.

Properties

$request : IncomingRequest: Request

Methods

__construct() : mixed: Constructor
charset() : string: Determines the best charset to use based on the $supported types the application says it supports, and the types requested by the client.
encoding() : string: Determines the best encoding type to use based on the $supported types the application says it supports, and the types requested by the client.
language() : string: Determines the best language to use based on the $supported types the application says it supports, and the types requested by the client.
matchLocales() : bool: Will match locales against their broader pairs, so that fr-FR would match a supported localed of fr
matchTypes() : bool: Compares the types/subtypes of an acceptable Media type and the supported string.
media() : string: Determines the best content-type to use based on the $supported types the application says it supports, and the types requested by the client.
parseHeader() : array<int, array{value: string, q: float, params: array}>: Parses an Accept* header into it's multiple values.
setRequest() : $this: Stores the request instance to grab the headers from.
getBestLocaleMatch() : string: Try to find the best matching locale. It supports strict locale comparison.
getBestMatch() : string: Does the grunt work of comparing any of the app-supported values against a given Accept* header string.
match() : bool: Match-maker
matchParameters() : bool: Checks two Accept values with matching 'values' to see if their 'params' are the same.
getMatchSpecificity() : int: Returns how specifically a header value matches a supported value, or -1 if it does not match it. A wildcard is the least specific.
isExcluded() : bool: Checks whether the header excludes a supported value, that is, whether the most specific value in the header that matches it has q=0.

$request

Request


        protected
            IncomingRequest
    $request

__construct()

Constructor


    public
                    __construct([RequestInterface|null $request = null ]) : mixed

Parameters

$request : RequestInterface|null = null

charset()

Determines the best charset to use based on the $supported types the application says it supports, and the types requested by the client.


    public
                    charset(array<int, string> $supported) : string

If no match is found, the first, highest-ranking client requested type is returned.

Parameters

$supported : array<int, string>

Return values

string

encoding()

Determines the best encoding type to use based on the $supported types the application says it supports, and the types requested by the client.


    public
                    encoding([array<int, string> $supported = [] ]) : string

If no match is found, the first, highest-ranking client requested type is returned.

Parameters

$supported : array<int, string> = []

Return values

string

language()

Determines the best language to use based on the $supported types the application says it supports, and the types requested by the client.


    public
                    language(array<int, string> $supported) : string

If strict locale negotiation is disabled and no match is found, the first, highest-ranking client requested type is returned.

Parameters

$supported : array<int, string>

Return values

string

matchLocales()

Will match locales against their broader pairs, so that fr-FR would match a supported localed of fr


    public
                    matchLocales(array{value: string, q: float, params: array} $acceptable, array{value: string, q: float, params: array} $supported) : bool

Parameters

$acceptable : array{value: string, q: float, params: array}
$supported : array{value: string, q: float, params: array}

Return values

bool

matchTypes()

Compares the types/subtypes of an acceptable Media type and the supported string.


    public
                    matchTypes(array{value: string, q: float, params: array} $acceptable, array{value: string, q: float, params: array} $supported) : bool

Parameters

$acceptable : array{value: string, q: float, params: array}
$supported : array{value: string, q: float, params: array}

Return values

bool

media()

Determines the best content-type to use based on the $supported types the application says it supports, and the types requested by the client.


    public
                    media(array<int, string> $supported[, bool $strictMatch = false ]) : string

If no match is found, the first, highest-ranking client requested type is returned.

Parameters

$supported : array<int, string>
$strictMatch : bool = false: If TRUE, will return an empty string when no match found. If FALSE, will return the first supported element.

Return values

string

parseHeader()

Parses an Accept* header into it's multiple values.


    public
                    parseHeader(string $header) : array<int, array{value: string, q: float, params: array}>

This is based on code from Aura.Accept library.

Parameters

$header : string

Return values

array<int, array{value: string, q: float, params: array}>

setRequest()

Stores the request instance to grab the headers from.


    public
                    setRequest(RequestInterface $request) : $this

Parameters

$request : RequestInterface

Return values

$this

getBestLocaleMatch()

Try to find the best matching locale. It supports strict locale comparison.


    protected
                    getBestLocaleMatch(array<int, string> $supportedLocales, string|null $header) : string

If Config\App::$supportedLocales have "en-US" and "en-GB" locales, they can be recognized as two different locales. This method checks first for the strict match, then fallback to the most general locale (in this case "en") ISO 639-1 and finally to the locale variant "en-*" (ISO 639-1 plus "wildcard" for ISO 3166-1 alpha-2).

If nothing from above is matched, then it returns the first option from the $supportedLocales array.

Parameters

$supportedLocales : array<int, string>: App-supported values
$header : string|null: Compatible 'Accept-Language' header string

Return values

string

getBestMatch()

Does the grunt work of comparing any of the app-supported values against a given Accept* header string.


    protected
                    getBestMatch(array<int, string> $supported[, string $header = null ][, bool $enforceTypes = false ][, bool $strictMatch = false ][, bool $matchLocales = false ]) : string

Portions of this code base on Aura.Accept library.

Parameters

$supported : array<int, string>: App-supported values
$header : string = null: header string
$enforceTypes : bool = false: If TRUE, will compare media types and sub-types.
$strictMatch : bool = false: If TRUE, will return empty string on no match. If FALSE, will return the first supported element.
$matchLocales : bool = false: If TRUE, will match locale sub-types to a broad type (fr-FR = fr)

Return values

string —

Best match

match()

Match-maker


    protected
                    match(array{value: string, q: float, params: array} $acceptable, string $supported[, bool $enforceTypes = false ][, bool $matchLocales = false ]) : bool

Parameters

$acceptable : array{value: string, q: float, params: array}
$supported : string
$enforceTypes : bool = false
$matchLocales : bool = false

Return values

bool

matchParameters()

Checks two Accept values with matching 'values' to see if their 'params' are the same.


    protected
                    matchParameters(array{value: string, q: float, params: array} $acceptable, array{value: string, q: float, params: array} $supported) : bool

Parameters

$acceptable : array{value: string, q: float, params: array}
$supported : array{value: string, q: float, params: array}

Return values

bool

getMatchSpecificity()

Returns how specifically a header value matches a supported value, or -1 if it does not match it. A wildcard is the least specific.


    private
                    getMatchSpecificity(array{value: string, q: float, params: array} $accept, array{value: string, q: float, params: array} $supported, bool $enforceTypes, bool $matchLocales) : int

A media range matches the media types of its type and subtype that have its parameters. "text/html" is more specific than "text/", which is more specific than a full wildcard, and a range is more specific than one of the same kind with fewer parameters, so "text/html;level=1" is more specific than "text/html", and "text/;charset=utf-8" than "text/*" (RFC 9110, Section 12.5.1). Types, subtypes, parameter names and charset values are compared ignoring case (RFC 9110, Section 8.3). A language range matches the tags that equal it or start with it followed by "-", ignoring case, and is more specific with more subtags (RFC 4647, Section 3.3.1). Other values must be equal, ignoring case.

Parameters

$accept : array{value: string, q: float, params: array}
$supported : array{value: string, q: float, params: array}
$enforceTypes : bool
$matchLocales : bool

Return values

int

isExcluded()

Checks whether the header excludes a supported value, that is, whether the most specific value in the header that matches it has q=0.


    private
                    isExcluded(array<int, array{value: string, q: float, params: array}> $acceptable, string $supported, bool $enforceTypes, bool $matchLocales) : bool

Parameters

$acceptable : array<int, array{value: string, q: float, params: array}>
$supported : string
$enforceTypes : bool: If TRUE, the values are media types.
$matchLocales : bool: If TRUE, the values are language tags.

Return values

bool

Negotiate in package Application

Tags

Table of Contents

Properties

Methods

Properties

$request

Methods

__construct()

Parameters

charset()

Parameters

Return values

encoding()

Parameters

Return values

language()

Parameters

Return values

matchLocales()

Parameters

Return values

matchTypes()

Parameters

Return values

media()

Parameters

Return values

parseHeader()

Parameters

Return values

setRequest()

Parameters

Return values

getBestLocaleMatch()

Parameters

Return values

getBestMatch()

Parameters

Return values

match()

Parameters

Return values

matchParameters()

Parameters

Return values

getMatchSpecificity()

Parameters

Return values

isExcluded()

Parameters

Return values

Negotiate
in package

Application