xref: /PHP-7.4/UPGRADING.INTERNALS (revision 86aac3ee)
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