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 dependencies 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 dependencies are met.

* Password Hashing

  * Dependencies

  * Constants

  * Function reference

* Hash (Message Digest)

  * Dependencies

  * Function reference

* Multibyte String

  * Dependencies

  * Function reference

* Standard Functions

  * Dependencies

  * Function reference


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.


Dependencies
------------

* PHP 5.3.7

* "CRYPT_BLOWFISH" support for "crypt()"


Constants
---------

* "PASSWORD_BCRYPT"

* "PASSWORD_DEFAULT"


Function reference
------------------

password_get_info($hash)

   Parameters:
      * **$hash** ("string") – Password hash

   Returns:
      Information about the hashed password

   Return type:
      "array"

   For more information, please refer to the PHP manual for
   password_get_info().

password_hash($password, $algo[, $options = array()])

   Parameters:
      * **$password** ("string") – Plain-text password

      * **$algo** ("int") – Hashing algorithm

      * **$options** ("array") – Hashing options

   Returns:
      Hashed password or FALSE on failure

   Return type:
      "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 dependency 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

password_needs_rehash()

   Parameters:
      * **$hash** ("string") – Password hash

      * **$algo** ("int") – Hashing algorithm

      * **$options** ("array") – Hashing options

   Returns:
      TRUE if the hash should be rehashed to match the given algorithm
      and options, FALSE otherwise

   Return type:
      "bool"

   For more information, please refer to the PHP manual for
   password_needs_rehash().

password_verify($password, $hash)

   Parameters:
      * **$password** ("string") – Plain-text password

      * **$hash** ("string") – Password hash

   Returns:
      TRUE if the password matches the hash, FALSE if not

   Return type:
      "bool"

   For more information, please refer to the PHP manual for
   password_verify().


Hash (Message Digest)
=====================

This compatibility layer contains backports for the "hash_equals()"
and "hash_pbkdf2()" functions, which otherwise require PHP 5.6 and/or
PHP 5.5 respectively.


Dependencies
------------

* None


Function reference
------------------

hash_equals($known_string, $user_string)

   Parameters:
      * **$known_string** ("string") – Known string

      * **$user_string** ("string") – User-supplied string

   Returns:
      TRUE if the strings match, FALSE otherwise

   Return type:
      "string"

   For more information, please refer to the PHP manual for
   hash_equals().

hash_pbkdf2($algo, $password, $salt, $iterations[, $length = 0[, $raw_output = FALSE]])

   Parameters:
      * **$algo** ("string") – Hashing algorithm

      * **$password** ("string") – Password

      * **$salt** ("string") – Hash salt

      * **$iterations** ("int") – Number of iterations to perform
        during derivation

      * **$length** ("int") – Output string length

      * **$raw_output** ("bool") – Whether to return raw binary data

   Returns:
      Password-derived key or FALSE on failure

   Return type:
      "string"

   For more information, please refer to the PHP manual for
   hash_pbkdf2().


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.


Dependencies
------------

* iconv extension

Important:

  This dependency 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 dependency check on the actual mbstring extension, use
  the "MB_ENABLED" constant.


Function reference
------------------

mb_strlen($str[, $encoding = NULL])

   Parameters:
      * **$str** ("string") – Input string

      * **$encoding** ("string") – Character set

   Returns:
      Number of characters in the input string or FALSE on failure

   Return type:
      "string"

   For more information, please refer to the PHP manual for
   mb_strlen().

mb_strpos($haystack, $needle[, $offset = 0[, $encoding = NULL]])

   Parameters:
      * **$haystack** ("string") – String to search in

      * **$needle** ("string") – Part of string to search for

      * **$offset** ("int") – Search offset

      * **$encoding** ("string") – Character set

   Returns:
      Numeric character position of where $needle was found or FALSE
      if not found

   Return type:
      "mixed"

   For more information, please refer to the PHP manual for
   mb_strpos().

mb_substr($str, $start[, $length = NULL[, $encoding = NULL]])

   Parameters:
      * **$str** ("string") – Input string

      * **$start** ("int") – Position of first character

      * **$length** ("int") – Maximum number of characters

      * **$encoding** ("string") – Character set

   Returns:
      Portion of $str specified by $start and $length or FALSE on
      failure

   Return type:
      "string"

   For more information, please refer to the PHP manual for
   mb_substr().


Standard Functions
==================

This set of compatibility functions offers support for a few standard
functions in PHP that otherwise require a newer PHP version.


Dependencies
------------

* None


Function reference
------------------

array_column(array $array, $column_key[, $index_key = NULL])

   Parameters:
      * **$array** ("array") – Array to fetch results from

      * **$column_key** ("mixed") – Key of the column to return values
        from

      * **$index_key** ("mixed") – Key to use for the returned values

   Returns:
      An array of values representing a single column from the input
      array

   Return type:
      "array"

   For more information, please refer to the PHP manual for
   array_column().

hex2bin($data)

   Parameters:
      * **$data** ("array") – Hexadecimal representation of data

   Returns:
      Binary representation of the given data

   Return type:
      "string"

   For more information, please refer to the PHP manual for hex2bin().
