From 81f036753272391360ba5b64e6dd93c4101a8733 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Thu, 13 Feb 2014 17:57:41 +0200 Subject: [ci skip] Add compatibility functions documentation + Sphinx build fixes for Cart --- user_guide_src/source/changelog.rst | 2 +- .../source/general/compatibility_functions.rst | 157 +++++++++++++++++++++ user_guide_src/source/general/index.rst | 1 + user_guide_src/source/libraries/cart.rst | 42 +++--- 4 files changed, 180 insertions(+), 22 deletions(-) create mode 100644 user_guide_src/source/general/compatibility_functions.rst (limited to 'user_guide_src') diff --git a/user_guide_src/source/changelog.rst b/user_guide_src/source/changelog.rst index d4f882064..ca31669e8 100644 --- a/user_guide_src/source/changelog.rst +++ b/user_guide_src/source/changelog.rst @@ -506,7 +506,7 @@ Release Date: Not Released - ``UTF8_ENABLED`` now requires only one of `Multibyte String `_ or `iconv `_ to be available instead of both. - Changed method ``clean_string()`` to utilize ``mb_convert_encoding()`` if it is available but ``iconv()`` is not. - - Added compatibility layers for PHP's `mbstring `_ (limited support) and `password `_ extensions. + - Added `compatibility layers ` for PHP's `mbstring `_ (limited support) and `password `_ extensions. - Removed ``CI_CORE`` boolean constant from *CodeIgniter.php* (no longer Reactor and Core versions). - Log Library will now try to create the **log_path** directory if it doesn't exist. - Added support for HTTP-Only cookies with new config option *cookie_httponly* (default FALSE). diff --git a/user_guide_src/source/general/compatibility_functions.rst b/user_guide_src/source/general/compatibility_functions.rst new file mode 100644 index 000000000..e025d2aa3 --- /dev/null +++ b/user_guide_src/source/general/compatibility_functions.rst @@ -0,0 +1,157 @@ +####################### +Compatibility Functions +####################### + +CodeIgniter provides a set of compatibility functions that enable +you to use functions what are otherwise natively available in PHP, +but only in higher versions or depending on a certain extension. + +Being custom implementations, these functions will also have some +set of dependancies on their own, but are still useful if your +PHP setup doesn't offer them natively. + +.. note:: Much like the `common functions `, the + compatibility functions are always available, as long as + their dependancies are met. + +.. contents:: + :local: + +.. raw:: html + +
+ +**************** +Password Hashing +**************** + +This set of compatibility functions offers a "backport" of PHP's +standard `Password Hashing extension `_ +that is otherwise available only since PHP 5.5. + +Dependancies +============ + +- PHP 5.3.7 +- ``CRYPT_BLOWFISH`` support for ``crypt()`` + +Constants +========= + +- ``PASSWORD_BCRYPT`` +- ``PASSWORD_DEFAULT`` + +Function reference +================== + +.. function:: password_get_info($hash) + + :param string $hash: Password hash + :returns: Information about the hashed password + :rtype: array + + For more information, please refer to the `PHP manual for + password_get_info() `_. + +.. function:: password_hash($password, $algo[, $options = array()]) + + :param string $password: Plain-text password + :param int $algo: Hashing algorithm + :param array $options: Hashing options + :returns: Hashed password or FALSE on failure + :rtype: string + + For more information, please refer to the `PHP manual for + password_hash() `_. + + .. note:: Unless you provide your own (and valid) salt, this function + has a further dependancy on an available CSPRNG source. Each + of the following would satisfy that: + - ``mcrypt_create_iv()`` with ``MCRYPT_DEV_URANDOM`` + - ``openssl_random_pseudo_bytes()`` + - /dev/arandom + - /dev/urandom + +.. function:: password_needs_rehash() + + :param string $hash: Password hash + :param int $algo: Hashing algorithm + :param array $options: Hashing options + :returns: TRUE if the hash should be rehashed to match the given algorithm and options, FALSE otherwise + :rtype: bool + + For more information, please refer to the `PHP manual for + password_needs_rehash() `_. + +.. function:: password_verify($password, $hash) + + :param string $password: Plain-text password + :param string $hash: Password hash + :returns: TRUE if the password matches the hash, FALSE if not + :rtype: bool + + For more information, please refer to the `PHP manual for + password_verify() `_. + +**************** +Multibyte String +**************** + +This set of compatibility functions offers limited support for PHP's +`Multibyte String extension `_. Because of +the limited alternative solutions, only a few functions are available. + +.. note:: When a character set parameter is ommited, + ``$config['charset']`` will be used. + +Dependancies +============ + +- `iconv `_ extension + +.. important:: This dependancy is optional and these functions will + always be declared. If iconv is not available, they WILL + fall-back to their non-mbstring versions. + +.. important:: Where a character set is supplied, it must be + supported by iconv and in a format that it recognizes. + +.. note:: For you own dependancy check on the actual mbstring + extension, use the ``MB_ENABLED`` constant. + +Function reference +================== + +.. function:: mb_strlen($str[, $encoding = NULL]) + + :param string $str: Input string + :param string $encoding: Character set + :returns: Number of characters in the input string or FALSE on failure + :rtype: string + + For more information, please refer to the `PHP manual for + mb_strlen() `_. + +.. function:: mb_strpos($haystack, $needle[, $offset = 0[, $encoding = NULL]]) + + :param string $haystack: String to search in + :param string $needle: Part of string to search for + :param int $offset: Search offset + :param string $encoding: Character set + :returns: Numeric character position of where $needle was found or FALSE if not found + :rtype: mixed + + For more information, please refer to the `PHP manual for + mb_strpos() `_. + +.. function:: mb_substr($str, $start[, $length = NULL[, $encoding = NULL]]) + + :param string $str: Input string + :param int $start: Position of first character + :param int $length: Maximum number of characters + :param string $encoding: Character set + :returns: Portion of $str specified by $start and $length or FALSE on failure + :rtype: string + + For more information, please refer to the `PHP manual for + mb_substr() `_. \ No newline at end of file diff --git a/user_guide_src/source/general/index.rst b/user_guide_src/source/general/index.rst index 2bc684a1d..195c4a98a 100644 --- a/user_guide_src/source/general/index.rst +++ b/user_guide_src/source/general/index.rst @@ -20,6 +20,7 @@ General Topics hooks autoloader common_functions + compatibility_functions routing errors Caching diff --git a/user_guide_src/source/libraries/cart.rst b/user_guide_src/source/libraries/cart.rst index 8a473b49d..d7d495967 100644 --- a/user_guide_src/source/libraries/cart.rst +++ b/user_guide_src/source/libraries/cart.rst @@ -114,26 +114,26 @@ same page. :: $data = array( - array( - 'id' => 'sku_123ABC', - 'qty' => 1, - 'price' => 39.95, - 'name' => 'T-Shirt', - 'options' => array('Size' => 'L', 'Color' => 'Red') - ), - array( - 'id' => 'sku_567ZYX', - 'qty' => 1, - 'price' => 9.95, - 'name' => 'Coffee Mug' - ), - array( - 'id' => 'sku_965QRS', - 'qty' => 1, - 'price' => 29.95, - 'name' => 'Shot Glass' - ) - ); + array( + 'id' => 'sku_123ABC', + 'qty' => 1, + 'price' => 39.95, + 'name' => 'T-Shirt', + 'options' => array('Size' => 'L', 'Color' => 'Red') + ), + array( + 'id' => 'sku_567ZYX', + 'qty' => 1, + 'price' => 9.95, + 'name' => 'Coffee Mug' + ), + array( + 'id' => 'sku_965QRS', + 'qty' => 1, + 'price' => 29.95, + 'name' => 'Shot Glass' + ) + ); $this->cart->insert($data); @@ -206,7 +206,7 @@ Updating The Cart To update the information in your cart, you must pass an array containing the Row ID and quantity to the ``$this->cart->update()`` -method:: +method. .. note:: If the quantity is set to zero, the item will be removed from the cart. -- cgit v1.2.3-24-g4f1b