Framework collects via STDOUT MVC API all client request information, mostly detected from PHP superglobals, into a Lucinda\STDOUT\Request object. All methods of this object are relevant for developers!
Following methods can be used to retrieve basic information
Request parameters are detected by matching HTTP request method to value of respective superglobal (eg: if method was POST, then $_POST is assumed) or input stream (for PUT, DELETE) and become available via following methods:
// if values of superglobals were:
$_SERVER["REQUEST_METHOD"] = "POST";
$_POST = ["a"=>"b", "c"=>"d"];
// then following evaluations will occur when a Controller uses this method:
$x = $this->request->parameters("a"); // $x will equal "b"
$x = $this->request->parameters("z"); // $x will equal NULL
// for same test case as above, following evaluations will happen
$x = $this->request->parameters(); // $x will equal ["a"=>"b", "c"=>"d"]
Uploaded files are detected based on contents of $_FILES superglobal. Latter structure is too clumsy and unintuitive, so it had to be remodelled into an Lucinda\STDOUT\Request\UploadedFiles\File tree available via uploadedFiles() method.
This method works exactly like parameters(), preserving input name hierarchy, only that files themselves are encapsulated into Lucinda\STDOUT\Request\UploadedFiles\File objects. When, for example, following files are uploaded:
<input type="file" name="a">
<input type="file" name="b">
<input type="file" name="c[x]">
<input type="file" name="c[y]">
Then when Controller runs this statement:
$x = $this->request->uploadedFiles();
Variable $x will evaluate to:
[
"a"=>object(Lucinda\STDOUT\Request\UploadedFiles\File),
"b"=>object(Lucinda\STDOUT\Request\UploadedFiles\File),
"c"=>[
"x"=>object(Lucinda\STDOUT\Request\UploadedFiles\File),
"y"=>object(Lucinda\STDOUT\Request\UploadedFiles\File)
]
]
Unless an error has occurred during upload, in which case a Lucinda\STDOUT\Request\UploadedFiles\Exception is thrown.
Getting request headers works in exactly the same way as parameters via following Request methods:
// if request headers were
Content-Type: text/html
Connection: keep-alive
// then following evaluations will occur when a Controller uses this method:
$x = $this->request->headers("Content-Type"); // $x will equal "text/html"
$x = $this->request->headers("Authorization"); // $x will equal NULL
If you desire to receive HTTP request headers in encapsulated form according to ISO standards, follow steps described in How To Validate Request Headers then use $this->attributes->getHeaders()->getRequest() to access them as Lucinda\Headers\Request instance. Example:
$this->attributes->getHeaders()->getRequest()->getAcceptLanguage()
Once a request is received, framework needs to match it with a <route> tag (see Routing section). Validation results are collected into Lucinda\STDOUT\Attributes object, which makes them available via following methods:
Format to resolve views into is detected according to following algorithm:
Final request uri is detected according to following algorithm:
Results of request uri validation will be collected and made available via getValidPage and getPathParameters methods above.
Request method a route allows is validated based on method attribute @ <route>. Example:
<route url="user/info/(id)" controller="UserInfoController" view="user-info" method="GET"/>
In case above, if route is called using a different request method from GET, a Lucinda\STDOUT\ValidationFailedException is thrown!
Framework supports validation of both path and request parameters (if names collide, former takes precedence). For each parameter you want to validate, you must set a <parameter> tag child to <route> holding the policy. Example:
<route url="user/info/(id)" controller="UserInfoController" view="user-info" method="GET">
<parameter name="id" validator="PositiveIntegerValidator"/>
</route>
Then you need to implement validator classes referenced, each extending Lucinda\STDOUT\EventListeners\Validators\ParameterValidator. Example:
class PositiveIntegerValidator implements Lucinda\STDOUT\EventListeners\Validators\ParameterValidator
{
public function validate($value)
{
return (is_integer($value) && $value >= 0);
}
}
If validate returns NULL, a Lucinda\STDOUT\ValidationFailedException is thrown! Otherwise, its result is collected by parameter name and will be made available via getValidParameters method above.
To perform automatic HTTP request headers validation you need to open bootstrap index.php file and add this event listener:
$object->addEventListener(Lucinda\STDOUT\EventType::REQUEST, "HttpHeadersListener");
which requires a <headers> tag @ stdout.xml:
<headers cacheable="application/cacheables/[DRIVER]"/>
Where [DRIVER] is a Lucinda\Headers\Cacheable implementation, able to get a string / date representation of response about to be sent. Framework comes by default with:
Following types of request header validation are supported, each requiring an extra event listener:
$object->addEventListener(Lucinda\STDOUT\EventType::RESPONSE, "HttpCachingListener");
$object->addEventListener(Lucinda\STDOUT\EventType::REQUEST, "HttpCorsListener");