README.md
Anax Request
==================================
[](https://packagist.org/packages/anax/request)
[](https://gitter.im/canax?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[](https://travis-ci.org/canax/request)
[](https://circleci.com/gh/canax/request)
[](https://scrutinizer-ci.com/g/canax/request/build-status/master)
[](https://scrutinizer-ci.com/g/canax/request/?branch=master)
[](https://scrutinizer-ci.com/g/canax/request/?branch=master)
[](https://codeclimate.com/github/canax/request/maintainability)
[](https://www.codacy.com/app/mosbth/request?utm_source=github.com&utm_medium=referral&utm_content=canax/request&utm_campaign=Badge_Grade)
Anax Request module for wrapping all request related information.
The module essentially wraps access to `$_GET, $_POST, $_SERVER`, information send through the HTTP body and calculates url details (current, site, base, route path) from the request uri.
The module provides a framework unified way to access these global variables and it provides a way to inject a certain setup when using the module for unit testing.
Table of content
------------------
* [Class, interface, trait](#class-interface-trait)
* [Exceptions](#exceptions)
* [Configuration file](#configuration-file)
* [DI service](#di-service)
* [General usage within the Anax framework](#general-usage-within-the-Anax-framework)
* [Access as framework service](#access-as-framework-service)
* [Create and init an object](#create-and-init-an-object)
* [Extract url and route parts](#extract-url-and-route-parts)
* [Get and set `$_SERVER`](#get-and-set-_server)
* [Get and set `$_GET`](#get-and-set-_get)
* [Get and set `$_POST`](#get-and-set-_post)
* [Get and set request body](#get-and-set-request-body)
Class, interface, trait
------------------
The following classes, interfaces and traits exists.
| Class, interface, trait | Description |
|------------------------------------|-------------|
| `Anax\Request\Request` | Wrapper class for request details and related. |
Exceptions
------------------
Module specific exceptions are thrown through `Anax\Request\Exception`.
Configuration file
------------------
There is no configuration file for this module.
DI service
------------------
The module is created as a framework service within `$di`. You can see the details in the configuration file [`config/di/request.php`](config/di/request.php).
It can look like this.
```php
/**
* Configuration file for request service.
*/
return [
// Services to add to the container.
"services" => [
"request" => [
"shared" => true,
"callback" => function () {
$obj = new \Anax\Request\Request();
$obj->init();
return $obj;
}
],
],
];
```
1. The object is created as a shared resource.
1. The init-method reads information from the environment to find out the url of the request.
The service is lazy loaded and not created until it is used.
General usage within the Anax framework
------------------
The request service is a mandatory service within the Anax framework and it is the first service used when handling a request.
Here is the general flow for receiving a request, mapping it to a route and returning a response. This is found in the frontcontroller `htdocs/index.php` of an Anax installation.
```php
// Leave to router to match incoming request to routes
$response = $di->get("router")->handle(
$di->get("request")->getRoute(),
$di->get("request")->getMethod()
);
// Send the HTTP response with headers and body
$di->get("response")->send($response);
```
The request is used to get the request method and the route path, these are used by the router service to find a callback for the route. Each callback can then return a response which is sent through the response service.
Access as framework service
------------------
You can access the module as a framework service.
```php
# $app style
$app->request->getRoute();
# $di style, two alternatives
$di->get("request")->getRoute();
$request = $di->get("request");
$request->getRoute();
```
Create and init an object
------------------
This is how the object can be created. This is usually done within the framework as a sevice in `$di`.
```php
# Create an object
$request = new \Anax\Request\Request();
# Set (reset) globals, useful in unit testing
# when not using $_GET, $_POST, $_SERVER
$request->setGlobals();
# Init the class by extracting url parts and
# route path.
$request->init();
```
Extract url and route parts
------------------
When the object is initiated you can extract url and route parts from it. This is based on the current url.
```php
# Get site url including scheme, host and port.
$request->getSiteUrl();
# Get base url including site url and path to current index.php.
$request->getBaseUrl();
# Get current url as base url and attach
# the query string.
$request->getCurrentUrl();
# Get script name, index.php or other.
$request->getScriptName();
# Get HTTP request method, for example
# GET, POST, PUT, DELETE.
$request->getMethod();
# Get route path as a string.
$request->getRoute();
# Get route path parts in an array.
$request->getRouteParts();
```
Get and set `$_SERVER`
------------------
You can get and set values in the PHP global variable `$_SERVER`.
```php
# Read a value
$value = $request->getServer($key);
# Read all values as an key value array
$array = $request->getServer();
# Read a value and use $default if $key is not set.
$value = $request->getServer($key, $default);
# Set a value
$request->setServer($key, $value);
```
You are reading and setting values in a copy of `$_SERVER`, so you are not actually editing the global variable, just the internal representation within the class.
Get and set `$_GET`
------------------
You can get and set values in the PHP global variable `$_GET`.
```php
# Read a value
$value = $request->getGet($key);
# Read all values as an key value array
$array = $request->getGet();
# Read a value and use $default if $key is not set.
$value = $request->getGet($key, $default);
# Set a value
$request->setGet($key, $value);
```
You are reading and setting values in a copy of `$_GET`, so you are not actually editing the global variable, just the internal representation within the class.
Get and set `$_POST`
------------------
You can get and set values in the PHP global variable `$_POST`.
```php
# Read a value
$value = $request->getPost($key);
# Read all values as an key value array
$array = $request->getGet();
# Read a value and use $default if $key is not set.
$value = $request->getPost($key, $default);
# Set a value
$request->setPost($key, $value);
```
You are reading and setting values in a copy of `$_POST`, so you are not actually editing the global variable, just the internal representation within the class.
Get and set request body
------------------
You can get and set the value in the HTTP request body. Sometimes the HTTP request body is used to send parameters to an route.
```php
# Read the body
$request->getBody();
# Read the body and treat it as json
$request->getBodyAsJson()
# Set the body
$request->setBody($content);
```
You are setting values in a copy of the actual body, so you are not actually editing it, just the internal representation within the class.
License
------------------
This software carries a MIT license. See [LICENSE.txt](LICENSE.txt) for details.
```
.
..: Copyright (c) 2013 - 2020 Mikael Roos, mos@dbwebb.se
```