release/src/router/php/UPGRADING.INTERNALS

   1 $Id$
   2
   3 UPGRADE NOTES - PHP X.Y
   4
   5 1. Internal API changes
   6   a. virtual_file_ex
   7   b. stat/lstat support
   8   c. readlink support
   9   d. layout of some core ZE structures (zend_op_array, zend_class_entry, ...)
  10   e. Zend\zend_fast_cache.h has been removed
  11   f. streams that enclose private streams
  12   g. leak_variable
  13   h. API Signature changes
  14   i. new TSRM function expand_filepath_with_mode
  15
  16 2. Build system changes
  17   a. Unix build system changes
  18   b. Windows build system changes
  19
  20
  21 ========================
  22 1. Internal API changes
  23 ========================
  24
  25         a. virtual_file_ex
  26
  27 virtual_file_ex takes now a TSRM context as last parameter:
  28 CWD_API int virtual_file_ex(cwd_state *state, const char *path,
  29  verify_path_func verify_path, int use_realpath TSRLS_DC);
  30
  31
  32         b. stat/lstat support
  33
  34 lstat is now available on all platforms. On unix-like platform
  35 php_sys_lstat is an alias to lstat (when avaible). On Windows it is now
  36 available using php_sys_lstat. php_sys_stat and php_sys_lstat usage is recommended
  37 instead of calling lstat directly, to ensure portability.
  38
  39
  40         c. readlink support
  41
  42 readlink is now available on all platforms. On unix-like platform
  43 php_sys_readlink is an alias to readlink (when avaible). On Windows it is now
  44 available using php_sys_readlink. php_sys_readlink usage is recommended
  45 instead of calling readlink directly, to ensure portability.
  46
  47
  48         d. layout of some core ZE structures (zend_op_array, zend_class_entry, ...)
  49
  50 . zend_function.pass_rest_by_reference is replaced by
  51   ZEND_ACC_PASS_REST_BY_REFERENCE in zend_function.fn_flags
  52 . zend_function.return_reference is replaced by ZEND_ACC_RETURN_REFERENCE
  53   in zend_function.fn_flags
  54 . zend_arg_info.required_num_args removed. it was needed only for internal
  55   functions. Now the first arg_info for internal function (which has special
  56   meaning) is represented by zend_internal_function_info structure.
  57 . zend_op_array.size, size_var, size_literal, current_brk_cont,
  58   backpatch_count moved into CG(context), because they are used only during
  59   compilation.
  60 . zend_op_array.start_op is moved into EG(start_op), because it's used
  61   only for 'interactive' execution of single top-level op-array.
  62 . zend_op_array.done_pass_two is replaced by ZEND_ACC_DONE_PASS_TWO in
  63   zend_op_array.fn_flags.
  64 . op_array.vars array is trimmed (reallocated) during pass_two.
  65 . zend_class_entry.constants_updated is replaced by
  66   ZEND_ACC_CONSTANTS_UPDATED in zend_class_entry.ce_flags
  67 . the size of zend_class_entry is reduced by sharing the same memory space
  68   by different information for internal and user classes.
  69   See zend_class_inttry.info union.
  70
  71
  72         e. Zend\zend_fast_cache.h
  73
  74 It should not have been used anymore since php5, but now this header has
  75 been removed. The following macros are not available anymore:
  76
  77 ZEND_FAST_ALLOC(p, type, fc_type)
  78 ZEND_FAST_FREE(p, fc_type)
  79 ZEND_FAST_ALLOC_REL(p, type, fc_type)
  80 ZEND_FAST_FREE_REL(p, fc_type)
  81
  82 Use emalloc, emalloc_rel, efree or efree_rel instead.
  83
  84
  85         f. Streams that enclose private streams
  86
  87 Some streams, like the temp:// stream, may enclose private streams. If the
  88 outer stream leaks due to a programming error or is not exposed through a
  89 zval (and therefore is not deleted when all the zvals are gone), it will
  90 be destroyed on shutdown.
  91 The problem is that the outer usually wants itself to close the inner stream,
  92 so that it may do any other shutdown action that requires the inner stream to
  93 be live (e.g. commit data to it). If the outer stream is exposed through a
  94 zval and the inner one isn't, this is not a problem because the outer stream
  95 will be freed when the zval is destroyed, which happens before the resources
  96 are destroyed on shutdown.
  97 On resource list shutdown, the cleanup happens in reverse order of resource
  98 creation, so if the inner stream was created in the opener of the outer stream,
  99 it will be destroyed first.
 100 The following functions were added to the streams API to force a predictable
 101 destruction order:
 102
 103 PHPAPI php_stream *php_stream_encloses(php_stream *enclosing, php_stream *enclosed);
 104 #define php_stream_free_enclosed(stream_enclosed, close_options)
 105 PHPAPI int _php_stream_free_enclosed(php_stream *stream_enclosed, int close_options TSRMLS_DC);
 106
 107 Additionally, the following member was added to php_stream:
 108
 109         struct _php_stream *enclosing_stream;
 110
 111 and the following macro was added:
 112
 113 #define PHP_STREAM_FREE_IGNORE_ENCLOSING        32
 114
 115 The function php_stream_encloses declares the first stream encloses the second.
 116 This has the effect that, when the inner stream is closed from a resource
 117 destructor it will abort and try to free its enclosing stream instead.
 118 To prevent this from happening when the inner stream is freed from the outer
 119 stream, the macro php_stream_free_enclosed should be used instead of
 120 php_stream_free/php_stream_close/php_stream_pclose, or the flag
 121 PHP_STREAM_FREE_IGNORE_ENCLOSING should be directly passed to php_stream_free.
 122 The outer stream cannot abstain, in its close callback, from closing the inner
 123 stream or clear the enclosing_stream pointer in its enclosed stream by calling
 124 php_stream_encloses with the 2nd argument NULL. If this is not done, there will
 125 be problems, so observe this requirement when using php_stream_encloses.
 126
 127
 128         g. leak_variable
 129
 130 The function leak_variable(variable [, leak_data]) was added. It is only
 131 available on debug builds. It increments the refcount of a zval or, if the
 132 second argument is true and the variable is either an object or a resource
 133 it increments the refcounts of those objects instead.
 134
 135
 136         h. API Signature changes
 137
 138 . zend_list_insert
 139   ZEND_API int zend_list_insert(void *ptr, int type TSRMLS_DC);
 140   call: zend_list_insert(a, SOMETYPE TSRMLS_CC);
 141   NB: If zend_list_insert is used to register a resource,
 142   ZEND_REGISTER_RESOURCE could be used instead.
 143
 144 . php_le_stream_context(TSRMLS_C)
 145   PHPAPI php_stream_context *php_stream_context_alloc(TSRMLS_D)
 146   call: context  = php_stream_context_alloc(TSRMLS_C);
 147
 148 . php_stream_context_alloc
 149   PHPAPI php_stream_context *php_stream_context_alloc(TSRMLS_D);
 150   call: context  = php_stream_context_alloc(TSRMLS_C);
 151
 152 . sapi_get_request_time(TSRMLS_D);
 153   SAPI_API double sapi_get_request_time(TSRMLS_D);
 154
 155 . sapi_register_default_post_reader
 156   SAPI_API int sapi_register_default_post_reader(void (*default_post_reader)(TSRMLS_D) TSRMLS_DC);
 157
 158 . sapi_register_treat_data
 159   SAPI_API int sapi_register_treat_data(void (*treat_data)(int arg, char *str, zval *destArray TSRMLS_DC) TSRMLS_DC);
 160
 161 . sapi_register_input_filter
 162   SAPI_API int sapi_register_input_filter(unsigned int (*input_filter)(int arg, char *var, char **val, unsigned int val_len, unsigned int *new_val_len TSRMLS_DC), unsigned int (*input_filter_init)(TSRMLS_D) TSRMLS_DC);
 163
 164 . tsrm_win32_access
 165   TSRM_API int tsrm_win32_access(const char *pathname, int mode TSRMLS_DC);
 166
 167 . popen_ex (win32)
 168   TSRM_API FILE *popen_ex(const char *command, const char *type, const char *cwd, char *env TSRMLS_DC);
 169
 170 . php_get_current_user
 171   PHPAPI php_get_current_user(TSRMLS_D)
 172   Call: char *user = php_get_current_user(TSRMLS_C);
 173
 174 . php_idate
 175   PHPAPI php_idate(char format, time_t ts, int localtime TSRMLS_DC)
 176   Call: int ret = php_idate(format, ts, localtime TSRMLS_CC)
 177
 178 . php_escape_html_entities
 179   (size_t parameters were ints, previous "quote_style" (now flags) has expanded meaning)
 180   PHPAPI char *php_escape_html_entities(unsigned char *old, size_t oldlen, size_t *newlen, int all, int flags, char *hint_charset TSRMLS_DC);
 181
 182 . php_escape_html_entities_ex
 183   PHPAPI char *php_escape_html_entities_ex(unsigned char *old, size_t oldlen, size_t *newlen, int all, int flags, char *hint_charset, zend_bool double_encode TSRMLS_DC);
 184
 185 . php_unescape_html_entities
 186   PHPAPI char *php_unescape_html_entities(unsigned char *old, size_t oldlen, size_t *newlen, int all, int flags, char *hint_charset TSRMLS_DC);
 187
 188   i.
 189   PHPAPI char *expand_filepath_with_mode(const char *filepath, char *real_path, const char *relative_to, size_t relative_to_len, int realpath_mode TSRMLS_DC);
 190   expand_filepath_with_mode lets define how realpath will behave, using one of the existing mode: CWD_EXPAND , CWD_FILEPATH or CWD_REALPATH.
 191
 192 ========================
 193 2. Build system changes
 194 ========================
 195
 196   a. Unix build system changes
 197
 198     - Changes in SAPI module build:
 199       . When adding new binary SAPI (executable, like CLI/CGI/FPM) use CLI config.m4 and Makefile.frag files as templates and replace CLI/cli with your SAPI name.
 200
 201     - New macros:
 202       . PHP_INIT_DTRACE(providerdesc, header-file, sources [, module])
 203
 204
 205   b. Windows build system changes
 206     -
 207