/**
* Return an instance with the specified header appended with the
* given value.
*
* 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.
*
* This method MUST be implemented in such a way as to retain the
* immutability of the message, and MUST return an instance that has the
* new header and/or value.
*
* @param string $name Case-insensitive header field name to add.
* @param string|string[] $value Header value(s).
* @return self
* @throws \InvalidArgumentException for invalid header names or values.
*/
public function withAddedHeader($header, $value)
{
if (is_string($value)) {
$value = [$value];
}
if (!is_array($value) || !$this->arrayContainsOnlyStrings($value)) {
throw new InvalidArgumentException('Invalid header value; must be a string or array of strings');
}
HeaderSecurity::assertValidName($header);
self::assertValidHeaderValue($value);
if (!$this->hasHeader($header)) {
return $this->withHeader($header, $value);
}
$normalized = strtolower($header);
$header = $this->headerNames[$normalized];
$new = clone $this;
$new->headers[$header] = array_merge($this->headers[$header], $value);
return $new;
}