php-src/UPGRADING.INTERNALS

$Id$

UPGRADE NOTES - PHP X.Y

1. Internal API changes
  a. Addition of do_operation and compare object handlers
  b. return_value_ptr now always available, RETVAL_ZVAL_FAST macros
  c. POST data handling
  d. Arginfo changes
  e. tsrm_virtual_cwd.h moved to zend_virtual_cwd.h
  f. empty strings are interned
  g. Additional str_* APIs
  h. Addition of zend_hash_reindex
  i. Addition of zend_hash_splice
  j. An additional parameter is sent to Countable::count()
  k. Unserialization of manipulated object strings
  l. Removal of IS_CONSTANT_ARRAY and IS_CONSTANT_INDEX hack

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


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

  a. Addition of do_operation and compare object handlers

  Two new object handlers have been added:

    do_operation:
    typedef int (*zend_object_do_operation_t)(
        zend_uchar opcode, zval *result, zval *op1, zval *op2 TSRMLS_DC
    );

    compare:
    typedef int (*zend_object_compare_zvals_t)(
        zval *result, zval *op1, zval *op2 TSRMLS_DC
    );

  The first handler is used to overload arithmetic operations. The first
  argument specifies the opcode of the operator, result is the target zval,
  op1 the first operand and op2 the second operand. For unary operations
  op2 is NULL. If the handler returns FAILURE PHP falls back to the default
  behavior for the operation.

  The second handler is used to perform comparison operations with
  non-objects. The value written into result must be an IS_LONG with value
  -1 (smaller), 0 (equal) or 1 (greater). The return value is a SUCCESS/FAILURE
  return code. The difference between this handler and compare_objects is
  that it will be triggered for comparisons with non-objects and objects of
  different types. It takes precedence over compare_objects.

  Further docs in the RFC: https://wiki.php.net/rfc/operator_overloading_gmp

  b. return_value_ptr now always available, RETVAL_ZVAL_FAST macros

  The return_value_ptr argument to internal functions is now always set.
  Previously it was only available for functions returning by-reference.
  return_value_ptr can now be used to return zvals without copying them.
  For this purpose two new macros are provided:

      RETVAL_ZVAL_FAST(zv); /* analog to RETVAL_ZVAL(zv, 1, 0) */
      RETURN_ZVAL_FAST(zv); /* analog to RETURN_ZVAL(zv, 1, 0) */

  The macros behave similarly to the non-FAST variants with copy=1 and
  dtor=0, but will try to return the zval without making a copy by utilizing
  return_value_ptr.
  
  c. POST data handling
  
  The sapi_request_info's members post_data, post_data_len and raw_post_data as 
  well as raw_post_data_len have been replaced with a temp PHP stream 
  request_body.
  
  The recommended way to access raw POST data is to open and use a php://input 
  stream wrapper.  It is safe to be used concurrently and more than once. 

  d. Arginfo changes

  The pass_rest_by_reference argument of the ZEND_BEGIN_ARG_INFO and
  ZEND_BEGIN_ARG_INFO_EX() is no longer used. The value passed to it is ignored.

  Instead a variadic argument is created using ZEND_ARG_VARIADIC_INFO():

      ZEND_ARG_VARIADIC_INFO(0, name) /* pass rest by value */
      ZEND_ARG_VARIADIC_INFO(1, name) /* pass rest by reference */
      ZEND_ARG_VARIADIC_INFO(ZEND_SEND_PREFER_REF, name)
          /* pass rest by prefer-ref */

  ZEND_ARG_VARIADIC_INFO() should only be used for the last argument.

  The following changes were applied to the zend_arg_info struct:

       typedef struct _zend_arg_info {
           const char *class_name;
           zend_uint class_name_len;
           zend_uchar type_hint;
      +    zend_uchar pass_by_reference;
           zend_bool allow_null;
      -    zend_bool pass_by_reference;
      +    zend_bool is_variadic;
       } zend_arg_info;

  The following changes were applied to the zend_internal_function_info struct:

       typedef struct _zend_internal_function_info {
           zend_uint required_num_args;
           zend_uchar _type_hint;
           zend_bool return_reference;
      -    zend_bool pass_rest_by_reference;
      +    zend_bool _allow_null;
      +    zend_bool _is_variadic;
       } zend_internal_function_info;

  The CHECK_ARG_SEND_TYPE(), ARG_MUST_BE_SENT_BY_REF(),
  ARG_SHOULD_BE_SENT_BY_REF() and ARG_MAY_BE_SENT_BY_REF() macros now assume
  that the argument passed to them is a zend_function* and that it is non-NULL.

  e. tsrm_virtual_cwd.h moved to zend_virtual_cwd.h

  Memory allocation is now managed by emalloc/efree instead of malloc/free.

  f. empty strings are interned

  String created using STR_EMPTY_ALLOC() are now interned.
  convert_to_string use STR_EMPTY_ALLOC() for zval when IS_NULL.
  str_efree() shoud be preferred as efree() on such strings can cause memory
  corruption.

  g. Additional str_* APIs

  In addition to the previously existing str_free() and str_efree() macros, the
  following macros have been introduced to simplify dealing with potentially
  interned strings:

      str_efree_rel(str)         - efree_rel() if not interned
      str_erealloc(str, new_len) - erealloc() or emalloc+memcpy if interned
      str_estrndup(str, len)     - estrndup() if not interned
      str_strndup(str, len)      - zend_strndup() if not interned
      str_hash(str, len)         - INTERNED_HASH(str) if interned,
                                   zend_hash_func(str, len+1) otherwise

  h. Addition of zend_hash_reindex

  A zend_hash_reindex() function with the following prototype has been added:

      void zend_hash_reindex(HashTable *ht, zend_bool only_integer_keys);

  If only_integer_keys==0, this function will change all keys to be continuous,
  zero-based integers in hash order. If only_integer_keys==1 the same will be
  done only for keys that were already integers previously, while leaving
  string keys alone.

  i. Addition of zend_hash_splice

  A zend_hash_splice() macro with the following prototype has been added:

      void zend_hash_splice(
          HashTable *ht, uint nDataSize, copy_ctor_func_t pCopyConstructor,
          uint offset, uint length,
          void **list, uint list_count, HashTable *removed
      );

  This function performs an in-place splice operation on a hashtable:

  The elements between offset and offset+length are removed and the elements in
  list[list_count] are inserted in their place. The removed elements can be
  optionally collected into a hashtable.

  This operation reindexes the hashtable, i.e. integer keys will be zero-based
  and sequential, while string keys stay intact. The same applies to the
  elements inserted into the removed HT.

  As a side-effect of this addition the signature of the php_splice() function
  changed:

      void php_splice(
          HashTable *ht, zend_uint offset, zend_uint length,
          zval ***list, zend_uint list_count, HashTable *removed TSRMLS_DC
      )
  
  This function now directly forwards to zend_hash_splice(), resets the
  IAP of ht (for compatibility with the previous implementation) and resets
  CVs if the passed hashtable is the global symbol table.

  j. An additional parameter is sent to Countable::count()

  That parameter denotes the $mode passed to count; it shouldn't affect any
  userland code, but any zend_parse_parameters() used with no arguments should
  fail. Extensions which implement Countable internally, need to accept one
  optional long as parameter.

  k. Unserialization of manipulated object strings

  Strings requiring unserialization of objects are now explicitly checked
  whether the object they contain implements the Serializable interface.
  This solves the situation where manipulated strings could be passed for
  objects using Serializable to disallow serialization. An object
  implementing Serializable will always start with "C:" in the serialized
  string, all other objects are represented with starting "O:". Objects
  implementing Serializable to disable serialization using
  zend_class_unserialize_deny and zend_class_serialize_deny, when
  instantiated from the serializer with a manipulated "O:" string at the
  start, will most likely be defectively initialized. This is now
  fixed at the appropriate place by checking for the presence of the
  serialize callback in the class entry.

  l. Removal of IS_CONSTANT_ARRAY and IS_CONSTANT_INDEX hack

  These two #defines disappeared. Instead we have now IS_CONSTANT_AST which
  covers also the functionality IS_CONSTANT_ARRAY bid and furthermore the
  hack for marking zvals as constant index with IS_CONSTANT_INDEX is now
  superfluous and so removed.
  Please note that IS_CONSTANT_AST now has the same value than
  IS_CONSTANT_ARRAY had.

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

  a. Unix build system changes
    - The bison version check is now a blacklist instead of a whitelist.
    - The bison binary can be specified through the YACC environment/configure
      variable. Previously `bison` was assumed to be in $PATH. 

  b. Windows build system changes
    - The configure option --enable-static-analyze isn't available anymore.
      The new option was introduced --with-analyzer.
    - It is possible to disable PGO for single extensions, to do that
      define a global variable PHP_MYMODULE_PGO evaluating to false
      inside config.w32