php-src/UPGRADING.INTERNALS

$Id$

UPGRADE NOTES - PHP X.Y

1. Internal API changes
  a. Executor changes
  b. Streams pooling API
  c. Lowercasing and locales
  d. zend_qsort_r
  e. get_current_key
  f. unserialization of manipulated object strings

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


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

	a. Executor changes

 * extensions can't override zend_execute() any more, they should override
   zend_execute_ex() instead. The EG(current_execute_data) is already
   initialized in zend_execute_ex(), so for compatibility extensions
   may need to use EG(current_execute_data)->prev_execute_data instead.
 * removed EG(arg_types_stack), EX(fbc), EX(called_scope), EX(current_object)
 * added op_array->nested_calls. It's calculated at compile time.
 * added EX(call_slots). It is an array to store information about syntaticaly
   nested calls (e.g. foo(bar())). It's preallocated together with execute_data.
 * added EX(call) - pointer to a current calling function. Actually an
   element of EX(call_slots)
 * opcodes INIT_METHOD_CALL, ZEND_INIT_STATIC_METHOD_CALL,
   ZEND_INIT_FCALL_BY_NAME, ZEND_INIT_NS_FCALL_BY_NAME use result.num as
   an index in EX(call_slots)
 * opcode ZEND_NEW uses extended_vallue as an index in EX(call_slots)
 * opcoes ZEND_DO_FCALL and ZEND_DO_FCALL_BY_NAME use op2.num as
   an index in EX(call_slots)
 * added op_array->used_stack. It's calculated at compile time and the
   corresponding stack space is preallocated together with execute_data.
   ZEND_SEND* and ZEND_DO_FCALL* don't need to check for stack overflow
   anymore.
 * Removed execute_data->Ts field. The VM temporary variables always allocated
   immediately before execute_data structure. Now they are accessed by offset
   from the execute_data base pointer (instead of execute_data->Ts). Compiler
   stores new offsets in op_array->opcodes[*].op?.num. You can use macros
   EX_TMP_VAR() and EX_TMP_VAR_NUM() to access temp_variable by offset or
   number. You can convert number to offset using EX_TMP_VAR_NUM(0, num) or
   offset to number (EX_TMP_VAR_NUM(0,0)-EX_TMP_VAR(0,offset)).
 * Removed execute_data->CVs field. The VM compiled variables always allocated
   immediately after execute_data structure. Now they are accessed by offset
   from the execute_data base pointer (instead of execute_data->CVs). You can
   use macros EX_CV_NUM() to access compiled variables by number.

	b. Streams pooling API

The streams pooling API has been removed. The following functions no longer
exist:

PHPAPI int php_stream_context_get_link(php_stream_context *context,
		const char *hostent, php_stream **stream);
PHPAPI int php_stream_context_set_link(php_stream_context *context,
		const char *hostent, php_stream *stream);
PHPAPI int php_stream_context_del_link(php_stream_context *context,
		php_stream *stream);

	c. Lowercasing and locales

The lowercasing functions in zend_operators.c were split into those that do 
lowercasing according to locale rules and those that do ASCII lowercasing.
ASCII:

                zend_str_tolower_copy
                zend_str_tolower_dup
                zend_str_tolower
                zend_binary_strcasecmp
                zend_binary_strncasecmp

Locale-based:
                zend_binary_strncasecmp_l
                zend_binary_strcasecmp_l
                zend_binary_zval_strcasecmp
                zend_binary_zval_strncasecmp
                string_compare_function_ex
                string_case_compare_function

Internal engine lowercasing will be using ASCII-only rules. User-facing functions,
such as strcasecmp, will be using locale rules. 

Two new functions - zend_binary_strncasecmp_l and zend_binary_strcasecmp_l - added as 
locale-based counterparts to zend_binary_strcasecmp and zend_binary_strncasecmp.

	d. zend_qsort_r

Added the function zend_qsort_r():

typedef int  (*compare_r_func_t)(const void *, const void * TSRMLS_DC, void *);
void zend_qsort_r(void *base, size_t nmemb, size_t siz, compare_r_func_t compare, void *arg TSRMLS_DC);

The extra argument it has (relatively to zend_qsort()) is passed to the
comparison function.

	e. get_current_key

The signature of the get_current_key iteration handler has been changed to:

void (*get_current_key)(zend_object_iterator *iter, zval *key TSRMLS_DC);

The key should be written into the zval* using the ZVAL_* macros.

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

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

  a. Unix build system changes
    - 

  b. Windows build system changes
    - Drop Windows XP and 2003 support.