request.md

# The Request Class

`Zend\Http\Request` is responsible for providing a fluent API that allows a
developer to interact with all the various parts of an HTTP request.

A typical HTTP request looks like this:

```text
| METHOD | URI | VERSION |
|        HEADERS         |
|         BODY           |
```

In simplified terms, the request consists of a method, URI, and HTTP version
number; together, they make up the "Request Line." This line is followed by zero
or more HTTP headers, which is followed by an empty line and then the request
body; the body is typically used when a client wishes to send data — which
could be urlencoded parameters, a JSON document, an XML document, or even one or
more files — to the server.  More information on the structure and
specification of a HTTP request can be found in
[RFC-2616 on the W3.org site](http://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html).

## Quick Start

Request objects can either be created from the provided `fromString()` factory,
or, if you wish to have a completely empty object to start with, by
manually instantiating the `Zend\Http\Request` class with no parameters.

```php
use Zend\Http\Request;

$request = Request::fromString(<<<EOS
POST /foo HTTP/1.1
HeaderField1: header-field-value1
HeaderField2: header-field-value2

foo=bar
EOS
);

// OR, the completely equivalent

$request = new Request();
$request->setMethod(Request::METHOD_POST);
$request->setUri('/foo');
$request->getHeaders()->addHeaders([
    'HeaderField1' => 'header-field-value1',
    'HeaderField2' => 'header-field-value2',
]);
$request->getPost()->set('foo', 'bar');
```

## Configuration Options

No configuration options are available.

## Available Methods

The following table details available methods, their signatures, and a brief
description. Note that the following references refer to the following
fully qualified class names and/or namespaces:

- `HeaderInterface`: `Zend\Http\Header\HeaderInterface`
- `Headers`: `Zend\Http\Headers`
- `Header`: `Zend\Http\Header`
- `Parameters`: `Zend\Stdlib\ParametersInterface`
- `Request`: `Zend\Http\Request`
- `Uri`: `Zend\Uri\Http`

Method signature                                                            | Description
--------------------------------------------------------------------------- | -----------
`static fromString(string $string) : Request`                               | A factory that produces a `Request` object from a well-formed HTTP request message string.
`setMethod(string $method) : self`                                          | Set the method for this request.
`getMethod() : string`                                                      | Return the method for this request.
`setUri(string|Uri $uri) : self`                                            | Set the URI/URL for this request; this can be a string or an instance of `Zend\Uri\Http`.
`getUri() : Uri`                                                            | Return the URI for this request object.
`getUriString() : string`                                                   | Return the URI for this request object as a string.
`setVersion(string $version) : self`                                        | Set the HTTP version for this object, one of 1.0 or 1.1 (`Request::VERSION_10`, `Request::VERSION_11`).
`getVersion() : string`                                                     | Return the HTTP version for this request.
`setQuery(Parameters $query) : self`                                        | Provide an alternate Parameter Container implementation for query parameters in this object. (This is NOT the primary API for value setting; for that, see `getQuery()`).
`getQuery(string|null $name, mixed|null $default) : null|string|Parameters` | Return the parameter container responsible for query parameters or a single query parameter based on `$name`.
`setPost(Parameters $post) : self`                                          | Provide an alternate Parameter Container implementation for POST parameters in this object. (This is NOT the primary API for value setting; for that, see `getPost()`).
`getPost(string|null $name, mixed|null $default) : null|string|Parameters`  | Return the parameter container responsible for POST parameters or a single POST parameter, based on `$name`.
`getCookie() : Header\Cookie`                                               | Return the Cookie header, this is the same as calling `$request->getHeaders()->get('Cookie');`.
`setFiles(Parameters $files) : self`                                        | Provide an alternate Parameter Container implementation for file parameters in this object, (This is NOT the primary API for value setting; for that, see `getFiles()`).
`getFiles(string|null $name, mixed|null $default) : null|string|Parameters` | Return the parameter container responsible for file parameters or a single file parameter, based on `$name`.
`setHeaders(Headers $headers) : self`                                       | Provide an alternate Parameter Container implementation for headers in this object, (this is NOT the primary API for value setting, for that see `getHeaders()`).
`getHeaders(string|null $name, mixed|null $default) : mixed`                | Return the container responsible for storing HTTP headers. This container exposes the primary API for manipulating headers set in the HTTP request. See the section on [Headers](headers.md) for more information. Return value is based on `$name`; `null` returns `Headers`, while a matched header returns a `Header\HeaderInterface` implementation for single-value headers or an `ArrayIterator` for multi-value headers.
`setMetadata(string|int|array|Traversable $spec, mixed $value) : self`      | Set message metadata.  Non-destructive setting of message metadata; always adds to the metadata, never overwrites the entire metadata container.
`getMetadata(null|string|int $key, null|mixed $default) : mixed`            | Retrieve all metadata or a single metadatum as specified by key.
`setContent(mixed $value) : self`                                           | Set request body (content).
`getContent() : mixed`                                                      | Get request body (content).
`isOptions() : bool`                                                        | Is this an OPTIONS method request?
`isGet() : bool`                                                            | Is this a GET method request?
`isHead() : bool`                                                           | Is this a HEAD method request?
`isPost() : bool`                                                           | Is this a POST method request?
`isPut() : bool`                                                            | Is this a PUT method request?
`isDelete() : bool`                                                         | Is this a DELETE method request?
`isTrace() : bool`                                                          | Is this a TRACE method request?
`isConnect() : bool`                                                        | Is this a CONNECT method request?
`isPatch() : bool`                                                          | Is this a PATCH method request?
`isXmlHttpRequest() : bool`                                                 | Is this a Javascript XMLHttpRequest?
`isFlashRequest() : bool`                                                   | Is this a Flash request?
`renderRequestLine() : string`                                              | Return the formatted request line (first line) for this HTTP request.
`toString() : string`                                                       | Returns string
`__toString() : string`                                                     | Allow PHP casting of this object.

## Examples

### Generating a Request object from a string

```php
use Zend\Http\Request;

$string = "GET /foo HTTP/1.1\r\n\r\nSome Content";
$request = Request::fromString($string);

$request->getMethod();    // returns Request::METHOD_GET
$request->getUri();       // returns Zend\Uri\Http object
$request->getUriString(); // returns '/foo'
$request->getVersion();   // returns Request::VERSION_11 or '1.1'
$request->getContent();   // returns 'Some Content'
```

### Retrieving and setting headers

```php
use Zend\Http\Request;
use Zend\Http\Header\Cookie;

$request = new Request();
$request->getHeaders()->get('Content-Type'); // return content type
$request->getHeaders()->addHeader(new Cookie(['foo' => 'bar']));
foreach ($request->getHeaders() as $header) {
    printf("%s with value %s\n", $header->getFieldName(), $header->getFieldValue());
}
```

### Retrieving and setting GET and POST values

```php
use Zend\Http\Request;

$request = new Request();

// getPost() and getQuery() both return, by default, a Parameters object, which
// extends ArrayObject
$request->getPost()->foo = 'Foo value';
$request->getQuery()->bar = 'Bar value';
$request->getPost('foo'); // returns 'Foo value'
$request->getQuery()->offsetGet('bar'); // returns 'Bar value'
```

### Generating a formatted HTTP Request from a Request object

```php
use Zend\Http\Request;

$request = new Request();
$request->setMethod(Request::METHOD_POST);
$request->setUri('/foo');
$request->getHeaders()->addHeaders([
    'HeaderField1' => 'header-field-value1',
    'HeaderField2' => 'header-field-value2',
]);
$request->getPost()->set('foo', 'bar');
$request->setContent($request->getPost()->toString());
echo $request->toString();

/** Will produce:
POST /foo HTTP/1.1
HeaderField1: header-field-value1
HeaderField2: header-field-value2

foo=bar
*/
```