Adding rest of HTTP/Message library docs.

2025-02-20 11:44:28 +08:00 · 2015-11-12 13:43:58 -06:00 · 2015-11-12 13:43:58 -06:00 · 5de286a741
commit 5de286a741
parent b43aefa2e7
1 changed files with 115 additions and 1 deletions
--- 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 <http://tools.ietf.org/html/rfc7231#section-5.3>`_ 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 <http://tools.ietf.org/html/rfc7231#section-5.3.2>`_.
+
+	.. 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 <https://www.ietf.org/rfc/rfc1766.txt>`_.
+