php-src/UPGRADING.INTERNALS

PHP 8.0 INTERNALS UPGRADE NOTES

1. Internal API changes
  a. Object Handlers API
  b. ZEND_OVERLOADED_FUNCTION and corresponding call_method() object handler
  c. TSRM changes
  d. get() and set() object handlers
  e. zend_parse_parameters 'L' specifier
  f. Arginfo argument types
  g. zend_free_op type and should_free argument of zend_get_zval_ptr()
  h. zend_value_error()
  i. get_closure() object handler
  j. compare_objects() and compare() object handlers
  k. The 'I' length modifier
  l. Some VM instructions switched to IS_TMP_VAR result instead of IS_VAR
  m. All internal functions must have arginfo
  n. zend_hash_sort compare function signature change
  o. cast_object() object handler is now required
  p. ARG_COUNT() macro removed

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

3. Module changes

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

  a. Object Handlers API and some related functions, e.g. zend_call_method() and
     zend_objects_clone_obj() were changed to receive zend_object* instead of
     zval* and zend_string* instead of zval* for property names.

  b. ZEND_OVERLOADED_FUNCTION and corresponding call_method() object handler
     were removed. ZEND_INTERNAL_FUNCTION with ZEND_ACC_CALL_VIA_HANDLER and
     defined "handler" callback should be used instead. This "handler" callback
     should also take care about function cleanup. See ext/zend_test/test.c
     for example.

  c. The following things have been removed from TSRM:
      - TSRMLS_DC
      - TSRMLS_D
      - TSRMLS_CC
      - TSRMLS_C
      - TSRMLS_FETCH
      - TSRMLS_FETCH_FROM_CTX
      - TSRMLS_SET_CTX
      - tsrm_new_interpreter_context
      - tsrm_set_interpreter_context
      - tsrm_free_interpreter_context
      - support for GNUPTH, SGI ST, and BETHREADS

  d. The get() and set() object handlers have been removed. The get() handler
     can generally be replaced with cast_object(). Some uses of set() may be
     replaced by do_operation(). If set() was used to overload direct
     assignments using "=", then this is no longer supported and the
     functionality should be provided in some other way (for example, as
     modification of an object property).

  e. The zend_parse_parameters 'L' specifier and the Z_PARAM_STRICT_LONG()
     family of macros have been removed. Use 'l' and Z_PARAM_LONG() instead,
     which, despite the confusing name, actually have stricter input validation.

  f. Arginfo argument types for internal functions are no longer checked.
     Instead type checks should be performed using the zend_parse_parameters()
     or ZEND_PARSE_PARAMETERS_*() APIs.

  g. zend_free_op type and "should_free" argument of zend_get_zval_ptr() were
     removed. It's possible to get the old "should_free" value using the
     following code.

     zval *ret = zend_get_zval_ptr(opline, opline->op1_type, &opline->op1,
         execute_data, BP_VAR_R);
     zval *should_free = (op_type & (IS_TMP_VAR|IS_VAR)) ? ret : NULL;

  h. Added the zend_value_error() function, which is intended to be used
     to raise ValueError when inappropriate argument values are passed
     to functions.

  i. get_closure() object handlers now accept an additional zend_bool parameter
     `check_only`. If it is true, the handler is called to check whether the
     object is callable; in this case the handler should not throw an exception.

  j. compare_objects() handler was removed. Extensions should use compare() object
     handler instead and check if both arguments are objects and have the same
     compare handler, using ZEND_COMPARE_OBJECTS_FALLBACK() macro.
     
  k. The 'I' length modifier, used to denote 32 and 64bit integer from the custom
     snprintf and spprintf implementations has been removed.
     Use the ZEND_LONG_FMT, ZEND_ULONG_FMT and ZEND_XLONG_FMT macros defined in
     php-src/Zend/zend_long.h

     The 'v' format from the custom snprintf and spprintf implementations has
     been removed. Use the standard 's' format instead.

  l. Some VM instructions switched to IS_TMP_VAR result instead of IS_VAR.
     Actually, all assignments (ZEND_ASSIGN, ZEND_ASSIGN_DIM, ZEND_ASSIGN_OBJ,
     ZEND_ASSIGN_STATIC_PROP), all compound assignments (ZEND_ASSIGN_OP,
     ZEND_ASSIGN_DIM_OP, ZEND_ASSIGN_OBJ_OP, ZEND_ASSIGN_STATIC_PROP_OP) and all
     pre increments/decrements (ZEND_PRE_INC, ZEND_PRE_DEC, ZEND_PRE_INC_OBJ
     ZEND_PRE_DEC_OBJ, ZEND_PRE_INC_STATIC_PROP ZEND_PRE_DEC_STATIC_PROP).

  m. All internal functions and methods are now required to specify arginfo
     information, otherwise warnings will be thrown on startup.

  n. The zend_hash_sort and zend_hash_minmax APIs now accept a comparison
     function with the following signature:

         typedef int (*bucket_compare_func_t)(Bucket *a, Bucket *b);

     Previously compare_func_t was used, which accepted void pointers.

  o. The cast_object() handler is now required, i.e. must be non-null. You can
     indicate that casting is not supported by always returning FAILURE.

  p. The ARG_COUNT() macro has been removed use ZEND_NUM_ARGS() instead.

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

  a. Abstract
    - Symbol HAVE_HASH_EXT is removed and is no longer defined. It should be
      considered to have hash extension always available since PHP 7.4.
    - Symbol HAVE_PCRE is removed and is no longer defined. It should be
      considered to have pcre extension always available since PHP 7.4.
    - Symbol HAVE_LOCALE_H has been removed and is no longer defined.

  b. Unix build system changes

    1.  --enable-maintainer-zts is renamed --enable-zts for parity with Windows
        and as recognition that ZTS is not a "maintainer" or experimental feature.

  c. Windows build system changes

    - The configuration option --enable-crt-debug has been removed. The VC
      debug heap can now be enabled for debug builds by setting the environment
      variable PHP_WIN32_DEBUG_HEAP to a non-negative number before PHP process
      startup.

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