# Trait HttpSoft\Message\MessageTrait

Trait implementing the methods defined in Psr\Http\Message\MessageInterface, used within HttpSoft\Message\RequestTrait and HttpSoft\Message\ResponseTrait.

Source code on GitHub.

# Public methods

See the original detailed description of the methods in the Psr\Http\Message\MessageInterface.

Setters prefixed with with and without they are immutable and return a new instance of the class (using HttpSoft\Message\MessageTrait) with the changed data.

# getProtocolVersion

Returns the HTTP protocol version as a string.

public function getProtocolVersion(): string;

Example of returned values: 1.0, 1.1, 2.0, 2.

# withProtocolVersion

Returns a new instance with the specified HTTP protocol version.

/**
 * @param string $version
 * @return static
 */
public function withProtocolVersion($version): MessageInterface;

If invalid specified HTTP protocol version, the \InvalidArgumentException exception will be thrown. Supported versions: 1.0, 1.1, 2.0 and 2.

$message->getProtocolVersion(); // '1.1'

$newMessage = $message->withProtocolVersion('2');
$newMessage->getProtocolVersion(); // '2'
$message->getProtocolVersion(); // '1.1'

$message->withProtocolVersion('1.1.1') // throws InvalidArgumentException

# getHeaders

Returns all HTTP message header values.

public function getHeaders(): array;

Example of returned values:

[
    'Content-Encoding' => [
        0 => 'gzip',
    ],
    'Content-Security-Policy' => [
        0 => 'block-all-mixed-content',
    ],
    'Allow' => [
        0 => 'GET',
        1 => 'HEAD',
    ],
];

# hasHeader

Checks if a header exists by the given case-insensitive name.

/**
 * @param string $name
 * @return bool
 */
public function hasHeader($name): bool;

# getHeader

Returns header value by the given case-insensitive name. Returns an empty array if no header with this name was found.

/**
 * @param string $name
 * @return array
 */
public function getHeader($name): array;

Example of returned values:

// $request->getHeader('Allow');
[
    0 => 'GET',
    1 => 'HEAD',
];

# getHeaderLine

Returns a comma-separated string of values for the specified header name, case-insensitive. Returns an empty string if no header with this name, was found.

/**
 * @param string $name
 * @return string
 */
public function getHeaderLine($name): string;

Example of returned values (for Allow): 'GET,HEAD'.

# withHeader

Returns a new instance with the provided value replacing the specified header. The header name is case-independent.

/**
 * @param string $name
 * @param string|string[] $value
 * @return static
 */
public function withHeader($name, $value): MessageInterface;

If invalid specified header names or values, the \InvalidArgumentException exception will be thrown.

$message->getHeader('Allow'); // ['POST']
$message->getHeaderLine('Allow'); // 'POST'

$newMessage1 = $message->withHeader('Allow', 'GET');
$newMessage1->getHeader('Allow'); // ['GET']
$newMessage1->getHeaderLine('Allow'); // 'GET'

$newMessage2 = $newMessage1->withHeader('Allow', ['GET', 'HEAD']);
$newMessage2->getHeader('Allow'); // ['GET', 'HEAD']
$newMessage2->getHeaderLine('Allow'); // 'GET,HEAD'

$message->withHeader('All/ow', 'GET') // throws InvalidArgumentException
$message->withHeader('Allow', "GE\nT") // throws InvalidArgumentException

# withAddedHeader

Returns a new instance with the specified header appended with the given value. The header name is case-independent.

/**
 * @param string $name
 * @param string|string[] $value
 * @return static
 */
public function withAddedHeader($name, $value): MessageInterface;

Existing values for the specified header will be maintained. The new value(s) will be appended to the existing list. If the header did not exist previously, it will be added.

If invalid specified header names or values, the \InvalidArgumentException exception will be thrown.

$message->getHeader('Allow'); // ['POST']
$message->getHeaderLine('Allow'); // 'POST'

$newMessage1 = $message->withAddedHeader('Allow', 'GET');
$newMessage1->getHeader('Allow'); // ['POST', 'GET']
$newMessage1->getHeaderLine('Allow'); // 'POST,GET'

$newMessage2 = $newMessage1->withAddedHeader('Allow', ['HEAD', 'OPTIONS']);
$newMessage2->getHeader('Allow'); // ['POST', 'GET', 'HEAD', 'OPTIONS']
$newMessage2->getHeaderLine('Allow'); // 'POST,GET,HEAD,OPTIONS'

$message->withAddedHeader('All/ow', 'GET') // throws InvalidArgumentException
$message->withAddedHeader('Allow', "GE\nT") // throws InvalidArgumentException

# withoutHeader

Returns a new instance without the specified header. The header name is case-independent.

/**
 * @param string $name
 * @return static
 */
public function withoutHeader($name): MessageInterface;

If header with the specified name, is not found, returns the current instance.

$message->getHeader('Allow'); // ['POST']
$message->getHeaderLine('Allow'); // 'POST'

$newMessage = $message->withoutHeader('Allow');
$newMessage->getHeader('Allow'); // []
$newMessage->getHeaderLine('Allow'); // ''

# getBody

Returns the HTTP message body.

public function getBody(): StreamInterface;

Psr\Http\Message\StreamInterface methods are implemented in the HttpSoft\Message\StreamTrait.

# withBody

Return a new instance with the specified message body.

public function withBody(StreamInterface $body): MessageInterface;

The body must be a Psr\Http\Message\StreamInterface instance.