php-src/UPGRADING.INTERNALS

PHP 7.2 INTERNALS UPGRADE NOTES

1. Internal API changes
  a. Path related functions
  b. php_win32_get_random_bytes()
  c. nice() Windows implementation
  d. ZEND_ACC_CLONE removed
  e. IS_TYPE_IMMUTABLE removed
  f. zend_arg_info.class_name removed
  g. ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX changed
  h. valid_symbol_table removed
  i. array_init() and array_init_size()
  j. Run-time constant operand addressing
  k. Array/Object recursion protection
  l. HASH_FLAG_PERSISTENT
  m. AST and IS_CONSTANT

2. Build system changes
  a. Unix build system changes
  b. Windows build system changes


3. Module changes

========================
1. Internal API changes
========================

  a. Path related functions
    - CWD_API void realpath_cache_del(const char *path, size_t path_len);
    - CWD_API realpath_cache_bucket* realpath_cache_lookup(const char *path, size_t path_len, time_t t);
    - PHPAPI void php_clear_stat_cache(zend_bool clear_realpath_cache, const char *filename, size_t filename_len);
    - PHPAPI void php_stat(const char *filename, size_t filename_length, int type, zval *return_value);

  b. php_win32_get_random_bytes()
    The internal randomness source on Windows switched to use CNG API.

  c. nice() now have a Windows alternative that is implemented in win32/nice.c, using
	   SetPriorityClass(). See the implementation for more in-depth details. This also 
	   defines HAVE_NICE.

  d. ZEND_ACC_CLONE is removed, but was not used in previous versions

  e. IS_TYPE_IMMUTABLE is removed, IS_TYPE_COPYABLE can be used instead
     Z_IMMUTABLE() check function is still available

  f. zend_arg_info class_name member is removed, use ZEND_TYPE_NAME instead

  g. ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX classname option is removed
     use ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX for simple type
     use ZEND_BEGIN_ARG_WITH_RETURN_OBJ_INFO_EX for object

  h. valid_symbol_table is removed from executor_globals.
     Use EG(active) instead of removed EG(valid_symbol_table)

  i. array_init() and array_init_size() are not functions anymore.
     They don't return any values.

  j. In 64-bit builds PHP-7.2 and below used relative run-time constant operand
     addressing. E.g. opline->op1.constant kept an offset from start of literals
     table - op_array->literals. To speedup access op_array->literals was cached
     in execute_data->literals. So the resulting address calculated as
     EX(literals) + opline->op1.constant.

     Now at run-time literals allocated close to opcodes, and addressed
     relatively from current opline. This eliminates load of EX(literals) on
     each constant access as well as EX(literals) initialization on each call.

     As result some related macros were removed (ZEND_EX_USE_LITERALS,
     EX_LOAD_LITERALS, EX_LITERALS, RT_CONSTANT_EX, EX_CONSTANT) or changed
     (RT_CONSTANT, ZEND_PASS_TWO_UPDATE_CONSTANT, ZEND_PASS_TWO_UNDO_CONSTANT).
     This change way affect only some "system" extensions. EX_LITERALS,
     RT_CONSTANT_EX, EX_CONSTANT should be substituted by RT_CONSTANT than now
     use "opline" (instead of "op_array") as first argument.

  k. Protection from recursion during processing circular data structures was
     refactored. HashTable.nApplyCount and IS_OBJ_APPLY_COUNT are replaced by
     single flag GC_PROTECTED. Corresponding macros Z_OBJ_APPLY_COUNT,
     Z_OBJ_INC_APPLY_COUNT, Z_OBJ_DEC_APPLY_COUNT, ZEND_HASH_GET_APPLY_COUNT,
     ZEND_HASH_INC_APPLY_COUNT, ZEND_HASH_DEC_APPLY_COUNT are replaced with
     GC_IS_RECURSIVE, GC_PROTECT_RECURSION, GC_UNPROTECT_RECURSION,
     Z_IS_RECURSIVE, Z_PROTECT_RECURSION, Z_UNPROTECT_RECURSION.

     HASH_FLAG_APPLY_PROTECTION flag and ZEND_HASH_APPLY_PROTECTION() macro
     are removed. All mutable arrays should use recursion protection.
     Corresponding checks should be replaced by Z_REFCOUNTED() or
     !(GC_GLAGS(p) & GC_IMMUTABLE).

  l. HASH_FLAG_PERSISTENT renamed into IS_ARRAY_PERSISTENT and moved into
     GC_FLAGS (to be consistent with IS_STR_PERSISTENT).

  m. zend_ast_ref structure is changed to use only one allocation.
     zend_ast_copy() now returns zend_ast_ref (instead of zend_asr).
     zend_ast_destroy_and_free() is removed. ZVAL_NEW_AST() is replaced
     by ZVAL_AST().

     IS_CONSTANT type and Z_CONST_FLAGS() are removed. Now constants are always
     represented using IS_CONSTANT_AST (ZEND_AST_CONSTANT kind). AST node
     attributes are used instead of constant flags. IS_TYPE_CONSTANT flag is
     removed, but Z_CONSTANT() macro is kept for compatibility.

========================
2. Build system changes
========================

  a. Unix build system changes

  b. Windows build system changes

    .  Minimum supported Windows versions are Windows 7/Server 2008 R2.
    . --enable-one-shot configure option is removed, --with-mp is usable.
    . The new binary tools SDK is required for Windows builds, the
      documentation is available under https://wiki.php.net/internals/windows/stepbystepbuild_sdk_2
    . Visual Studio 2017 is utilized for the Windows builds
    . Clang build with ASAN is supported with clang 5+

========================
3. Module changes
========================

- Pcre:
  . php_pcre_replace and php_pcre_replace_impl expect a zend_string instead of a zval and
    is_callable_replace options is removed:
    - PHPAPI zend_string *php_pcre_replace(zend_string *regex, zend_string *subject_str, char *subject, int subject_len, zend_string *replace_str, int limit, int *replace_count);
    - PHPAPI zend_string *php_pcre_replace_impl(pcre_cache_entry *pce, zend_string *subject_str, char *subject, int subject_len, zend_string *replace_str, int limit, int *replace_count);

- Session:
  . php_session_start()/session_reset_id() return value is changed from void to int.
    It returns SUCCESS/FAILURE.
  . Session module manages session status correctly.

- OpenSSL:
  . Windows builds ship with OpenSSL 1.1 by default, lower versions are still supported with custom deps.