lithium\net\http\Message::headers()

public method

Adds, gets or removes one or multiple headers at the same time.

Header names are not normalized and their casing left untouched. When headers are retrieved no sorting takes place. This behavior is inline with the specification which states header names should be treated in a case-insensitive way. Sorting is suggested but not required.

// Get single or multiple headers.
$request->headers('Content-Type'); // returns 'text/plain'
$request->headers(); // returns array('Content-Type: text/plain', ... )

// Set single or multiple headers.
$request->headers('Content-Type', 'text/plain');
$request->headers(array('Content-Type' => 'text/plain', ...));

// Alternatively use full header line.
$request->headers('Content-Type: text/plain');
$request->headers(array('Content-Type: text/plain', ...));

// Removing single or multiple headers.
$request->headers('Content-Type', false);
$request->headers(array('Content-Type' => false, ...));

Certain header fields support multiple values. These can be separated by comma or alternatively the header repeated for each value in the list.

When explicitly adding a value to an already existing header (that is when $replace is false) an array with those values is kept/created internally. Later when retrieving headers the header will be repeated for each value.

Note: Multiple headers of the same name are only valid if the values of that header can be separated by comma as defined in section 4.2 of RFC2616.

// Replace single or multiple headers
$request->headers('Cache-Control', 'no-store');
$request->headers(array('Cache-Control' => 'public'));
$request->headers('Cache-Control'); // returns 'public'

// Merging with existing array headers.
// Note that new elements are just appended and no sorting takes place.
$request->headers('Cache-Control', 'no-store');
$request->headers('Cache-Control', 'no-cache', false);
$request->headers();
// returns array('Cache-Control: no-store', 'Cache-Control: no-cache')

$request->headers('Cache-Control', 'no-store');
$request->headers('Cache-Control', array('no-cache'), false);
$request->headers();
// returns array('Cache-Control: no-store', 'Cache-Control: no-cache')

$request->headers('Cache-Control', 'max-age=0');
$request->headers('Cache-Control', 'no-store, no-cache');
$request->headers();
// returns array('Cache-Control: no-store, no-cache')

Parameters

  • string|array $key

    A header name, a full header line ('<key>: <value>'), or an array of headers to set in key => value form.

  • mixed $value

    A value to set if $key is a string. It can be an array to set multiple headers with the same key. If null, returns the value of the header corresponding to $key. If false, it unsets the header corresponding to $key.

  • boolean $replace

    Whether to override or add alongside any existing header with the same name.

Returns

mixed

When called with just $key provided, the value of a single header or an array of values in case there is multiple headers with this key. When calling the method without any arguments, an array of compiled headers in the form array('<key>: <value>', ...) is returned. All set and replace operations return no value for performance reasons.

Source

	public function headers($key = null, $value = null, $replace = true) {
		if ($key === null && $value === null) {
			$headers = array();

			foreach ($this->headers as $key => $value) {
				if (is_scalar($value)) {
					$headers[] = "{$key}: {$value}";
					continue;
				}
				foreach ($value as $val) {
					$headers[] = "{$key}: {$val}";
				}
			}
			return $headers;
		}
		if ($value === null && is_string($key) && strpos($key, ':') === false) {
			return isset($this->headers[$key]) ? $this->headers[$key] : null;
		}

		if (is_string($key)) {
			if (strpos($key, ':') !== false && preg_match('/(.*?):(.+)/', $key, $match)) {
				$key = $match[1];
				$value = trim($match[2]);
			} elseif ($value === false) {
				unset($this->headers[$key]);
				return;
			}
			if ($replace || !isset($this->headers[$key])) {
				$this->headers[$key] = $value;
			} elseif ($value !== $this->headers[$key]) {
				$this->headers[$key] = (array) $this->headers[$key];

				if (is_string($value)) {
					$this->headers[$key][] = $value;
				} else {
					$this->headers[$key] = array_merge($this->headers[$key], $value);
				}
			}
		} else {
			$replace = ($value === false) ? $value : $replace;

			foreach ((array) $key as $header => $value) {
				if (is_string($header)) {
					$this->headers($header, $value, $replace);
					continue;
				}
				$this->headers($value, null, $replace);
			}
		}
	}