summaryrefslogtreecommitdiff
path: root/UPGRADING.INTERNALS
blob: c15cbef3b118c8fef84285a759b1283983687190 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
PHP 8.0 INTERNALS UPGRADE NOTES

1. Internal API changes
  a. Object Handlers API
  b. ZEND_OVERLOADED_FUNCTION and corresponding call_method() object handler
  c. TSRM changes
  d. get() and set() object handlers
  e. zend_parse_parameters 'L' specifier
  f. Arginfo argument types
  g. zend_free_op type and should_free argument of zend_get_zval_ptr()
  h. zend_value_error()
  i. get_closure() object handler
  j. compare_objects() and compare() object handlers
  k. The 'I' length modifier
  l. Some VM instructions switched to IS_TMP_VAR result instead of IS_VAR
  m. All internal functions must have arginfo
  n. zend_hash_sort compare function and zend_hash_sort signature change
  o. cast_object() object handler is now required
  p. ARG_COUNT() macro removed
  q. GC_COLLECTABLE flag
  r. Cannot implement Traversable only
  s. zend_fcall_info no_separation flag removed
  t. Signature changes
  u. Error Notification callbacks to replace zend_error_cb overwrite use-cases
  v. Removed Zend APIs
  w. Renamed Zend APIs
  x. ZEND_EXT_NOP no longer emitted

2. Build system changes
  a. Abstract
  b. Unix build system changes
  c. Windows build system changes

3. Module changes

========================
1. Internal API changes
========================

  a. The Object Handlers API was changed to receive zend_object* instead of
     zval* and zend_string* instead of zval* for property names. See also
     section t for other similar changes.

  b. ZEND_OVERLOADED_FUNCTION and corresponding call_method() object handler
     were removed. ZEND_INTERNAL_FUNCTION with ZEND_ACC_CALL_VIA_HANDLER and
     defined "handler" callback should be used instead. This "handler" callback
     should also take care about function cleanup. See ext/zend_test/test.c
     for example.

  c. The following things have been removed from TSRM:
      - TSRMLS_DC
      - TSRMLS_D
      - TSRMLS_CC
      - TSRMLS_C
      - TSRMLS_FETCH
      - TSRMLS_FETCH_FROM_CTX
      - TSRMLS_SET_CTX
      - tsrm_new_interpreter_context
      - tsrm_set_interpreter_context
      - tsrm_free_interpreter_context
      - support for GNUPTH, SGI ST, and BETHREADS

  d. The get() and set() object handlers have been removed. The get() handler
     can generally be replaced with cast_object(). Some uses of set() may be
     replaced by do_operation(). If set() was used to overload direct
     assignments using "=", then this is no longer supported and the
     functionality should be provided in some other way (for example, as
     modification of an object property).

  e. The zend_parse_parameters 'L' specifier and the Z_PARAM_STRICT_LONG()
     family of macros have been removed. Use 'l' and Z_PARAM_LONG() instead,
     which, despite the confusing name, actually have stricter input validation.

  f. Arginfo argument types for internal functions are no longer checked.
     Instead type checks should be performed using the zend_parse_parameters()
     or ZEND_PARSE_PARAMETERS_*() APIs.

  g. The zend_free_op type and the "should_free" and "type" arguments of
     zend_get_zval_ptr() were removed. It's possible to get the old
     "should_free" value using the following code:

         zval *ret = zend_get_zval_ptr(
             opline, opline->op1_type, &opline->op1, execute_data);
         zval *should_free = (op_type & (IS_TMP_VAR|IS_VAR)) ? ret : NULL;

  h. Added the zend_value_error() function, which is intended to be used
     to raise ValueError when inappropriate argument values are passed
     to functions.

  i. get_closure() object handlers now accept an additional zend_bool parameter
     `check_only`. If it is true, the handler is called to check whether the
     object is callable; in this case the handler should not throw an exception.

  j. compare_objects() handler was removed. Extensions should use compare() object
     handler instead and check if both arguments are objects and have the same
     compare handler, using ZEND_COMPARE_OBJECTS_FALLBACK() macro.

  k. The 'I' length modifier, used to denote 32 and 64bit integer from the custom
     snprintf and spprintf implementations has been removed.
     Use the ZEND_LONG_FMT, ZEND_ULONG_FMT and ZEND_XLONG_FMT macros defined in
     php-src/Zend/zend_long.h

     The 'v' format from the custom snprintf and spprintf implementations has
     been removed. Use the standard 's' format instead.

  l. Some VM instructions switched to IS_TMP_VAR result instead of IS_VAR.
     Actually, all assignments (ZEND_ASSIGN, ZEND_ASSIGN_DIM, ZEND_ASSIGN_OBJ,
     ZEND_ASSIGN_STATIC_PROP), all compound assignments (ZEND_ASSIGN_OP,
     ZEND_ASSIGN_DIM_OP, ZEND_ASSIGN_OBJ_OP, ZEND_ASSIGN_STATIC_PROP_OP) and all
     pre increments/decrements (ZEND_PRE_INC, ZEND_PRE_DEC, ZEND_PRE_INC_OBJ
     ZEND_PRE_DEC_OBJ, ZEND_PRE_INC_STATIC_PROP ZEND_PRE_DEC_STATIC_PROP).

  m. All internal functions and methods are now required to specify arginfo
     information, otherwise warnings will be thrown on startup.

  n. The zend_hash_sort and zend_hash_minmax APIs now accept a comparison
     function with the following signature:

         typedef int (*bucket_compare_func_t)(Bucket *a, Bucket *b);

     Previously compare_func_t was used, which accepted void pointers.
     Furthermore, the return type of zend_hash_sort and zend_ts_hash_sort has
     been changed from int to void; these functions always succeed.

  o. The cast_object() handler is now required, i.e. must be non-null. You can
     indicate that casting is not supported by always returning FAILURE.

  p. The ARG_COUNT() macro has been removed use ZEND_NUM_ARGS() instead.

  q. GC_COLLECTABLE flag was inverted into GC_NOT_COLLECTABLE.
     Assignments to GC_TYPE_INFO() might need to be changed to properly
     set the value of the GC_NOT_COLLECTABLE flag.

  r. Just for for userland classes, it is no longer allowed to implement only
     the Traversable interface. Instead, it is necessary to implement either
     Iterator or IteratorAggregate. You can do the latter by implementing
     zend_ce_aggregate and providing the following method implementation:

         ZEND_METHOD(MyClass, getIterator) {
             ZEND_PARSE_PARAMETERS_NONE();
             zend_create_internal_iterator_zval(return_value, ZEND_THIS);
         }

  s. The zend_fcall_info no_separation flag has been removed, and separation is
      never allowed. If you wish to pass (or allow passing) arguments by
      reference, explicitly create those arguments as references using
      ZEND_MAKE_REF. This removal also affects call_user_function_ex(), which
      should be replaced by call_user_function().

  t. The following ZEND_API function have changed signature:
     1. Void in Zend Engine 4.0:
        - add_assoc_*()
        - add_index_*()
        - add_property_*()
        - object_init()
        - zend_declare_class_constant*()
        - zend_declare_property*()
        - zend_startup_modules()
        - zend_wrong_parameters_none_error()
        - zend_fcall_info_argp()
        - zend_fcall_info_argv()
        - zend_fcall_info_argn()
        - zend_startup()
        - zend_set_memory_limit()
        - pass_two()
        - zend_startup_constants()
        - zend_shutdown_constants()
        - zend_startup_extensions_mechanism()
        - zend_startup_extensions()
        - zend_register_extension()
        - highlight_string()
        - zend_ini_startup()
        - zend_ini_shutdown()
        - zend_ini_global_shutdown()
        - zend_ini_deactivate()
        - zend_copy_ini_directives()
        - zend_prepare_string_for_scanning()
        - zend_init_rsrc_list()
        - zend_list_close()
        - zend_signal()
        - zend_sigaction()
        - zend_stack_init()
        - zend_stack_del_top()
        - zend_stack_destroy()
     2. Argument int to uint32_t in Zend Engine 4.0:
        - _zend_get_parameters_array_ex()
        - zend_copy_parameters_array()
        - zend_fcall_info_args_save()
        - zend_fcall_info_args_restore()
        - zend_fcall_info_argp()
        - zend_fcall_info_argv()
        - zend_fcall_info_argn()
        - zend_wrong_parameter*()
        - zend_wrong_callback_error()
        - zend_parse_arg_class()
     3. Argument int to bool in Zend Engine 4.0:
        - add_next_index_bool()
        - zend_register_class_alias_ex()
        - add_assoc_bool_ex()
        - add_index_bool()
        - zend_fcall_info_args_clear()
        - zend_set_local_var()
        - zend_set_local_var_str()
        - zend_parse_arg_*()
        - shutdown_memory_manager()
        - zend_memory_usage()
        - zend_memory_peak_usage()
        - zend_mm_shutdown()
        - zend_eval_string*()
        - zend_set_timeout()
        - _zend_hash_append_ex()
        - _zend_hash_append_ptr_ex()
        - zend_alter_ini_entry_ex()
        - (*zend_encoding_list_parser) typedef
        - zend_multibyte_parse_encoding_list()
        - zend_safe_address()
        - zend_string_tolower_ex()
        - zend_string_alloc()
        - zend_string_safe_alloc()
        - zend_string_init()
        - zend_string_dup()
        - zend_string_realloc()
        - zend_string_extend()
        - zend_string_truncate()
        - zend_string_safe_realloc()
        - zend_string_release_ex()
        - zend_ts_hash_merge()
        - zend_ts_hash_sort()
     4. Argument int to size_t in Zend Engine 4.0:
        - zend_set_hash_symbol()
     5. Argument zval* to zend_object* in Zend Engine 4.0:
        - zend_read_property()
        - zend_update_property()
        - zend_unset_property()
        - zend_call_method()
        - zend_objects_clone_obj()
        - zend_get_closure_method_def()
        - zend_throw_exception_hook()
        - zend_throw_exception_internal()
        - zend_get_exception_base()
     6. Argument zval* to zend_long in Zend Engine 4.0:
        - _php_math_longtobase()
     7. Return type from int to zend_result in Zend Engine 4.0:
        - (*stream_open_function) in _zend_utility_functions
        - (*zend_post_startup_cb)
        - (*zend_preload_autoload)
        - zend_execute_scripts()
        - zend_post_startup()
        - _zend_get_parameters_array_ex()
        - zend_copy_parameters_array()
        - zend_parse_parameters()
        - zend_parse_parameters_ex()
        - zend_parse_method_parameters()
        - zend_parse_method_parameters_ex()
        - zend_parse_method_parameters()
        - zend_register_functions()
        - zend_startup_module()
        - zend_startup_module_ex()
        - zend_register_class_alias_ex()
        - zend_disable_function()
        - zend_disable_class()
        - zend_update_class_constants()
        - zend_update_static_property*()
        - object_init_ex()
        - object_and_properties_init()
        - add_index_zval()
        - add_next_index_long_*()
        - array_set_zval_key()
        - _call_user_function_impl()
        - zend_fcall_info_*()
        - zend_call_function()
        - zend_set_hash_symbol()
        - zend_delete_global_variable()
        - zend_set_local_var()
        - zend_set_local_var_str()
        - zend_forbid_dynamic_call()
        - zend_get_default_from_internal_arg_info()
        - zend_try_assign_typed_ref*()
        - zend_ast_evaluate()
        - zend_startup_builtin_functions()
        - do_bind_function()
        - do_bind_class()
        - zend_unmangle_property_name_ex()
        - zend_register_auto_global()
        - zend_register_constant()
        - zend_exception_error()
        - zend_eval_string*()
        - zend_undefined_offset_write()
        - zend_undefined_index_write()
        - zval_update_constant(_ex)()
        - zend_load_extension()
        - zend_load_extension_handle()
        - zend_hash_del(_ind)()
        - zend_hash_str_del(_ind)()
        - zend_hash_index_del()
        - zend_hash_move_forward_ex()
        - zend_hash_move_backward_ex()
        - zend_hash_get_current_key_ex()
        - zend_hash_get_current_key_type_ex()
        - zend_symtable_del(_ind)()
        - zend_symtable_str_del(_ind)()
        - highlight_file()
        - zend_do_link_class()
        - zend_alter_ini_entry*()
        - zend_restore_ini_entry()
        - zend_ini_register_displayer()
        - zend_ini_open_file_for_scanning()
        - zend_ini_prepare_string_for_scanning()
        - zend_user_it_valid()
        - zend_create_internal_iterator_zval()
        - zend_multibyte_set_filter()
        - zend_lex_tstring()
        - _zend_module_entry module_startup_func, module_shutdown_func,
          request_startup_func, request_shutdown_func, and post_deactivate_func function pointers
        - (*zend_encoding_list_parser) typedef
        - (*zend_encoding_internal_encoding_setter) typedef
        - zend_multibyte_set_functions()
        - zend_multibyte_set_script_encoding_by_string()
        - add_function()
        - sub_function()
        - mul_function()
        - pow_function()
        - div_function()
        - mod_function()
        - boolean_xor_function()
        - boolean_not_function()
        - bitwise_not_function()
        - bitwise_or_function()
        - bitwise_and_function()
        - bitwise_xor_function()
        - shift_left_function()
        - shift_right_function()
        - concat_function()
        - is_equal_function(
        - is_identical_function()
        - is_not_identical_function()
        - is_not_equal_function()
        - is_smaller_function()
        - is_smaller_or_equal_function(zv
        - increment_function()
        - decrement_function()
        - zend_stream_open()
        - zend_stream_fixup()
        - zend_ts_hash_del()
        - zend_ts_hash_index_del()
     8. Return type from int to bool in Zend Engine 4.0:
        - zend_make_printable_zval()
        - zend_parse_arg_*()
        - is_zend_mm()
        - is_zend_ptr()
        - zend_mm_is_custom_heap()
        - (*zend_mm_chunk_truncate_t)
        - (*zend_mm_chunk_extend_t)
        - zend_bitset_empty()
        - zend_is_smart_branch()
        - zend_check_arg_send_type()
        - zend_verify_const_access()
        - zend_gdb_register_code()
        - zend_gdb_present()
        - _zend_handle_numeric_str(_ex)()
        - zend_hash_exists_ind()
        - zend_hash_str_exists_ind()
        - zend_symtable_exists(_ind)()
        - zend_symtable_str_exists()
        - (*zend_encoding_lexer_compatibility_checker)
        - zend_object_is_true()
        - i_zend_is_true()
        - zendi_smart_streq()
        - zend_stack_is_empty()
        - zend_ts_hash_exists()
        - zend_ts_hash_index_exists()
     9. Argument void to const char* in Zend Engine 4.0:
        - zend_get_op_array_extension_handle()
     10. Argument zend_extension to const char* in Zend Engine 4.0:
        - zend_get_resource_handle()
     11. Argument const char * to HMODULE in Zend Engine 4.0:
        - php_win32_image_compatible()
     12. const char * argument dropped in Zend Engine 4.0:
        - php_win32_crt_compatible()

  u. Instead of overwriting zend_error_cb extensions with debugging, monitoring
     use-cases catching Errors/Exceptions are strongly encouraged to use
	 the new error observer API instead.

	 Error observering callbacks are guaranteed to be called regardless of
	 the users error_reporting setting or userland error handler return values.

     Register observer callbacks during MINIT of an extension:

		void my_error_observer_cb(int type,
			const char *error_filename,
			uint32_t error_lineno,
			zend_string *message) {
		}
		zend_observer_error_register(my_error_observer_cb);

  v. The following APIs have been removed from the Zend Engine:
     - zend_ts_hash_init_ex(), drop the last argument and use zend_ts_hash_init() instead
     - zend_hash_init_ex(), drop the last argument and use zend_hash_init() instead
     - zval_internal_dtor(), use zval_internal_ptr_dtor() instead
     - zval_dtor_func(), use rc_dtor_func() instead
     - zval_ptr_dtor_wrapper(), use zval_ptr_dtor() instead
     - zval_internal_ptr_dtor_wrapper(), use zval_internal_ptr_dtor() instead

  w. The following APIs have been renamed:
     - _zend_ts_hash_init() to zend_ts_hash_init()

  x. In COMPILE_EXTENDED_STMT mode, a ZEND_EXT_NOP opcode will no longer be
     generated at the start of a function. Use the new observer APIs or hook
     into zend_execute_ex instead.

========================
2. Build system changes
========================

  a. Abstract
    1.  Symbol HAVE_HASH_EXT is removed and is no longer defined. It should be
        considered to have hash extension always available since PHP 7.4.

    2.  Symbol HAVE_PCRE is removed and is no longer defined. It should be
        considered to have pcre extension always available since PHP 7.4.

    3.  Symbol HAVE_LOCALE_H has been removed and is no longer defined.

    4.  --disable-inline-optimization (which actually disabled all compiler
        optimizations) has been removed. If you wish to build PHP on a host
        with extremely constrained memory, and compilation fails with an "out
        of memory" message, add "-O0" to CFLAGS.

    5.  build system and provider are displayed in phpinfo from environment:
        - PHP_BUILD_SYSTEM (default is same as PHP_UNAME)
        - PHP_BUILD_PROVIDER (no default)

  b. Unix build system changes

    1.  --enable-maintainer-zts is renamed --enable-zts for parity with Windows
        and as recognition that ZTS is not a "maintainer" or experimental
        feature.

    2.  The PHP_CHECK_GCC_ARG() m4 macro has been removed in favor of
        AX_CHECK_COMPILE_FLAG().

    3. The 6th argument of PHP_ADD_SOURCES_X has been removed.

    4. The 'special-flags' (3rd) argument of PHP_ADD_SOURCES_X are
       now appended instead of prepended to previous compiler flags.
       This means compiler flags passed to PHP_NEW_EXTENSION and PHP_ADD_SOURCES
       are now appended, this allows to disable compiler flags set by Zend/Zend.m4
       (e.g. disable certain compiler flags enabled by -Wextra)

  c. Windows build system changes

    - The configuration option --enable-crt-debug has been removed. The VC
      debug heap can now be enabled for debug builds by setting the environment
      variable PHP_WIN32_DEBUG_HEAP to a non-negative number before PHP process
      startup.

========================
3. Module changes
========================