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