HTTP Messages

    This class is the parent class that both the Request Class and the extend from. As such, some methods, such as the contentnegotiation methods, may apply only to a request or response, and not the other one, but they havebeen included here to keep the header methods together.

    At it’s heart Content Negotiation is simply a part of the HTTP specification that allows a singleresource to serve more than one type of content, allowing the clients to request the type ofdata that works best for them.

    A classic example of this is a browser that cannot display PNG files can request only GIF orJPEG images. When the getServer receives the request, it looks at the available file types the clientis requesting and selects the best match from the image formats that it supports, in this caselikely choosing a JPEG image to return.

    This same negotiation can happen with four types of data:

    • Media/Document Type - this could be image format, or HTML vs. XML or JSON.
    • Character Set - The character set the returned document should be set in. Typically is UTF-8.
    • Document Encoding - Typically the type of compression used on the results.
    • Document Language - For sites that support multiple languages, this helps determine which to return.
      • body()

    Returns:The current message bodyReturn type:string

    Returns the current message body, if any has been set. If not body exists, returns null:

    • setBody([$str])

    Parameters:

    1. - **$str** (_string_) – The body of the message.Returns:

    the Message instance to allow methods to be chained together.Return type:

    CodeIgniter\HTTP\Message instance.

    Sets the body of the current request.

    • populateHeaders()

    Returns:void

    Scans and parses the headers found in the SERVER data and stores it for later access.This is used by the to makethe current request’s headers available.

    The headers are any SERVER data that starts with HTTP, like HTTP_HOST. Each messageis converted from it’s standard uppercase and underscore format to a ucwords and dash format.The preceding HTTP is removed from the string. So HTTP_ACCEPT_LANGUAGE becomesAccept-Language.

    • getHeaders()

    Returns:An array of all of the headers found.Return type:array

    Returns an array of all headers found or previously set.

    • getHeader([$name[, $filter = null]])

    Parameters:

    1. - **$name** (_string_) – The name of the header you want to retrieve the value of.
    2. - **$filter** (_int_) – The type of filter to apply. A list of filters can be found [here](http://php.net/manual/en/filter.filters.php).Returns:

    The current value of the header. If the header has multiple values, they will be returned as an array.Return type:string|array|null

    1. // These are all the same:
    2. $message->getHeader('HOST');
    3. $message->getHeader('Host');
    4. $message->getHeader('host');

    If the header has multiple values, the values will return as an array of values. You can use the headerLine()method to retrieve the values as a string:

    1. echo $message->getHeader('Accept-Language');
    2.  
    3. // Outputs something like:
    4.         'en',
    5.         'en-US'
    6. ]

    You can filter the header by passing a filter value in as the second parameter:

    1. $message->getHeader('Document-URI', FILTER_SANITIZE_URL);
    • headerLine($name)

    Parameters:

    A string representing the header value.Return type:string

    Returns the value(s) of the header as a string. This method allows you to easily get a string representationof the header values when the header has multiple values. The values are appropriately joined:

    1. echo $message->headerLine('Accept-Language');
    2.  
    3. // Outputs:
    4. en, en-US
    • setHeader([$name[, $value]])

    Parameters:

    The current message instanceReturn type:CodeIgniter\HTTP\Message

    Sets the value of a single header. $name is the case-insensitive name of the header. If the headerdoesn’t already exist in the collection, it will be created. The $value can be either a stringor an array of strings:

    1. $message->setHeader('Host', 'codeigniter.com');
    • removeHeader([$name])

    Parameters:

    1. - **$name** (_string_) – The name of the header to remove.Returns:

    The current message instanceReturn type:CodeIgniter\HTTP\Message

    Removes the header from the Message. $name is the case-insensitive name of the header:

    1. $message->remove('Host');
    • appendHeader([$name[, $value]]))

    Parameters:

    1. - **$name** (_string_) – The name of the header to modify
    2. - **$value** (_mixed_) – The value to add to the header.Returns:

    The current message instanceReturn type:CodeIgniter\HTTP\Message

    Adds a value to an existing header. The header must already be an array of values instead of a single string.If it is a string then a LogicException will be thrown.

    1. $message->appendHeader('Accept-Language', 'en-US; q=0.8');
    • protocolVersion()

    Returns:The current HTTP protocol versionReturn type:string

    Returns the message’s current HTTP protocol. If none has been set, will return null. Acceptable valuesare 1.0 and 1.1.

    • setProtocolVersion($version)

    Parameters:

    1. - **$version** (_string_) – The HTTP protocol versionReturns:

    Sets the HTTP protocol version this Message uses. Valid values are 1.0 or :

      • negotiateMedia($supported[, $strictMatch=false])

      Parameters:

      The supported media type that best matches what is requested.Return type:string

      Parses the Accept header and compares with the application’s supported media types to determinethe best match. Returns the appropriate media type. The first parameter is an array of application supportedmedia types that should be compared against header values:

      1. $supported = [
      2.         'image/png',
      3.         'image/jpg',
      4.         'image/gif'
      5. ];
      6. $imageType = $message->negotiateMedia($supported);

      The $supported array should be structured so that the application’s preferred format is the first in thearray, with the rest following in descending order of priority. If no match can be made between the headervalues and the supported values, the first element of the array will be returned.

      Per the RFC the match has the option of returning adefault value, like this method does, or to return an empty string. If you need to have an exact match andwould like an empty string returned instead, pass true as the second parameter:

      1. // Returns empty string if no match.
      2. $imageType = $message->negotiateMedia($supported, true);

      The matching process takes into account the priorities and specificity of the RFC. This means that the morespecific header values will have a higher order of precedence, unless modified by a different q value.For more details, please read the .

      • negotiateCharset($supported)

      Parameters:

      1. - **$supported** (_array_) – An array of character sets the application supports.Returns:

      The supported character set that best matches what is required.Return type:string

      This is used identically to the negotiateMedia() method, except that it matches against the Accept-Charsetheader string:

      1. $supported = [
      2.         'utf-8',
      3.         'iso-8895-9'
      4. ];
      5. $charset = $message->negotiateCharset($supported);

      If no match is found, the system will default to utf-8.

      • negotiateEncoding($supported)

      Parameters:

      1. - **$supported** (_array_) – An array of character encodings the application supports.Returns:

      The supported character set that best matches what is required.Return type:string

      Determines the best match between the application-supported values and the Accept-Encoding header value.If no match is found, will return the first element of the $supported array:

      1. $supported = [
      2.         'gzip',
      3.         'compress'
      4. ];
      5. $encoding = $message->negotiateEncoding($supported);
      • negotiateLanguage($supported)

      Parameters:

        The supported language that best matches what is required.Return type:string

        Determines the best match between the application-supported languages and the header value.If no match is found, will return the first element of the $supported array: