diff --git a/user_guide_src/source/libraries/message.rst b/user_guide_src/source/libraries/message.rst index f250c02769..d2d7d59ee1 100644 --- a/user_guide_src/source/libraries/message.rst +++ b/user_guide_src/source/libraries/message.rst @@ -112,7 +112,7 @@ Class Reference Returns the value(s) of the header as a string. This method allows you to easily get a string representation of the header values when the header has multiple values. The values are appropriately joined:: - echo $message->headerLine('Host'); + echo $message->headerLine('Accept-Language'); // Outputs: en, en-US @@ -140,3 +140,117 @@ Class Reference $message->remove('Host'); + .. php:method:: appendHeader([$name[, $value]])) + + :param string $name: The name of the header to modify + :param mixed $value: The value to add to the header. + :returns: The current message instance + :rtype: 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. + :: + + $message->appendHeader('Accept-Language', 'en-US; q=0.8'); + + .. php:method:: protocolVersion() + + :returns: The current HTTP protocol version + :rtype: string + + Returns the message's current HTTP protocol. If none has been set, will return ``null``. Acceptable values + are ``1.0`` and ``1.1``. + + .. php:method:: setProtocolVersion($version) + + :param string $version: The HTTP protocol version + :returns: The current message instance + :rtype: CodeIgniter\\HTTP\\Message + + Sets the HTTP protocol version this Message uses. Valid values are ``1.0`` or ``1.1``.:: + + $message->setProtocolVersion('1.1'); + + .. php:method:: negotiateMedia($supported[, $strictMatch=false]) + + :param array $supported: An array of media types the application supports + :param bool $strictMatch: Whether it should force an exact match to happen. + :returns: The supported media type that best matches what is requested. + :rtype: string + + Parses the ``Accept`` header and compares with the application's supported media types to determine + the best match. Returns the appropriate media type. The first parameter is an array of application supported + media types that should be compared against header values:: + + $supported = [ + 'image/png', + 'image/jpg', + 'image/gif' + ]; + $imageType = $message->negotiateMedia($supported); + + The ``$supported`` array should be structured so that the application's preferred format is the first in the + array, with the rest following in descending order of priority. If no match can be made between the header + values and the supported values, the first element of the array will be returned. + + Per the `RFC `_ the match has the option of returning a + default value, like this method does, or to return an empty string. If you need to have an exact match and + would like an empty string returned instead, pass ``true`` as the second parameter.:: + + // Returns empty string if no match. + $imageType = $message->negotiateMedia($supported, true); + + The matching process takes into account the priorities and specificity of the RFC. This means that the more + specific header values will have a higher order of precedence, unless modified by a different ``q`` value. + For more details, please read the `appropriate section of the RFC `_. + + .. php:method:: negotiateCharset($supported) + + :param array $supported: An array of character sets the application supports. + :returns: The supported character set that best matches what is required.. + :rtype: string + + This is used identically to the ``negotiateMedia()`` method, except that it matches against the ``Accept-Charset`` + header string:: + + $supported = [ + 'utf-8', + 'iso-8895-9' + ]; + $charset = $message->negotiateCharset($supported); + + If no match is found, the system will default to ``utf-8``. + + .. php:method:: negotiateEncoding($supported) + + :param array $supported: An array of character encodings the application supports. + :returns: The supported character set that best matches what is required.. + :rtype: 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.:: + + $supported = [ + 'gzip', + 'compress' + ]; + $encoding = $message->negotiateEncoding($supported); + + .. php:method:: negotiateLanguage($supported) + + :param array $supported: An array of languages the application supports. + :returns: The supported language that best matches what is required.. + :rtype: string + + Determines the best match between the application-supported languages and the ``Accept-Language`` header value. + If no match is found, will return teh first element of the ``$supported`` array.:: + + $supported = [ + 'en', + 'fr', + 'x-pig-latin' + ]; + $language = $message->negotiateLanguage($supported); + + More information about the language tags are available in `RFC 1766 `_. +