1PHP 7.4 INTERNALS UPGRADE NOTES 2 31. Internal API changes 4 a. php_sys_symlink() and php_sys_link() 5 b. zend_lookup_class_ex() and zend_fetch_class_by_name() 6 c. Function/property/class flags 7 d. Removed zend_check_private() 8 e. php_win32_error_to_msg() memory management 9 f. get_properties_for() handler / Z_OBJDEBUG_P 10 g. Required object handlers 11 h. Immutable classes and op_arrays 12 i. php_fgetcsv() and php_fputcsv() 13 j. Removed add_get_assoc_*() and add_get_index_*() 14 k. Class declaration opcodes 15 l. HASH_FLAG_INITIALIZED 16 m. write_property return value 17 n. Assignments to references 18 o. ZEND_COMPILE_EXTENDED_INFO split 19 p. ZEND_EXT_FCALL_BEGIN can access arguments 20 q. ZEND_COMPILE_IGNORE_USER_FUNCTIONS and ZEND_COMPILE_IGNORE_INTERNAL_FUNCTIONS 21 r. TSRM environment locking 22 s. Typed references support 23 t. Exceptions thrown by string conversions. 24 u. Removed uint and ulong typedefs 25 v. Compound assignment opcodes 26 w. APACHE symbol removed 27 x. php_error_docref0() renamed to php_error_docref() 28 y. Stream wrapper read/write ops 29 302. Build system changes 31 a. Abstract 32 b. Unix build system changes 33 c. Windows build system changes 34 353. Module changes 36 a. ext/xml 37 b. ext/hash 38 39======================== 401. Internal API changes 41======================== 42 43 a. php_sys_symlink() and php_sys_link() portability macros have been 44 added, which behave like POSIX's symlink() and link(), respectively, on 45 POSIX compliant systems and on Windows. 46 47 b. zend_lookup_class_ex() and zend_fetch_class_by_name() prototypes were 48 changed to accept optional lower-case class name as zend_string*, 49 instead of zval*. 50 51 c. Function/property/class flags changes 52 - ZEND_ACC_IMPLEMENTED_ABSTRACT is removed (it was used only internally 53 during inheritance). 54 - ZEND_ACC_IMPLICIT_PUBLIC is removed (it was used only for reflection) 55 - ZEND_ACC_SHADOW property flag is removed. Instead of creating shadow 56 clone, now we use the same private property_info, and should also 57 check property_info->ce (in the same way as with methods). 58 - ZEND_ACC_ANON_BOUND is replaced with ZEND_ACC_LINKED. This flag is set 59 not only during anonymous classes declaration, but also during any 60 run-time or compile-time class declaration. 61 - ZEND_ACC_NO_RT_ARENA renamed into ZEND_ACC_HEAP_RT_CACHE. Now it's used 62 not only for closures, but also for pseudo-main op_arrays. 63 - ZEND_ACC_... flags are re-numbered. 64 65 d. zend_check_private() is removed. Use (func->common.scope == scope) instead. 66 67 e. Pointers returned by php_win32_error_to_msg() have to be freed using 68 php_win32_error_msg_free(). Same regarding php_win_err() vs. 69 php_win_err_free(). 70 71 f. A new, optional object handler with the signature 72 73 HashTable *get_properties_for(zval *obj, zend_prop_purpose purpose) 74 75 has been introduced, where zend_prop_purpose (currently) takes one of: 76 77 ZEND_PROP_PURPOSE_DEBUG // var_dump etc. 78 ZEND_PROP_PURPOSE_ARRAY_CAST // (array) $obj 79 ZEND_PROP_PURPOSE_SERIALIZE // "O"-format serialization (__wakeup) 80 ZEND_PROP_PURPOSE_VAR_EXPORT // var_export (__set_state) 81 ZEND_PROP_PURPOSE_JSON // json_encode 82 83 The handler returns a non-null HashTable with increased refcounted, and 84 the return value must be released using zend_release_properties(). 85 86 This handler serves the same general function as get_properties(), but 87 provides more control over different property uses, while also making 88 it possible to return a temporary property table. 89 90 get_properties() is still used in cases where none of the above purposes 91 apply, but overloading get_properties() is generally discouraged. If you 92 want to provide purposes for general usage rather than just debugging or 93 serialization, please prefer using properly declared properties. 94 95 get_debug_info() is superseded by get_properties_for() with the 96 ZEND_PROP_PURPOSE_DEBUG purpose, but remains available for backwards- 97 compatibility reasons. However, while it is fine to define this handler, 98 it should never be directly called by consuming code. 99 100 The Z_OBJDEBUG_P macro has been removed. It should be replaced by calls to 101 zend_get_properties_for() with the ZEND_PROP_PURPOSE_DEBUG purpose: 102 103 // OLD 104 int is_temp; 105 HashTable *ht = Z_OBJDEBUG_P(obj, is_temp); 106 // ... 107 if (is_temp) { 108 zend_hash_destroy(ht); 109 FREE_HASHTABLE(ht); 110 } 111 112 // NEW 113 HashTable *ht = zend_get_properties_for(obj, ZEND_PROP_PURPOSE_DEBUG); 114 // ... 115 zend_release_properties(ht); 116 117 g. The following object handlers are now required (must be non-NULL): 118 119 * free_obj 120 * dtor_obj 121 * read_property 122 * write_property 123 * read_dimension 124 * write_dimension 125 * get_property_ptr_ptr 126 * has_property 127 * unset_property 128 * has_dimension 129 * unset_dimension 130 * get_properties 131 * get_method 132 * get_constructor 133 * get_class_name 134 * get_gc 135 136 It is recommended to initialize object handler structures by copying the 137 std object handlers and only overwriting those you want to change. 138 139 h. Opcache may make classes and op_arrays immutable. Such classes are marked 140 by ZEND_ACC_IMMUTABLE flag, they are not going to be copied from opcache 141 shared memory to process memory and must not be modified at all. 142 Few related data structures were changed to allow addressing mutable data 143 structures from immutable ones. This access is implemented through 144 ZEND_MAP_PTR... abstraction macros and, basically, uses additional level of 145 indirection. op_array->run_time_cache, op_array->static_variables_ptr and 146 class_entry->static_members_table now have to be accessed through 147 ZEND_MAP_PTR... macros. 148 It's also not allowed to change op_array->reserved[] handles of immutable 149 op_arrays. Instead, now you have to reserve op_array handle using 150 zend_get_op_array_extension_handle() during MINIT and access its value 151 using ZEND_OP_ARRAY_EXTENSION(op_array, handle). 152 153 i. The type of the escape parameter of php_fgetcsv() and php_fputcsv() has 154 been changed from char to int. This allows to pass the new constant macro 155 PHP_CSV_NO_ESCAPE to this parameter, to disable PHP's proprietary escape 156 mechanism. 157 158 j. add_get_assoc_*() and add_get_index_*() are removed. Use add_assoc*(), 159 add_index*() or zend_hash_*() API functions instead. 160 161 k. Complex class declaration opcodes ZEND_ADD_INTERFACE, ZEND_ADD_TRAIT, 162 ZEND_BIND_TRAITS and ZEND_VERIFY_ABSTRACT_CLASS were removed. Information 163 about interfaces and traits is kept in zend_class_entry structure and 164 actual linked performed by ZEND_DECLARE_...CLASS... opcode(s). 165 Linked classes have ZEND_ACC_LINKED flag set. 166 167 l. HASH_FLAG_INITIALIZED was reverted into HASH_FLAG_UNINITIALIZED. Special 168 HT_IS_INITIALIZED() and HT_INVALIDATE() macro were introduced to hide 169 implementation details. 170 171 m. The write_property() object handler now returns the assigned value (after 172 possible type coercions) rather than void. For extensions, it should 173 usually be sufficient to return whatever was passed as the argument. 174 175 n. Assignments to references now need to ensure that they respect property 176 types that affect the reference. This means that references should no 177 longer be directly assigned to, and instead a set of specialized macros of 178 the form ZEND_TRY_ASSIGN* needs to be used. You can find detailed porting 179 instructions as well as a compatibility shim in the wiki: 180 https://wiki.php.net/rfc/typed_properties_v2#assignments_to_references 181 182 o. ZEND_COMPILE_EXTENDED_INFO has been split into: 183 ZEND_COMPILE_EXTENDED_FCALL and ZEND_COMPILE_EXTENDED_STMT 184 This allows tooling to choose between profiling and debugging behaviour 185 ZEND_COMPILE_EXTENDED_INFO remains and preserves behaviour. 186 187 p. ZEND_EXT_BEGIN_FCALL is emitted after arguments are sent, this means 188 that handlers may access arguments. 189 190 q. ZEND_COMPILE_IGNORE_USER_FUNCTIONS and ZEND_COMPILE_IGNORE_INTERNAL_FUNCTIONS 191 are respected by zend_get_call_op such that when set, the only possible 192 call opcodes are ZEND_DO_FCALL and ZEND_DO_FCALL_BY_NAME, previously they 193 were ignored by zend_get_call_op. 194 195 r. TSRM adds tsrm_env_lock() and tsrm_env_unlock() for ZTS: 196 code that may change environ and may run concurrently with user code in ZTS 197 is expected to use this exclusion API to maintain as much safety as 198 reasonable. This results in "thread safe" getenv/putenv in Windows and 199 Unix, however functions that may read the environment without exclusion 200 still exist, for example: 201 - setlocale 202 - mktime 203 - tzset 204 The above is not an exhaustive list of such functions, while getenv/putenv 205 will behave as if they are safe, care should still be taken in 206 multi-threaded environments. 207 208 s. Correct support for typed properties requires the use of new macros to 209 assign values to references. For more information see 210 https://wiki.php.net/rfc/typed_properties_v2#impact_on_extensions. 211 212 t. convert_to_string() and zval_get_string() are now more likely to result in 213 an exception. For instructions on how to gracefully handle this see 214 https://wiki.php.net/rfc/tostring_exceptions#extension_guidelines. 215 216 u. The typedefs uint and ulong are no longer guaranteed to be available, and 217 have to be replaced with standard types. 218 219 v. Compound assignment opcodes were changed. Instead of ZEND_ASSIGN_ADD (and 220 others) with 0, ZEND_ASSIGN_DIM, ZEND_ASSIGN_OBJ or 221 ZEND_ASSIGN_STATIC_PROP in extended value, now we use ZEND_ASSIGN_OP, 222 ZEND_ASSIGN_DIM_OP, ZEND_ASSIGN_OBJ_OP and ZEND_ASSIGN_STATIC_PROP_OP with 223 ZEND_ADD (or other) in extended_value. 224 225 w. APACHE symbol has been removed and is no longer defined. 226 227 x. php_error_docref0() has been removed and renamed to php_error_docref(). 228 229 y. The read and write operations of php_stream_ops now return ssize_t, with 230 negative values indicating an error. 231 232======================== 2332. Build system changes 234======================== 235 236 a. Abstract 237 - The hash extension is now always available, meaning the --enable-hash 238 configure argument has been removed. 239 - The filter extension no longer exposes the --with-pcre-dir configure 240 argument and therefore allows shared builds with ./configure for Unix 241 builds. 242 - Symbols HAVE_DATE, HAVE_REFLECTION, and HAVE_SPL have been removed. It 243 should be considered to have these extensions always available. 244 - Removed unused build time symbols: PHP_ADA_INCLUDE, PHP_ADA_LFLAGS, 245 PHP_ADA_LIBS, PHP_APACHE_INCLUDE, PHP_APACHE_TARGET, PHP_FHTTPD_INCLUDE, 246 PHP_FHTTPD_LIB, PHP_FHTTPD_TARGET, PHP_CFLAGS, PHP_DBASE_LIB, 247 PHP_BUILD_DEBUG, PHP_GDBM_INCLUDE, PHP_IBASE_INCLUDE, PHP_IBASE_LFLAGS, 248 PHP_IBASE_LIBS, PHP_IFX_INCLUDE, PHP_IFX_LFLAGS, PHP_IFX_LIBS, 249 PHP_INSTALL_IT, PHP_IODBC_INCLUDE, PHP_IODBC_LFLAGS, PHP_IODBC_LIBS, 250 PHP_MSQL_LFLAGS, PHP_MSQL_INCLUDE, PHP_MSQL_LFLAGS, PHP_MSQL_LIBS, 251 PHP_MYSQL_INCLUDE, PHP_MYSQL_LIBS, PHP_MYSQL_TYPE, PHP_OCI8_SHARED_LIBADD, 252 PHP_ORACLE_SHARED_LIBADD, PHP_ORACLE_DIR, PHP_ORACLE_VERSION, 253 PHP_PGSQL_INCLUDE, PHP_PGSQL_LFLAGS, PHP_PGSQL_LIBS, PHP_SOLID_INCLUDE, 254 PHP_SOLID_LIBS, PHP_EMPRESS_INCLUDE, PHP_EMPRESS_LIBS, PHP_SYBASE_INCLUDE, 255 PHP_SYBASE_LFLAGS, PHP_SYBASE_LIBS, PHP_DBM_TYPE, PHP_DBM_LIB, 256 PHP_LDAP_LFLAGS, PHP_LDAP_INCLUDE, PHP_LDAP_LIBS. 257 - Removed unused symbols: HAVE_CURL_EASY_STRERROR, HAVE_CURL_MULTI_STRERROR, 258 HAVE_MPIR, HAVE_MBSTR_CN, HAVE_MBSTR_JA, HAVE_MBSTR_KR, HAVE_MBSTR_RU, 259 HAVE_MBSTR_TW. 260 261 b. Unix build system changes 262 - Added --ini-path and --ini-dir options to php-config. 263 - configure --help now also outputs --program-suffix and --program-prefix 264 information by using the Autoconf AC_ARG_PROGRAM macro. 265 - Obsolescent macros AC_FUNC_VPRINTF and AC_FUNC_UTIME_NULL have been 266 removed. Symbols HAVE_VPRINTF and HAVE_UTIME_NULL are no longer defined 267 since they are not needed on the current systems. 268 - Local PHP m4 unused or obsolete macros have been removed: 269 PHP_TARGET_RDYNAMIC, PHP_SOLARIS_PIC_WEIRDNESS, PHP_SYS_LFS, 270 PHP_AC_BROKEN_SPRINTF, PHP_EXTENSION, PHP_DECLARED_TIMEZONE, 271 PHP_CHECK_TYPES, PHP_CHECK_64BIT, PHP_READDIR_R_TYPE, 272 PHP_SETUP_KERBEROS. 273 - Local PHP_TM_GMTOFF m4 macro replaced with Autoconf's AC_CHECK_MEMBERS. 274 The HAVE_TM_GMTOFF symbol is replaced with HAVE_STRUCT_TM_TM_GMTOFF and 275 HAVE_TM_ZONE symbol is replaced with HAVE_STRUCT_TM_TM_ZONE. 276 - new --enable-rtld-now build option allow to switch dlopen behavior 277 from RTLD_LAZY to RTLD_NOW 278 - Minimum Bison version is 3.0+ for generating parser files. 279 - PHP_PROG_BISON macro now takes two optional arguments - minimum required 280 version and excluded versions that aren't supported. 281 - PHP_PROG_RE2C is not called in the generated configure.ac for extensions 282 anymore and now takes one optional argument - minimum required version. 283 - with-pcre-valgrind and with-valgrind are merged, and valgrind detected by 284 pkgconfig 285 - Removed unused AC_PROG_CC_C_O check and the NO_MINUS_C_MINUS_O symbol. 286 - Obsolescant checks for headers and functions that are part of C89 have 287 been removed. The following symbols are therefore no longer defined by the 288 PHP build system at the configure step and shouldn't be used anymore: 289 HAVE_SETLOCALE, HAVE_LOCALECONV, HAVE_STRSTR, HAVE_STRTOL, HAVE_STRBRK, 290 HAVE_PERROR, HAVE_STRFTIME, HAVE_TZNAME, HAVE_STDARG_H, HAVE_STRING_H, 291 HAVE_STDLIB_H, HAVE_SYS_VARARGS_H, HAVE_ASSERT_H, HAVE_SYS_DIR_H, 292 TM_IN_SYS_TIME, HAVE_STRTOD, HAVE_STRCOLL, HAVE_ERRNO_H, HAVE_MEMCPY, 293 HAVE_SNPRINTF, HAVE_STDIO_H, HAVE_STRPBRK, HAVE_TIME_H, HAVE_LIMITS_H, 294 HAVE_STRTOUL, HAVE_SYS_NDIR_H, HAVE_SYS_TIMES_H, PHP_HAVE_STDINT_TYPES, 295 HAVE_SIGNAL_H, HAVE_STRERROR. 296 - Removed unused check for dev/arandom and the HAVE_DEV_ARANDOM symbol. 297 - Remove unused functions checks: HAVE_MBSINIT, HAVE_MEMPCPY, HAVE_SETPGID, 298 HAVE_STRPNCPY, HAVE_STRTOULL, HAVE_VSNPRINTF, HAVE_CUSERID, HAVE_LRAND48, 299 HAVE_RANDOM, HAVE_SRAND48, HAVE_SRANDOM, HAVE_STRDUP, HAVE_GCVT, 300 HAVE_ISASCII, HAVE_LINK, HAVE_LOCKF, HAVE_SOCKOPT, HAVE_SETVBUF, HAVE_SIN, 301 HAVE_TEMPNAM. 302 - Unused check for struct cmsghdr and symbol HAVE_CMSGHDR have been removed. 303 - Unused ApplicationServices/ApplicationServices.h headers check and 304 HAVE_APPLICATIONSERVICES_APPLICATIONSERVICES_H symbol have been removed. 305 - PHP_DEBUG_MACRO macro has been removed. 306 - PHP_CHECK_CONFIGURE_OPTIONS macro has been removed. Default Autoconf's 307 --enable-option-checking=fatal option can be used in the configure step 308 to enable error when invalid options are used. 309 - Removed unused check and symbols HAVE_SHM_MMAP_ZERO, HAVE_SHM_MMAP_FILE. 310 - Removed unused check and symbol MISSING_MSGHDR_MSGFLAGS. 311 312 c. Windows build system changes 313 314 . Visual Studio 2019 is utilized for the Windows builds 315 . Removed unused defined symbol HAVE_LIBBIND. 316 317======================== 3183. Module changes 319======================== 320 321 a. ext/xml 322 - The public (internal) API of the ext/xml extension has been removed. All 323 functions and structures are private to the extension now. 324 325 b. ext/hash 326 - The hash extension is now always available, allowing extensions to rely 327 on its functionality to be available without compile time checks. 328
