1PHP 7.0 INTERNALS UPGRADE NOTES 2 30. Wiki Examples 41. Internal API changes 5 e. New data types 6 f. zend_parse_parameters() specs 7 g. sprintf() formats 8 h. HashTable API 9 i. New portable macros for large file support 10 j. New portable macros for integers 11 k. get_class_entry object handler info 12 l. get_class_name object handler info 13 m. Other portable macros info 14 n. ZEND_ENGINE_2 removal 15 o. Updated final class modifier 16 p. TSRM changes 17 q. gc_collect_cycles() is now hookable 18 r. PDO uses size_t for lengths 19 s. Resource API changes 20 t. Optimized strings concatenation. 21 u. Streams changes 22 v. Sort algorithm changes 23 242. Build system changes 25 a. Unix build system changes 26 b. Windows build system changes 27 283. Module changes 29 30================ 310. Wiki Examples 32================ 33 34The wiki contains multiple examples and further explanations of the internal 35changes. See: https://wiki.php.net/phpng-upgrading 36 37 38======================== 391. Internal API changes 40======================== 41 42 e. New data types 43 44 String 45 46 Besides the old way of accepting the strings with 's', the new 'S' ZPP spec 47 was introduced. It expects an argument of the type zend_string *. String lengths 48 in it are bound to the size_t datatype. 49 50 Integer types 51 52 Integers do no more depend on the firm 'long' type. Instead a platform 53 dependent integer type is used, it is called zend_long. That datatype is 54 defined dynamically to guarantee the consistent 64 bit support. The zval 55 field representing user land integer it bound to zend_long. 56 57 Signed integer is defined as zend_long, unsigned integer as zend_ulong 58 inside Zend. 59 60 Other datatypes 61 62 zend_off_t - portable off_t analogue 63 zend_stat_t - portable 'struct stat' analogue 64 65 These datatypes are declared to be portable across platforms. Thus, direct 66 usage of the functions like fseek, stat, etc. as well as direct usage of 67 off_t and struct stat is strongly not recommended. Instead the portable 68 macros should be used. 69 70 zend_fseek - portable fseek equivalent 71 zend_ftell - portable ftell equivalent 72 zend_lseek - portable lseek equivalent 73 zend_fstat - portable fstat equivalent 74 zend_stat - portable stat equivalent 75 76 f. zend_parse_parameters() specs 77 78 The new spec 'S' introduced, which expects an argument of type zend_string *. 79 The 'l' spec expects a parameter of the type zend_long, not long anymore. 80 The 's' spec expects parameters of the type char * and size_t, no int anymore. 81 82 g. sprintf() formats 83 84 New printf modifier 'p' was implemented to platform independently output zend_long, 85 zend_ulong and php_size_t datatypes. That modifier can be used with 'd', 'u', 'x' and 'o' 86 printf format specs with spprintf, snprintf and the wrapping printf implementations. 87 %pu is sufficient for both zend_ulong and php_size_t. the code using %p spec to output 88 pointer address might need to be enclosed into #ifdef when it unlickily followed by 'd', 89 'u', 'x' or 'o'. 90 91 The only exceptions are the snprintf and zend_sprintf functions yet, because in some cases 92 they can use the implemenations available on the system, not the PHP one. With snprintf the 93 macros ZEND_LONG_FMT and ZEND_ULONG_FMT should be used. 94 95 h. HashTable API 96 97 Datatype for array indexes was changed to zend_ulong, for string keys to zend_string *. 98 99 i. New portable macros for large file support 100 101 Function(s) Alias Comment 102 stat, _stat64 zend_stat for use with zend_stat_t 103 fstat, _fstat64 zend_fstat for use with zend_stat_t 104 lseek, _lseeki64 zend_lseek for use with zend_off_t 105 ftell, _ftelli64 zend_ftell for use with zend_off_t 106 fseek, _fseeki64 zend_fseek for use with zend_off_t 107 108 j. New portable macros for integers 109 110 Function(s) Alias Comment 111 snprintf with "%ld" or "%lld", _ltoa_s, _i64toa_s ZEND_LTOA for use with zend_long 112 atol, atoll, _atoi64 ZEND_ATOL for use with zend_long 113 strtol, strtoll, _strtoi64 ZEND_STRTOL for use with zend_long 114 strtoul, strtoull, _strtoui64 ZEND_STRTOUL for use with zend_long 115 abs, llabs, _abs64 ZEND_ABS for use with zend_long 116 - ZEND_LONG_MAX replaces LONG_MAX where appropriate 117 - ZEND_LONG_MIN replaces LONG_MIN where appropriate 118 - ZEND_ULONG_MAX replaces ULONG_MAX where appropriate 119 - SIZEOF_ZEND_LONG reworked SIZEOF_ZEND_LONG representing the size of zend_long datatype 120 - ZEND_SIZE_MAX Max value of size_t 121 - Z_L casts an integral constant to zend_long 122 - Z_UL casts an integral constant to zend_ulong 123 124 The macro ZEND_ENABLE_ZVAL_LONG64 reveals whether zval operates on 64 or 32 bit integer. 125 126 k. The get_class_entry object handler is no longer available. Instead 127 zend_object.ce is always used. 128 129 l. The get_class_name object handler is now only used for displaying class 130 names in debugging functions like var_dump(). It is no longer used in 131 get_class(), get_parent_class() or similar. 132 133 The handler is now obligatory, no longer accepts a `parent` argument and 134 must return a non-NULL zend_string*, which will be released by the caller. 135 136 m. Other portable macros info 137 138 ZEND_SECURE_ZERO - zeroes chunk of memory 139 ZEND_VALID_SOCKET - validates a php_socket_t variable 140 141 ZEND_FASTCALL is defined to use __vectorcall convention on VS2013 and above 142 ZEND_NORETURN is defined as __declspec(noreturn) on VS 143 144 n. The ZEND_ENGINE_2 macro has been removed. A ZEND_ENGINE_3 macro has been added. 145 146 o. Removed ZEND_ACC_FINAL_CLASS in favour of ZEND_ACC_FINAL, turning final class 147 modifier now a different class entry flag. Update your extensions. 148 149 p. TSRM changes 150 151 The TSRM layer undergone significant changes. It is not necessary anymore to 152 pass the tsrm_ls pointer explicitly. The TSRMLS_* macros should not be used 153 in any new developments. 154 155 The recommended way accessing globals in TS builds is by implementing it 156 to use a local thread unique pointer to the corresponding data pool. These 157 are the new macros that serve to achieve this goal: 158 159 - ZEND_TSRMG - based on TSRMG and if static pointer for data pool access is 160 implemented, will use it 161 - ZEND_TSRMLS_CACHE_EXTERN - to be used in a header shared across multiple 162 C/C++ files 163 - ZEND_TSRMLS_CACHE_DEFINE - to be used in the main extension C/C++ file 164 - ZEND_TSRMLS_CACHE_UPDATE - to be integrated at the top of the globals 165 ctor or RINIT function 166 - ZEND_ENABLE_STATIC_TSRMLS_CACHE - to be used in the config.[m4|w32] for 167 enabling the globals access per thread unique pointer 168 - TSRMLS_CACHE - expands to the variable name which links to the thread 169 unique data pool 170 171 Note that usually it will work without implementing the globals access per 172 a thread unique pointer, however it might cause a slowdown. The reason is 173 that the access model to the extension/SAPI own globals as well as the 174 access to the core globals is determined in the compilation phase depending 175 on whether ZEND_ENABLE_STATIC_TSRMLS_CACHE macro is defined. 176 177 Due to the current compiler evolution state, the TSRMLS_CACHE pointer 178 (when implemented) has to be present and updated in every binary unit which 179 is not compiled statically into PHP. So any DLL, DSO, EXE, etc. has to take 180 care about defining and updating it's TSRMLS cache. An update should happen 181 before any globals was accessed. 182 183 Porting an extension or SAPI is usually as easy as removing all the TSRMLS_* 184 occurrences and integrating the macros mentioned above. However if tsrm_ls 185 is used explicitly, its usage can be considered obsolete in most cases. 186 Additionally, if an extension triggers its own threads, TSRMLS_CACHE shouldn't 187 be passed to that threads directly. 188 189 When working with CTOR/DTOR for the extension globals, only the data passed 190 as parameters should be touched. For example, don't use code like 191 free(MYEXT_G(vars)); inside globals destructor, as it possibly can destroy 192 the data from a wrong thread. Instead use the pointer to the data delivered 193 into the destructor. So the previous example could look like 194 free(my_struct->vars); given the income was casted to (struct my_struct *). 195 196 A new macro was introduced to simplify the declaration to the extension 197 globals. A simplified declaration looks as follows 198 199 #define MYEXT_G(v) ZEND_MODULE_GLOBALS_ACCESSOR(myext, v) 200 201 Another new macro ZEND_MODULE_GLOBALS_BULK(myext) delivers the corresponding 202 globals struct as a whole. 203 204 Two new storage specifiers was introduced. 205 206 ZEND_EXT_TLS - expand to an appropriate thread specific storage specifier in 207 the thread safe build, expands to empty in a non thread safe 208 build. 209 ZEND_TLS - expands to an appropriate thread specific storage specifier 210 with static visibility in the thread safe build, expands to 211 static specifier in a non thread safe build. 212 213 Variables declared with these storage specifiers can not be shared across 214 threads. While ZEND_TLS enforces the local scope visibility, ZEND_EXT_TLS 215 pertains to the visiblity across several compilation units. In both cases, 216 there's no portable way to achieve the visibility across shared objects. 217 Thus, these specifiers are not compatible with ZEND_API and PHPAPI specifiers. 218 219 q. gc_collect_cycles() is now a function pointer, and can be replaced in the 220 same manner as zend_execute_ex() if needed (for example, to include the 221 time spent in the garbage collector in a profiler). The default 222 implementation has been renamed to zend_gc_collect_cycles(), and is 223 exported with ZEND_API. 224 225 r. In accordance with general use of size_t as string length, all PDO API 226 functions now use size_t for string length. 227 228 s. Removed ZEND_REGISTER/FETCH_RESOURCE, use zend_fetch_resource and 229 and zend_register_resource instead, zend_fetch_resource accepts a zend_resource * 230 as first argument, if you still need to fetch a resource from zval, use 231 zend_fetch_resource_ex. More details can be found in Zend/zend_list.c. 232 233 t. Optimized strings concatenation. 234 ZEND_ADD_STRING/VAR/CHAR are replaced with ZEND_ROPE_INIT, ZEND_ROPE_ADD, 235 ZEND_ROPE_END. 236 Instead of reallocation and copying string on each ZEND_ADD_STRING/VAR/CAHR, 237 collect all the strings and then allocate and construct the resulting string once. 238 239 u. Streams changes 240 - It is possible to do blocking reads on Windows pipes. It can be done either 241 using context stream option PHP_STREAM_OPTION_PIPE_BLOCKING or 242 adding STREAM_USE_BLOCKING_PIPE when opening the stream. 243 244 v. Sort algorithm changes 245 - Improved zend_qsort(using hybrid sorting algo) for better performance, 246 and also renamed zend_qsort to zend_sort. 247 - Added stable sorting algo zend_insert_sort. 248 249 w. Tick functions internal API change 250 Tick functions have different declaration now. They expect a single 251 parameter while before they were parameterless. When registering the 252 tick function a value for this parameter must be passed. This value will be 253 provided to the tick function on every execution. 254 255======================== 2562. Build system changes 257======================== 258 259 a. Unix build system changes 260 261 b. Windows build system changes 262 263 - Besides Visual Studio, building with Clang or Intel Composer is now 264 possible. To enable an alternative toolset, add the option 265 --with-toolset=[vs,clang,icc] to the configure line. The default 266 toolset is vs. Still clang or icc need the correct environment 267 which involves many tools from the vs toolset. 268 269 The toolset option is supported by phpize as well. 270 271 AWARENESS The only recommended and supported toolset to produce production 272 ready binaries is Visual Studio. Still other compilers can be used now for 273 testing and analyzing purposes. 274 275 - configure.js now produces response files which are passed to the linker 276 and library manager. This solves the issues with the long command lines 277 which can exceed the OS limit. 278 279 - with clang toolset, an option --with-uncritical-warn-choke is available, 280 which suppresses the most frequent false positive warnings 281 282 - the --with-mp option will by default utilize all the available cores. It's 283 enabled by default for release builds and can be disabled with the special 284 "disable" keyword. 285 286======================== 2873. Module changes 288======================== 289 290 Session: 291 292 - PS_MOD_UPDATE_TIMESTAMP() session save handler definition is added. New 293 save handler should use PS_MOD_UPDATE_TIMESTAMP() definition. Save handler 294 must not refer/change PS() variables directly from save handler. Use 295 parameters. 296 - PS_MOD()/PS_MOD_SID() macro exist only for transition. Beware these 297 save handlers are less secure and slower than PS_MOD_UPDATE_TIMESTAMP(). 298 - PS(invalid_session_id) was removed. It was never worked as it supposed. 299 To report invalid session ID, use PS_VALIDATE_SID() handler. 300 - PS_VALIDATE_SID() defines session ID validation handler. This handler 301 must validate if requested session ID exists in session data storage or not. 302 Do not access PS(id) directly, but use this handler and it's parameter. 303 - PS_UPDATE_TIMESTAMP() defines timestamp updating handler. This handler 304 must update session data timestamp for GC if it is needed. e.g. Memcache 305 updates timestamp on read, so it does not need to update timestamp. Return 306 SUCCESS simply for this case. 307 - PS_CREATE_SID() should check session ID collision. Return NULL for failure. 308 - More documentation can be found in ext/session/mod_files.c as comments. 309 mod_files.c may be used as reference implementation. 310 311 Openssl: 312 - several ext/openssl functions require the inclusion of the applink shim 313 as documented in the OpenSSL FAQ https://www.openssl.org/support/faq.html#PROG2 314 to properly work on Windows. While this primarily affects the OpenSSL 315 functionality, the shim needs to be included into the executable file 316 which loads the extension DLL, not into the extension DLL itself. Alternatively 317 it can be compiled and linked with the main program as a separate object file. 318 More information and explanation in the linked OpenSSL FAQ. 319 320 Thus, this primarily affects any WAMP or other redistributions bundling the 321 official PHP release zipballs or building from sources. The applink shim is 322 already integrated with all the PHP executables from the official distribution 323 starting with 7.0.0beta1. 324 325
