path: root/UPGRADING

PHP 7.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


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

- Core:
  . 'void' can no longer be used as the name of a class, interface, or trait.
    This applies to declarations, class_alias() and use statements.
  . 'iterable' can no longer be used as the name of a class, interface, or
    trait. This applies to declarations, class_alias() and use statements.
    (RFC: https://wiki.php.net/rfc/iterable)
  . (int), intval() where $base is 10 or unspecified, settype(), decbin(),
    decoct(), dechex(), integer operators and other conversions now always
    respect scientific notation in numeric strings.
    (RFC: https://wiki.php.net/rfc/invalid_strings_in_arithmetic)
  . The ASCII 0x7F Delete control character is no longer permitted in unquoted
    identifiers in source code.
  . The following functions may no longer be called dynamically using $func(),
    call_user_func(), array_map() or similar:
     . extract()
     . compact()
     . get_defined_vars()
     . func_get_args()
     . func_get_arg()
     . func_num_args()
     . parse_str() with one argument
     . mb_parse_str() with one argument
     . assert() with a string argument
    (RFC: https://wiki.php.net/rfc/forbid_dynamic_scope_introspection)
  . If the error_log is set to syslog, the PHP error levels are mapped to the
    syslog error levels. This brings finer differentiation in the error logs
    in contrary to the previous approach where all the errors are loggged with
    the notice level only.

- JSON:
  . The serialize_precision is used instead of precision when encoding double
    values.
  . An empty key is decoded as an empty property name instead of using _empty_
    property name when decoding object to stdClass.
  . When calling json_encode with JSON_UNESCAPED_UNICODE option, U+2028 and
    U+2029 are escaped.

========================================
2. New Features
========================================
- Core
  . Added void return type, which requires that a function not return a value.
    (RFC: https://wiki.php.net/rfc/void_return_type)
  . Added iterable pseudo-type accepting any array or object implementing
    Traversable.
    (RFC: https://wiki.php.net/rfc/iterable)
  . String offset access now supports negative references, which will be
    counted from the end of the string.
    (RFC: https://wiki.php.net/rfc/negative-string-offsets)
  . Added a form of the list() construct where keys can be specified.
    (RFC: https://wiki.php.net/rfc/list_keys)
  . Added [] = as alternative construct to list() =.
    (RFC: https://wiki.php.net/rfc/short_list_syntax)
  . Number operators taking numeric strings now emit "A non well formed numeric
    value encountered" E_NOTICEs for leading-numeric strings, and "A
    non-numeric value encountered" E_WARNINGs for non-numeric strings.
    This always applies to the +, -, *, /, **, %, << and >> operators, and
    their assignment counterparts +=, -=, *=, /=, **=, %=, <<= and >>=.
    For the bitwise operators |, & and ^, and their assignment counterparts
    |=, &= and ^=, this only applies where only one operand is a string.
    Note that this never applies to the bitwise NOT operator, ~, which does not
    handle numeric strings, nor to the increment and decrement operators
    ++ and --, which have a unique approach to handling numeric strings.
    (RFC: https://wiki.php.net/rfc/invalid_strings_in_arithmetic)
  . Closure::fromCallable (RFC: https://wiki.php.net/rfc/closurefromcallable)

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

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

========================================
5. Changed Functions
========================================
- get_headers() has an extra parameter which allows passing a custom stream
  context.
- The first $varname argument for getenv() is no longer mandatory, the
  current environment variables will be returned as an associative array
  when omitted.
- json_encode() accepts new option JSON_UNESCAPED_LINE_TERMINATORS that
  disables escaping of U+2028 and U+2029 characters when
  JSON_UNESCAPED_UNICODE is supplied.
- long2ip() accepts integer as parameter now
- pg_last_notice() accepts optional long parameter to specify operation.
  PGSQL_NOTICE_LAST - Get last notice (Default)
  PGSQL_NOTICE_ALL - Get all stored notices
  PGSQL_NOTICE_CLEAR - Remove all stored notices
  It returns empty string or array on successful PGSQL_NOTICE_LAST/ALL calls.
  It returned FALSE for empty notice previously.
- pg_fetch_all() accepts 2nd optional result type parameter like
  pg_fetch_row().
- pg_select() accepts 4th optional result type parameter like pg_fetch_row().
- parse_url() is more restrictive now and supports RFC3986.
- unpack() accepts an additional optional $offset argument. '@' format code
  (that specifes an absolute position) is applyed to input data after
  the $offset argument.
- strpos(), stripos(), substr_count(), grapheme_strpos(), grapheme_stripos(),
  grapheme_extract(), iconv_strpos(), mb_strimwidth(), mb_ereg_search_setpos(),
  mb_strpos() and mb_stripos() now accept negative string offsets.
- substr_count() and mb_strimwidth() additionally also accept negative length.
- file_get_contents() accepts a negative seek offset if the stream is seekable.
- tempnam() throws a notice when failing back to the system temp dir.
- getopt() has an extra by-ref parameter : optind

========================================
6. New Functions
========================================
- Core:
  . Added sapi_windows_cp_set(), sapi_windows_cp_get(), sapi_windows_cp_is_utf8(),
    sapi_windows_cp_conv() for codepage handling.

- pcntl:
  . Added pcntl_signal_get_handler() that returns the current signal handler
    for a particular signal.

- Standard:
  . Added is_iterable() that determines if a value will be accepted by the new
    iterable pseudo-type.

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

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

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

- Date:
  . Invalid serialization data for a DateTime or DatePeriod object will now
    throw an instance of Error from __wakeup() or __set_state() instead of
    resulting in a fatal error.
  . Timezone initialization failure from serialized data will now throw an
    instance of Error from __wakeup() or __set_state() instead of resulting in
    a fatal error.

- DBA:
  . Data modification functions (e.g.: dba_insert()) now throw an instance of
    Error instead of triggering a catchable fatal error if the key is does not
    contain exactly two elements.

- DOM:
  . Invalid schema or RelaxNG validation contexts will throw an instance of
    Error instead of resulting in a fatal error.
  . Attempting to register a node class that does not extend the appropriate
    base class will now throw an instance of Error instead of resulting in a
    fatal error.
  . Attempting to read an invalid or write to a readonly property will throw
    an instance of Error instead of resulting in a fatal error.

- GD:
  . Changed the default of the ini setting gd.jpeg_ignore_warning to 1.

- IMAP:
  . An email address longer than 16385 bytes will throw an instance of Error
    instead of resulting in a fatal error.
    
- Intl:
  . Failure to call the parent constructor in a class extending Collator
    before invoking the parent methods will throw an instance of Error
    instead of resulting in a recoverable fatal error.
  . Cloning a Transliterator object may will now throw an instance of Error
    instead of resulting in a fatal error if cloning the internal
    transliterator fails.

- LDAP:
  . Providing an unknown modification type to ldap_batch_modify() will now
    throw an instance of Error instead of resulting in a fatal error.

- Mbstring:
  . mb_ereg() and mb_eregi() will now throw an instance of ParseError if an
    invalid PHP expression is provided and the 'e' option is used.

- Mcrypt:
  . mcrypt_encrypt() and mcrypt_decrypt() will throw an instance of Error
    instead of resulting in a fatal error if mcrypt cannot be initialized.

- Mysqli:
  . Attempting to read an invalid or write to a readonly property will throw
    an instance of Error instead of resulting in a fatal error.

- Reflection:
  . Failure to retrieve a reflection object or retrieve an object property
    will now throw an instance of Error instead of resulting in a fatal error.

- Session:
  . Custom session handlers that do not return strings for session IDs will 
    now throw an instance of Error instead of resulting in a fatal error
    when a function is called that must generate a session ID.
  . An invalid setting for session.hash_function will throw an instance of
    Error instead of resulting in a fatal error when a session ID is created.

- SimpleXML:
  . Creating an unnamed or duplicate attribute will throw an instance of Error
    instead of resulting in a fatal error.

- SPL:
  . Attempting to clone an SplDirectory object will throw an instance of Error
    instead of resulting in a fatal error.
  . Calling ArrayIterator::append() when iterating over an object will throw an
    instance of Error instead of resulting in a fatal error.

- SQLite3:
  . Upgraded bundled SQLite lib to 3.13.0

- Standard:
  . assert() will throw a ParseError when evaluating a string given as the first
    argument if the PHP code is invalid instead of resulting in a catchable
    fatal error.
  . Calling forward_static_call() outside of a class scope will now throw an
    instance of Error instead of resulting in a fatal error.

- Tidy:
  . Creating a tidyNode manually will now throw an instance of Error instead of
    resulting in a fatal error.

- WDDX:
  . A circular reference when serializing will now throw an instance of Error
    instead of resulting in a fatal error.

- XML-RPC:
  . A circular reference when serializing will now throw an instance of Error
    instead of resulting in a fatal error.

- Zip:
  . ZipArchive::addGlob() will throw an instance of Error instead of resulting
    in a fatal error if glob support is not available.

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

- Core:
  . PHP_FD_SETSIZE

- JSON:
  . JSON_UNESCAPED_LINE_TERMINATORS

- Pgsql:
  PGSQL_NOTICE_LAST
  PGSQL_NOTICE_ALL
  PGSQL_NOTICE_CLEAR

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

- serialize_precision
  . If the value is set to -1, then the dtoa mode 0 is used. The value -1
    is now used by default.

- precision
  . If the value is set to -1, then the dtoa mode 0 is used. No changes
    in default value which is still 14.

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

- Core:
  . Support for long and UTF-8 path;

    If an application is UTF-8 conform, no further action is required. For
    applications depending on paths in non UTF-8 encodings for I/O, an explicit
    INI directive has to be set. The encoding INI settings check relies on the
    order in the core:
      - internal_encoding
      - default_charset
      - zend.multibyte

    Several functions for codepage handling were itroduced:
      - sapi_windows_cp_set() to set the default codepage
      - sapi_windows_cp_get() to retrieve the current codepage
      - sapi_windows_cp_is_utf8()
      - sapi_windows_cp_conv() to convert between codepages, using iconv()
        compatible signature
    These functions are thread safe.

    The console output codepage is adjusted depending on the encoding used in
    PHP. Depending on the concrete system OEM codepage, the visible output
    might or might be not correct. For example, in the default cmd.exe and on
    a system with the OEM codepage 437, outputs in codepages 1251, 1252, 1253
    and some others can be shown correctly when using UTF-8. On the same system,
    chars in codepage like 20932 probably won't be shown correctly. This refers
    to the particular system rules for codepage, font compatibility and the
    particular console program used. PHP automatically sets the console codepage
    according to the encoding rules from php.ini. Using alternative consoles
    instead of cmd.exe directly might bring better experience in some cases.

    As a result of UTF-8 support in the streams, PHP scripts are not limited
    to ASCII or ANSI filenames anymore. This is supported out of the box on
    CLI. For other SAPI, the documentation for the corresponding server
    is useful.

    Long paths support is transparent. Paths longer than 260 bytes get
    automatically prefixed with \\?\. The max path length is limited to
    2048 bytes. Be aware, that the path segment limit (basename length) still
    persists.

    The recommended way to handle file paths, I/O and other related topics is
    by utilizing UTF-8.

  . Support for ftok()

- FCGI
  . PHP_FCGI_CHILDREN is respected. If this environment variable is defined,
    the first php-fcgi.exe process will exec the specified number of children.
    Those will share the same TCP socket. 

- readline:
  . The readline extension is supported through the WinEditLine library
    (http://mingweditline.sourceforge.net/). Thereby, the interactive CLI
    shell is supported as well (php.exe -a).

    It is well known, but nevertheless is worth mentioning again, that
    the readline extension is not thread safe and will never be. Thus,
    the usage of it with any true thread safe SAPI (like Apache mod_winnt) is
    strongely discouraged.

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