$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

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.

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

  a. Unix build system changes
    - 

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