php-src/UPGRADING

PHP 8.1 UPGRADE NOTES

1. Backward Incompatible Changes
2. New Features
3. Changes in SAPI modules
4. Deprecated Functionality
5. Changed Functions
6. New Functions
7. New Classes and Interfaces
8. Removed Extensions and SAPIs
9. Other Changes to Extensions
10. New Global Constants
11. Changes to INI File Handling
12. Windows Support
13. Other Changes
14. Performance Improvements

========================================
1. Backward Incompatible Changes
========================================

- Fileinfo:
  . The fileinfo functions now accept and return, respectively, finfo objects
    instead of resources.

- IMAP:
  . The IMAP functions now accept and return, respectively, IMAPConnection objects
    instead of resources.

- MySQLi:
  . mysqli_fetch_fields() and mysqli_fetch_field_direct() will now always return
    zero for max_length. You can compute this information by iterating over the
    result set and taking the maximum length. This is what PHP was doing
    internally previously.
  . The MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH option no longer has an effect.
  . The MYSQLI_STORE_RESULT_COPY_DATA option no longer has an effect.

- MySQLnd:
  . The mysqlnd.fetch_copy_data ini setting has been removed. However, this
    should not result in user-visible behavior changes.

- PDO:
  . PDO::ATTR_STRINGIFY_FETCHES now also stringifies values of type bool to
    "0" or "1". Previously booleans were not stringified.
  . Calling bindColumn() with PDO::PARAM_LOB (and assuming stringification is
    not enabled) will now consistently bind a stream result, as documented.
    Previously the result would be either a stream or a string depending on the
    used database driver and the time the binding is performed.

- PDO MySQL:
  . Integers and floats in result sets will now be returned using native PHP
    types instead of strings when using emulated prepared statements. This
    matches the behavior of native prepared statements. You can restore the
    previous behavior by enabling the PDO::ATTR_STRINGIFY_FETCHES option.

- Standard:
  . version_compare() no longer accepts undocumented operator abbreviations.

========================================
2. New Features
========================================

- hash:
  . The following functions have changed signatures:

    - function hash(string $algo, string $data, bool $binary = false, array $options = []): string|false {}
    - function hash_file(string $algo, string $filename, bool $binary = false, array $options = []): string|false {}
    - function hash_init(string $algo, int $flags = 0, string $key = "", array $options = []): HashContext {}

    The additional `$options` argument can be used to pass algorithm specific data.

  . Added MurmurHash3 with streaming support. The following variants are implemented:

    - murmur3a, 32-bit hash
    - murmur3c, 128-bit hash for x86
    - murmur3f, 128-bit hash for x64

    The initial hash state can be passed through the `seed` key in the `$options` array, for example:

    ```php
    $h = hash("murmur3f", $data, options: ["seed" => 42]);
    echo $h, "\n";
    ```

    A valid seed value is within the range from 0 to the plaform defined UINT_MAX, usually 4294967295.

========================================
3. Changes in SAPI modules
========================================

========================================
4. Deprecated Functionality
========================================

========================================
5. Changed Functions
========================================

========================================
6. New Functions
========================================

========================================
7. New Classes and Interfaces
========================================

========================================
8. Removed Extensions and SAPIs
========================================

========================================
9. Other Changes to Extensions
========================================

- MySQLi:
  . The mysqli_stmt::next_result() and mysqli::fetch_all() methods are now
    available when linking against libmysqlclient.

- OpenSSL:
  . The OpenSSL extension now requires at least OpenSSL version 1.0.2.

- Standard:
  . --with-password-argon2 now uses pkg-config to detect libargon2. As such,
    an alternative libargon2 location should now be specified using
    PKG_CONFIG_PATH.

========================================
10. New Global Constants
========================================

========================================
11. Changes to INI File Handling
========================================

========================================
12. Windows Support
========================================

. The macro IGNORE_URL_WIN has been removed; it had no effect as of PHP 5.0.0.

========================================
13. Other Changes
========================================

========================================
14. Performance Improvements
========================================