51Degrees Pipeline for PHP

fiftyone\pipeline\core\Evidence Class Reference

Detailed Description

Storage of evidence on a FlowData object.

Collaboration diagram for fiftyone\pipeline\core\Evidence:

[legend]

Public Member Functions

 __construct (FlowData $flowData)
 Evidence container constructor.
 set (string $key, $value)
 Add the key value pair to the evidence collection where a flow element can use the key, and to the unaccepted collection where none can, so that a Cloud Request Engine can still send it.
 setArray ($array)
 Helper function to set multiple pieces of evidence from an array.
 setFromWebRequest (?array $server=null, ?array $cookies=null, ?array $query=null)
 Extract evidence from a web request No argument version automatically reads from current request using the $_SERVER, $_COOKIE, $_GET and $_POST globals.
 get (string $key)
 Get a piece of evidence by key, in any letter case.
 getAll ()
 Get all evidence, apart from the web request that get() returns under server.http-request.
 getAllIncludingUnaccepted ()
 Every value set on this Flow Data, both the values an element accepts and the values none does, apart from the web request that get() returns under server.http-request.

Data Fields

const HTTP_REQUEST_KEY = 'server.http-request'
 The key the web request is held under.

Static Protected Member Functions

static queryFromRequest (array $server)
 The form parameters of the current request, with the names as the browser sent them.
static isFormEncodedPost (array $server)
 Whether the request carries a form encoded body, which is the only body that can be read again as name and value pairs.
static rawBody ()
 The body of the request exactly as it arrived.
static parseFormEncoded (string $raw)
 Reads form encoded text into name and value pairs, decoding both and keeping every name exactly as it was sent.
static isDottedName (string $name)
 Whether a name sent by the browser is one whose dots are put back.
static asPhpGivesIt (string $name)
 The name PHP gives a parameter in $_GET and $_POST.
static maxInputVars ()
 How many parameters PHP itself would keep from one input source, which is how many are read from the request here.

Protected Attributes

FlowData $flowData
array $evidence = []
array $unaccepted = []
HttpRequest $httpRequest = null
 The web request, kept apart from the values above so that it never reaches an element's filter, a cache key or a request to the cloud.

Constructor & Destructor Documentation

◆ __construct()

fiftyone\pipeline\core\Evidence::__construct ( FlowData $flowData)

Evidence container constructor.

Parameters
\fiftyone\pipeline\core\FlowData$flowDataParent FlowData

Member Function Documentation

◆ asPhpGivesIt()

fiftyone\pipeline\core\Evidence::asPhpGivesIt ( string $name)
staticprotected

The name PHP gives a parameter in $_GET and $_POST.

Only a name holding a dot and no space reaches here, see isDottedName(), so replacing the dot is the whole of it.

◆ get()

fiftyone\pipeline\core\Evidence::get ( string $key)

Get a piece of evidence by key, in any letter case.

Returns
null|int|string|HttpRequest

◆ getAll()

fiftyone\pipeline\core\Evidence::getAll ( )

Get all evidence, apart from the web request that get() returns under server.http-request.

Returns
array<string, int|string>

◆ getAllIncludingUnaccepted()

fiftyone\pipeline\core\Evidence::getAllIncludingUnaccepted ( )

Every value set on this Flow Data, both the values an element accepts and the values none does, apart from the web request that get() returns under server.http-request.

A Cloud Request Engine sends this, as the Processing section of the cloud request engine specification requires. No other reader wants it, because an unaccepted value is one no element in the Pipeline asked for.

The unaccepted values come first. The request keeps the last value given for a field, so where an unaccepted value and an accepted one give the same field, the accepted value is sent.

Returns
array<string, int|string>

◆ isDottedName()

fiftyone\pipeline\core\Evidence::isDottedName ( string $name)
staticprotected

Whether a name sent by the browser is one whose dots are put back.

A dot is put back because it separates the parts of the names the cloud service reads, such as 'id.usage'. A space is not: no name the service reads holds one, PHP strips a leading space rather than replacing it so the name it gave could not be found to drop, and putting the space back produced an evidence key with a space in it, such as 'query.user agent' for a request sending 'user+agent', which nothing downstream matches. A name holding both is left to PHP whole, because putting back only the dot would leave PHP's name in place beside it and the evidence would carry the parameter twice.

◆ isFormEncodedPost()

fiftyone\pipeline\core\Evidence::isFormEncodedPost ( array $server)
staticprotected

Whether the request carries a form encoded body, which is the only body that can be read again as name and value pairs.

Parameters
array<string,string>$server Key-value pairs for the HTTP headers

◆ maxInputVars()

fiftyone\pipeline\core\Evidence::maxInputVars ( )
staticprotected

How many parameters PHP itself would keep from one input source, which is how many are read from the request here.

ini_get returns false where the setting cannot be read, and a value of zero or less would drop every parameter, so PHP's documented default stands in for both.

◆ parseFormEncoded()

fiftyone\pipeline\core\Evidence::parseFormEncoded ( string $raw)
staticprotected

Reads form encoded text into name and value pairs, decoding both and keeping every name exactly as it was sent.

A repeated name takes the last value, as PHP does. A name in the array form is skipped, because PHP builds an array for it and this is not trying to replace that.

Reading stops after max_input_vars names, which is where PHP itself stops filling $_GET and $_POST. Without the limit a request could carry any number of names past the point PHP would have given up, and every one of them would be offered to every flow element in the pipeline.

Returns
array<string, string>

◆ queryFromRequest()

fiftyone\pipeline\core\Evidence::queryFromRequest ( array $server)
staticprotected

The form parameters of the current request, with the names as the browser sent them.

PHP replaces a dot or a space in a parameter name with an underscore when it fills $_GET and $_POST, so a request carrying 'id.usage' arrives as 'id_usage' and the cloud service, which reads 'id.usage', never sees it. The raw query string and, for a form encoded body, the raw body are read again here so those names survive. A name PHP left alone is taken from $_GET and $_POST as before, and where a name was changed the changed one is dropped in favour of the name that was sent.

Only a name holding a dot is put back, see isDottedName(). A name written in the array form, such as 'a[b]', is left to PHP, which builds an array from it. A multipart body cannot be read a second time, so a dotted name sent in one keeps the underscore PHP gave it.

Parameters
array<string,string>$server Key-value pairs for the HTTP headers
Returns
array<string, int|string>

◆ rawBody()

fiftyone\pipeline\core\Evidence::rawBody ( )
staticprotected

The body of the request exactly as it arrived.

Overridden in tests, because php://input cannot be written to.

◆ set()

fiftyone\pipeline\core\Evidence::set ( string $key,
$value )

Add the key value pair to the evidence collection where a flow element can use the key, and to the unaccepted collection where none can, so that a Cloud Request Engine can still send it.

A key is held in one collection or the other and never in both.

Parameters
int | string$value

◆ setArray()

fiftyone\pipeline\core\Evidence::setArray ( $array)

Helper function to set multiple pieces of evidence from an array.

Parameters
array<string,int|string>$array

◆ setFromWebRequest()

fiftyone\pipeline\core\Evidence::setFromWebRequest ( ?array $server = null,
?array $cookies = null,
?array $query = null )

Extract evidence from a web request No argument version automatically reads from current request using the $_SERVER, $_COOKIE, $_GET and $_POST globals.

Parameters
null|array<string,string>$server Key-value pairs for the HTTP headers
null|array<string,string>$cookies Key-value pairs for the cookies
null|array<string,string>$query Key-value pairs for the form parameters