1PHP 8.4 INTERNALS UPGRADE NOTES 2 31. Internal API changes 4 52. Build system changes 6 73. Module changes 8 94. OpCode changes 10 115. SAPI changes 12 13======================== 141. Internal API changes 15======================== 16 17* zend_register_module_ex() now takes an additional int module_type argument. 18 This function will also assign the module number and type, there is no need 19 to do this at the call site anymore. Writing the handle should happen after 20 successful registration. 21 22* ZPP now accepts a F or Z_PARAM_FUNC_NO_TRAMPOLINE_FREE type check. 23 This is identical to the 'f' or Z_PARAM_FUNC type check, except the FCC is 24 always initialized because it doesn't free trampolines. 25 Trampolines MUST be freed using zend_release_fcall_info_cache() or consumed. 26 Z_PARAM_FUNC_EX2 was added as well with the same arguments as Z_PARAM_FUNC_EX 27 plus an additional argument free_trampoline. 28 29* The zend_object_iterator_funcs valid member has changed its signature from 30 int(*)(zend_object_iterator *) to zend_result(*)(zend_object_iterator *) to 31 be more in line with what callbacks are returning. 32 33* The backwards compatibility headers ext/standard/{php_lcg.h,php_mt_rand.h, 34 php_rand.h,php_random.h} have been removed. Include ext/random/php_random.h 35 directly. 36 37* The zend_*printf family of functions now supports the "%S" modifier to print 38 out zend_string*. This won't cut off the string if it embeds a NUL byte. 39 40* The inet_aton() and win32/inet.h have been removed. Use platform-agnostic 41 inet_pton() from arpa/inet.h or ws2tcpip.h on Windows. 42 43* zend_mm_set_custom_debug_handlers() has been removed from ZendMM, use 44 zend_mm_set_custom_handlers() instead which now supports DEBUG builds 45 46* zend_mm_set_custom_handlers() has changed its signature from 47 void()(zend_mm_heap *heap, 48 void* (*_malloc)(size_t), 49 void (*_free)(void*), 50 void* (*_realloc)(void*, size_t)) 51 to 52 void()(zend_mm_heap *heap, 53 void* (*_malloc)(size_t ZEND_FILE_LINE_DC ZEND_FILE_LINE_ORIG_DC), 54 void (*_free)(void* ZEND_FILE_LINE_DC ZEND_FILE_LINE_ORIG_DC), 55 void* (*_realloc)(void*, size_t ZEND_FILE_LINE_DC ZEND_FILE_LINE_ORIG_DC)) 56 57* zend_mm_get_custom_handlers() has changed its signature from 58 void()(zend_mm_heap *heap, 59 void* (**_malloc)(size_t), 60 void (**_free)(void*), 61 void* (**_realloc)(void*, size_t)) 62 to 63 void()(zend_mm_heap *heap, 64 void* (**_malloc)(size_t ZEND_FILE_LINE_DC ZEND_FILE_LINE_ORIG_DC), 65 void (**_free)(void* ZEND_FILE_LINE_DC ZEND_FILE_LINE_ORIG_DC), 66 void* (**_realloc)(void*, size_t ZEND_FILE_LINE_DC ZEND_FILE_LINE_ORIG_DC)) 67 68* Added gc and shutdown custom handlers, settable via 69 zend_mm_set_custom_handlers_ex() 70 71* __zend_malloc() has changed their signature from 72 void(*)(size_t) to 73 void(*)(size_t ZEND_FILE_LINE_DC ZEND_FILE_LINE_ORIG_DC) 74 75* __zend_calloc() has changed their signature from 76 void(*)(size_t, size_t) to 77 void(*)(size_t, size_t ZEND_FILE_LINE_DC ZEND_FILE_LINE_ORIG_DC) 78 79* __zend_realloc() has changed their signature from 80 void(*)(void *, size_t) to 81 void(*)(void *, size_t ZEND_FILE_LINE_DC ZEND_FILE_LINE_ORIG_DC) 82 83* zend_observer_remove_begin_handler() and zend_observer_remove_end_handler() 84 got each a new parameter returning an observer which must be called, if the 85 removal happened during observer execution. 86 87* zend_get_internal_function_extension_handle[s]() must now be used over 88 zend_get_op_array_extension_handle[s]() when registering run_time_cache slots 89 for internal functions. If you need a cache slot for both internal and user 90 functions, you may obtain a slot for each through the corresponding function. 91 92* zend_is_true now returns bool rather than int. Note that on PHP 8 this has 93 always returned 0 or 1, so conversion should be trivial. 94 95* Added zend_hash_get_current_pos_ex() variant of zend_hash_get_current_pos(). 96 97* Renamed rebuild_object_properties() to rebuild_object_properties_internal(). 98 This function should not be used outside of zend_std_get_properties_ex() and 99 zend_std_get_properties(). Use zend_std_get_properties_ex() or 100 zend_std_get_properties() instead. 101 102* zend_object.properties must not be accessed directly. Use 103 zend_std_get_properties_ex() instead. 104 105* Removed IS_STATIC_VAR_UNINITIALIZED constant. Check for IS_NULL in the 106 static_variables array instead. 107 108* Removed ZEND_DIM_ALTERNATIVE_SYNTAX constant. This syntax no longer has a 109 specialized error message. 110 111======================== 1122. Build system changes 113======================== 114 115 a. Abstract 116 - The configure option --with-imap has been removed. 117 - The configure option --with-mhash emits deprecation warning. 118 - The configure option --with-pdo-oci has been removed. 119 - The configure option --with-pspell has been removed. 120 - Symbol SIZEOF_SHORT removed (size of 2 on 32-bit and 64-bit platforms). 121 - Symbol DBA_CDB_MAKE removed in ext/dba. 122 - Symbol HAVE_LIBM has been removed. 123 - Symbol HAVE_INET_ATON has been removed. 124 - Symbol HAVE_SIGSETJMP has been removed. 125 - The Zend/zend_istdiostream.h header has been removed. 126 127 b. Unix build system changes 128 - The configure option --with-imap-ssl has been removed. 129 - The configure option --with-oci8 has been removed. 130 - The configure option --with-zlib-dir has been removed. 131 - The configure option --with-kerberos has been removed. 132 - The configure option --with-openssl-dir has been removed. SSL support in 133 ext/ftp and ext/mysqlnd is enabled implicitly, when building with 134 ext/openssl (--with-openssl), or explicitly by using new configure options 135 --with-ftp-ssl and --with-mysqlnd-ssl. 136 - New configure option --with-openssl-legacy-provider to enable OpenSSL 137 legacy provider. 138 - New configure option --with-openssl-argon2 to enable PASSWORD_ARGON2 139 from OpenSSL 3.2 140 - COOKIE_IO_FUNCTIONS_T symbol has been removed (use cookie_io_functions_t). 141 - HAVE_SOCKADDR_UN_SUN_LEN symbol renamed to HAVE_STRUCT_SOCKADDR_UN_SUN_LEN. 142 - HAVE_UTSNAME_DOMAINNAME symbol renamed to HAVE_STRUCT_UTSNAME_DOMAINNAME. 143 - PHP_CHECK_IN_ADDR_T Autoconf macro and 'in_addr_t' fallback definition to 144 'u_int' removed (use AC_CHECK_TYPES Autoconf macro instead). 145 - HAVE_ODBC2 symbol has been removed in ext/odbc. 146 - Removed linking with obsolete dnet_stub library in ext/pdo_dblib. 147 - Removed checking and linking with obsolete libbind for some functions. 148 - Symbol HAVE_JSON has been removed (ext/json is always available since PHP 149 8.0). 150 - Symbol DARWIN has been removed (use __APPLE__ to target Darwin systems). 151 - Symbol MISSING_FCLOSE_DECL and Autoconf macro PHP_MISSING_FCLOSE_DECL were 152 removed. 153 - Symbol HAVE_BSD_ICONV has been removed. 154 - Symbol ZEND_FIBER_ASM has been removed. 155 - Symbols HAVE_DLOPEN and HAVE_DLSYM have been removed. 156 - Symbol HAVE_MYSQL has been removed. 157 - Symbol HAVE_PDO_SQLITELIB has been removed. 158 - Symbol HAVE_WAITPID has been removed. 159 - Symbol HAVE_LIBPQ has been removed. 160 - Symbols HAVE_LIBRT and HAVE_TIMER_CREATE removed. 161 - Symbols PHP_FPM_SYSTEMD, PHP_FPM_USER, and PHP_FPM_GROUP removed. 162 - Symbol PTHREADS has been removed. 163 - Symbol HAVE_STRPTIME_DECL_FAILS has been removed (use HAVE_DECL_STRPTIME). 164 - Symbol HAVE_PHPDBG has been removed. 165 - Symbols PHP_HAVE_AVX512_SUPPORTS and PHP_HAVE_AVX512_VBMI_SUPPORTS are now 166 either defined to 1 or undefined. 167 - Symbol HAVE_LIBCRYPT has been removed. 168 - Autoconf macro PHP_DEFINE (atomic includes) removed (use AC_DEFINE and 169 config.h). 170 - Autoconf macro PHP_WITH_SHARED has been removed (use PHP_ARG_WITH). 171 - Autoconf macro PHP_STRUCT_FLOCK has been removed (use AC_CHECK_TYPES). 172 - Autoconf macro PHP_SOCKADDR_CHECKS has been removed (use AC_CHECK_TYPES and 173 AC_CHECK_MEMBERS). 174 - Autoconf macro PHP_CHECK_GCC_ARG has been removed since PHP 8.0 (use 175 AX_CHECK_COMPILE_FLAG). 176 - Autoconf macro PHP_PROG_RE2C got a new 2nd argument to define common 177 default re2c command-line options substituted to the Makefile RE2C_FLAGS 178 variable. 179 - Autoconf macros PHP_CHECK_BUILTIN_* have been removed in favor of 180 PHP_CHECK_BUILTIN and all PHP_HAVE_BUILTIN_* symbols changed to be either 181 undefined or defined to 1 whether compiler supports the builtin. 182 - Added php-config --lib-dir and --lib-embed options for PHP embed SAPI. 183 - PDO extensions in php-src don't have the include flag -I$pdo_cv_inc_path 184 directory anymore. 185 - Autoconf macro PHP_SETUP_OPENSSL doesn't accept the 3rd argument anymore. 186 - Autoconf macro PHP_EVAL_LIBLINE got a new 3rd argument to override the 187 ext_shared checks. 188 - Autoconf macro PHP_SETUP_LIBXML doesn't define the redundant HAVE_LIBXML 189 symbol anymore and requires at least libxml2 2.9.4. 190 - Autoconf macro PHP_SETUP_ICONV doesn't define the HAVE_ICONV symbol 191 anymore. 192 - Autoconf macro PHP_AP_EXTRACT_VERSION is obsolete (use the 193 'apxs -q HTTPD_VERSION'). 194 - Autoconf macro PHP_OUTPUT is obsolete (use AC_CONFIG_FILES). 195 - Autoconf macro PHP_TEST_BUILD is obsolete (use AC_* macros). 196 - Autoconf macro PHP_BUILD_THREAD_SAFE is obsolete (set enable_zts manually). 197 - Autoconf macro PHP_DEF_HAVE is obsolete (use AC_DEFINE). 198 - Autoconf macro PHP_PROG_SETUP now accepts an argument to set the minimum 199 required PHP version during the build. 200 - Autoconf macro PHP_INSTALL_HEADERS arguments can now be also 201 blank-or-newline-separated lists instead of only separated with whitespace 202 or backslash-then-newline. 203 - Autoconf macro PHP_ADD_BUILD_DIR now also accepts 1st argument as a 204 blank-or-newline-separated separated list. 205 - Autoconf macros PHP_NEW_EXTENSION, PHP_ADD_SOURCES, PHP_ADD_SOURCES_X, 206 PHP_SELECT_SAPI now have the source files and flags arguments normalized so 207 the list of items can be passed as a blank-or-newline-separated list. 208 - Autoconf macro PHP_ADD_INCLUDE now takes also a blank-or-newline-separated 209 list of include directories instead of a single directory. The "prepend" 210 argument is validated at Autoconf compile time. 211 - TSRM/tsrm.m4 file and its TSRM_CHECK_PTHREADS macro have been removed. 212 - Added pkg-config support to find libpq for the pdo_pgsql and pgsql 213 extensions. The libpq paths can be customized with the PGSQL_CFLAGS and 214 PGSQL_LIBS environment variables. When a directory argument is provided to 215 configure options (--with-pgsql=DIR or --with-pdo-pgsql=DIR), it will be 216 used instead of the pkg-config search. 217 - Added pkg-config support to find unixODBC and iODBC for the pdo_odbc 218 extension. 219 - Added pkg-config support to find GNU MP library. As a fallback default 220 system paths are searched. When a directory argument is provided 221 (--with-gmp=DIR), it will be used instead of the pkg-config. 222 - Added optional pkg-config support to find NET-SNMP library. As a fallback 223 net-snmp-config utility is used like before. 224 - Removed BC enable_pear variable check due to --enable-pear configure option 225 once used (use with_pear variable name). 226 - Cache variables synced to php_cv_* naming scheme. If you use them for 227 advanced cross-compilation, these were renamed: 228 - ac_cv_copy_file_range -> php_cv_func_copy_file_range 229 - ac_cv_flush_io -> php_cv_have_flush_io 230 - ac_cv_func_getaddrinfo -> php_cv_func_getaddrinfo 231 - ac_cv_have_broken_gcc_strlen_opt -> php_cv_have_broken_gcc_strlen_opt 232 - ac_cv_have_pcre2_jit -> php_cv_have_pcre2_jit 233 - ac_cv_pread -> php_cv_func_pread 234 - ac_cv_pwrite -> php_cv_func_pwrite 235 - ac_cv_syscall_shadow_stack_exists -> php_cv_have_shadow_stack_syscall 236 - ac_cv_time_r_type -> php_cv_time_r_type 237 - ac_cv_write_stdout -> php_cv_have_write_stdout 238 and all other checks wrapped with their belonging cache variables (see *.m4 239 source files for details). 240 241 c. Windows build system changes 242 - The configure options --with-oci8-11g, --with-oci8-12c, --with-oci8-19, 243 --enable-apache2-2handler have been removed. 244 - The configure option --enable-apache2-4handler is now an alias for the 245 preferred --enable-apache2handler. 246 - Added Bison flag '-Wall' when generating lexer files as done in *nix build 247 system. 248 - HAVE_WIN32_NATIVE_THREAD, USE_WIN32_NATIVE_THREAD, ENABLE_THREADS symbols 249 in ext/mbstring/libmbfl removed. 250 - FIBER_ASSEMBLER and FIBER_ASM_ARCH Makefile variables removed in favor of 251 PHP_ASSEMBLER and FIBER_ASM_ABI. 252 - HAVE_PHP_SOAP symbol renamed to HAVE_SOAP. 253 - Unused symbols CONFIGURATION_FILE_PATH, DISCARD_PATH, HAVE_ERRMSG_H, 254 HAVE_REGCOMP, HAVE_RINT, NEED_ISBLANK, PHP_URL_FOPEN, REGEX, HSREGEX, 255 USE_CONFIG_FILE have been removed. 256 - The HAVE_OPENSSL symbol has been removed. 257 - The HAVE_OPENSSL_EXT symbol is now consistently defined to value 1 whether 258 the openssl extension is available either as shared or built statically. 259 - Added configure option --enable-phpdbg-debug to build phpdbg in debug mode. 260 - The win32/build/libs_version.txt file has been removed. 261 - MSVC builds now use the new preprocessor (/Zc:preprocessor). 262 - The CHECK_HEADER_ADD_INCLUDE function now consistently defines preprocessor 263 macros HAVE_<header>_H either to value 1 or leaves them undefined to match 264 the Autotools headers checks. 265 266======================== 2673. Module changes 268======================== 269 270 a. ext/dom 271 - dom_read_t and dom_write_t now expect the function to return zend_result 272 instead of int. 273 - The macros DOM_NO_ARGS() and DOM_NOT_IMPLEMENTED() have been removed. 274 - New public APIs are available to handle callbacks from XPath, see 275 xpath_callbacks.h. 276 - Added public APIs to manipulate namespace data, see namespace_compat.h. 277 - php_dom_create_object() now no longer accepts a NULL obj argument. 278 - Removed the `ret` argument from the DOM_RET_OBJ macro, use the return 279 value instead. 280 - Removed DOM_XMLNS_NAMESPACE from xml_common.h. Use DOM_XMLNS_NS_URI 281 from namespace_compat.h instead. 282 - Added php_dom_get_ns_mapper(), php_dom_next_in_tree_order(), 283 php_dom_follow_spec_doc_ref(), and php_dom_follow_spec_doc_ref(). 284 285 b. ext/random 286 - The macro RAND_RANGE_BADSCALING() has been removed. The implementation 287 should either be inlined and undefined behavior fixed or it should be 288 replaced by a non-biased scaler. 289 - The php_srand() and php_rand() functions have been removed. These were 290 slim wrappers around the corresponding php_mt_srand() and php_mt_rand() 291 function since PHP 7.1, but using zend_long instead of uint32_t as their 292 input/output types. This made their behavior incompatible between 32-bit 293 and 64-bit builds of PHP. Users of these functions are encouraged to 294 migrate to one of the more modern engines provided since PHP 8.2. If that 295 is not possible, due to backwards compatibility requirements, then the 296 php_mt_srand() and php_mt_rand() functions should be called directly and 297 the values appropriately casted. 298 - The PHP_RAND_MAX and RAND_MAX constants corresponding to the removed 299 php_rand() have also been removed. 300 - The generate member of a php_random_algo is now expected to return 301 the new php_random_result struct, replacing the last_generated_size 302 member of the php_random_status struct and the generate_size member of 303 the php_random_algo struct. 304 - The php_random_status struct has been removed, since the previous change 305 reduced it to a single void* member containing the actual state, resulting 306 in needless indirection. Functions taking a php_random_algo struct pointer 307 and a php_random_status struct pointer as separate parameters now take a 308 single php_random_algo_with_state struct by value, making it easier to 309 pass around the state with its associated algorithm and thus reducing 310 the chance for mistakes. 311 - The seed member of a php_random_algo has been removed. As a replacement 312 engine-specific seeding functions are now exposed. This change allows 313 users to better take engine-specific behavior into account. As an example 314 Mt19937 ignored the upper half of the seed parameter of the generic 315 seeding function. 316 - The CSPRNG API (php_random_(bytes|int)_*) is now provided by the new 317 and much smaller php_random_csprng.h header. The new header is included 318 in php_random.h for compatibility with existing users. 319 - A new php_random_generate_fallback_seed() function has been added as a 320 replacement for the generically named GENERATE_SEED(). The internal 321 implementation has been improved to generate better seeds, however any 322 users should use the opportunity to verify that seeding is first 323 attempted using the CSPRNG for better output size flexibility. 324 - The standalone combined_lcg engine has been removed, as the lcg_value() 325 userland function is deprecated and as the engine is unable to return 326 unbiased integer values. The internal php_combined_lcg() function remains 327 available for now. 328 329 c. ext/xsl 330 - The function php_xsl_create_object() was removed as it was not used 331 nor exported. 332 333 d. ext/libxml 334 - Added php_libxml_pretend_ctx_error_ex() to emit errors as if they had come 335 from libxml. 336 - Added php_libxml_error_handler_va() to pass libxml errors, and 337 corresponding php_libxml_error_level enum. 338 - Removed the "properties" HashTable field from php_libxml_node_object. 339 - Added a way to attached private data to a php_libxml_ref_obj. 340 - Added a way to fix a class type onto php_libxml_ref_obj. 341 - Added a way to record quirks mode in php_libxml_ref_obj. 342 - Added php_libxml_uses_internal_errors(). 343 - Added a way to override document handlers (e.g. serialization) with 344 php_libxml_document_handlers. 345 - Changed the refcount fields from int to unsigned int. 346 347 e. ext/date 348 - Added the php_format_date_ex() API to format instances of php_date_obj. 349 - Added the php_date_initialize_from_ts_long() and 350 php_date_initialize_from_ts_double() to initialize a php_date_obj with 351 the given unix timestamp using GMT +00:00. 352 353 f. ext/pcre 354 - php_pcre_match_impl() now no longer has a use_flags argument. 355 When flags should be ignored, pass 0 to the flags argument. 356 - php_pcre_match_impl() and pcre_get_compiled_regex_cache_ex() now use 357 proper boolean argument types instead of integer types. 358 - pcre_get_compiled_regex_cache_ex() now provides an option to collect extra 359 options (from modifiers used in the expression, for example), and calls 360 pcre2_set_compile_extra_options() with those options. 361 - Removed per-request cache, the cache is now always per process or 362 per thread depending on whether you use NTS or ZTS. 363 This was removed due to fundamental ordering issues between destructors. 364 365 g. ext/standard 366 - Added the php_base64_encode_ex() API with flag parameters, value can be 367 PHP_BASE64_NO_PADDING to encode without the padding character '='. 368 - The php_escape_shell_cmd() now takes a zend_string* instead of a char* 369 Moreover, providing it with a binary safe string is the responsibility of 370 the caller now. 371 - The php_escape_shell_arg() now takes a zend_string* instead of a char* 372 Moreover, providing it with a binary safe string is the responsibility of 373 the caller now. 374 - The php_info_html_esc() function has been removed, use 375 php_escape_html_entities() with ENT_QUOTES directly instead. 376 - The deprecated php_uint32 and php_int32 typedefs have been removed from 377 ext/standard/basic_functions.h. Use the standard uint32_t and int32_t 378 types instead. 379 - The php_mkdir() and php_mkdir_ex() APIs have been removed, use 380 php_stream_mkdir() instead. 381 - The php_strtoupper(), php_string_toupper(), php_strtolower(), and 382 php_string_tolower() functions has been removed, use zend_str_toupper(), 383 zend_string_toupper(), zend_str_tolower(), and zend_string_tolower() 384 respectively instead. 385 - The php_replace_controlchars_ex() function is no longer exposed. 386 387 h. ext/session 388 - Added the php_get_session_status() API to get the session status, which is 389 equivalent to reading PS(session_status) but works with shared objects too. 390 - Added the php_get_session_var_str() API to set a session variable without 391 needing to create a zend_string. 392 - The ext/session/php_session.h doesn't transitively include the 393 ext/hash/php_hash.h header anymore. 394 - It is no longer allowed to return out of the PS_ENCODE_LOOP macro. 395 Instead, you should break out of the loop instead. 396 397 i. ext/xml 398 - Made the expat compatibility wrapper XML_GetCurrentByteIndex return a long 399 instead of an int. This corresponds to the XML_Index type when 400 XML_LARGE_SIZE is not used in expat. 401 402======================== 4034. OpCode changes 404======================== 405 406* DO_ICALL, DO_FCALL, and DO_FCALL_BY_NAME now call zend_interrupt_function 407 while the internal frame is still on the stack. This means interrupt handlers 408 will now see the internal call. If your interrupt handler does something like 409 switching EG(current_execute_data), it should not do so if an internal func 410 is on top. 411* New FRAMELESS_ICALL_[0,3] opcodes for faster internal function calls have been 412 added. These opcodes don't create a stack frame, but pass arguments via opcode 413 operands. They only work for functions that are known at compile-time, and 414 that provide a frameless handler (search for usages of the 415 ZEND_FRAMELESS_FUNCTION macro). 416 417* CREATE_GENERATOR now initializes the generator with opline pointing to the 418 CREATE_GENERATOR op (before, opline was set to the next op). 419 420* YIELD and YIELD_FROM do not increment the opline anymore. 421 422* The EXIT opcode has been removed as exit is now implemented as a function. 423 424======================== 4255. SAPI changes 426======================== 427
