Commit fdc5b8f952c for php.net
commit fdc5b8f952cf5ea2a1b9b838f8e36847e2f76b1b
Author: Gina Peter Banyard <girgias@php.net>
Date: Sun Jul 19 16:40:18 2026 +0100
Reorganise UPGRADING.INTERNALS to be more legible (#22808)
Split API changes into Removed, Changed, and Added
diff --git a/UPGRADING.INTERNALS b/UPGRADING.INTERNALS
index 237c3cb2378..fe6946faddd 100644
--- a/UPGRADING.INTERNALS
+++ b/UPGRADING.INTERNALS
@@ -14,13 +14,8 @@ PHP 8.6 INTERNALS UPGRADE NOTES
1. Internal API changes
========================
- . ZSTR_INIT_LITERAL(), zend_string_starts_with_literal(), and
- zend_string_starts_with_literal_ci() now support strings containing NUL
- bytes. Passing non-literal char* is no longer supported.
- . Added zend_string_equals_cstr_ci().
+- Removed:
. The misnamed ZVAL_IS_NULL() has been removed. Use Z_ISNULL() instead.
- . New zend_class_entry.ce_flags2 and zend_function.fn_flags2 fields were
- added, given the primary flags were running out of bits.
. The zval_is_true() alias of zend_is_true() has been removed. Call
zend_is_true() directly instead.
. The _zval_get_*() compatibility macros for PHP 7.2 have been removed
@@ -42,45 +37,13 @@ PHP 8.6 INTERNALS UPGRADE NOTES
needs to be obtained use the zend_get_callable_zval_from_fcc() function
instead. If this was used to store a callable, then an FCC should be
stored instead.
- . The zend_active_function{_ex}() functions now return a const zend_function
- pointer.
- . The zend_get_call_trampoline_func() API now takes the __call or
- __callStatic zend_function* instead of a CE and a boolean argument.
+ . The zend_exception_save() and zend_exception_restore() functions were
+ removed.
. The zend_set_hash_symbol() API has been removed.
- . Added zend_hash_str_lookup().
. The WRONG_PARAM_COUNT and ZEND_WRONG_PARAM_COUNT() macros have been
removed. Call zend_wrong_param_count(); followed by RETURN_THROWS();
instead.
. PHP_HAVE_STREAMS macro removed from <php.h>.
- . zend_function.arg_info is now always a zend_arg_info*. Before, it was a
- zend_internal_arg_info on internal functions, unless the
- ZEND_ACC_USER_ARG_INFO flag was set.
- . Added zend_ast_call_get_args() to fetch the argument node from any call
- node.
- . The zend_exception_save() and zend_exception_restore() functions were
- removed.
- . Internal functions that return by reference are now expected to
- automatically unwrap references when the result of the call is stored in an
- IS_TMP_VAR variable. This may be achieved by calling the
- zend_return_unwrap_ref() function.
- . The php_math_round_mode_from_enum() function now takes a
- zend_enum_RoundingMode parameter.
- . Added Z_PARAM_ENUM().
- . Added zend_enum_fetch_case_id().
- . Added zend_enum_get_case_by_id().
- . Added zend_bin2hex() and zend_bin2hex_str() as helper functions to remove
- dependencies on /ext/hash in various extensions.
- . ZEND_INI_GET_ADDR() is now a void* pointer instead of a char* pointer. This
- more correctly represents the generic nature of the returned pointer and
- allows to remove explicit casts, but possibly breaks pointer arithmetic
- performed on the result.
- . The zend_dval_to_lval_cap() function no longer takes a second
- zend_string* parameter.
- . EG(in_autoload) was renamed to EG(autoload_current_classnames) and no
- longer is a pointer, but a directly embedded HashTable struct.
- . Added a C23_ENUM() helper macro to define forward-compatible fixed-size
- enums.
- . Extended php_stream_filter_ops with seek method.
. The INI_STR(), INI_INT(), INI_FLT(), and INI_BOOL() macros have been
removed. Instead new zend_ini_{bool|long|double|str|string}_literal()
macros have been added. This fixes an internal naming inconsistency as
@@ -90,13 +53,8 @@ PHP 8.6 INTERNALS UPGRADE NOTES
unused. If this behaviour is required fall back to the zend_ini_*
functions.
. The unused ZEND_AST_PARENT_PROPERTY_HOOK_CALL has been removed.
- . ZEND_AST_METHOD_REFERENCE has been renamed to
- ZEND_AST_TRAIT_METHOD_REFERENCE.
. The EMPTY_SWITCH_DEFAULT_CASE() macro has been removed. Use
default: ZEND_UNREACHABLE(); instead.
- . Functions using zend_forbid_dynamic_call() *must* be flagged with
- ZEND_ACC2_FORBID_DYN_CALLS (@forbid-dynamic-calls in stubs). In debug
- builds, failing to include that flag will lead to assertion failures.
. The ZEND_RESULT_CODE type has been removed. Use zend_result directly.
. The zend_parse_parameters_none_throw(), zend_parse_parameters_throw(),
and ZEND_PARSE_PARAMS_THROW have been removed due to being misleading,
@@ -115,16 +73,63 @@ PHP 8.6 INTERNALS UPGRADE NOTES
have been removed, because they are unsafe by relying on the zvals
having a specific type. Use zend_binary_strcmp() / zend_binary_strncmp(),
string_compare_function() or similar instead.
- . Added zend_fcall_info.consumed_args together with
- zend_fci_consumed_arg(), which allows moving a selected callback argument
- instead of copying it in zend_call_function(). Currently only a single
- consumed argument is supported.
- . Added ZEND_CONTAINER_OF().
. The OPENBASEDIR_CHECKPATH() compatibility macro has been removed, instead
use php_check_open_basedir() directly.
. The Z_CONSTANT(), Z_CONSTANT_P(), Z_OPT_CONSTANT(), and
Z_OPT_CONSTANT_P() macros have been removed. Check for IS_CONSTANT_AST
directly.
+ . The {_}php_stream_fopen_with_path() functions have been removed as they are
+ unused.
+
+- Changed:
+ . Internal functions that return by reference are now expected to
+ automatically unwrap references when the result of the call is stored in an
+ IS_TMP_VAR variable. This may be achieved by calling the
+ zend_return_unwrap_ref() function.
+ . ZEND_AST_METHOD_REFERENCE has been renamed to
+ ZEND_AST_TRAIT_METHOD_REFERENCE.
+ . Functions using zend_forbid_dynamic_call() *must* be flagged with
+ ZEND_ACC2_FORBID_DYN_CALLS (@forbid-dynamic-calls in stubs). In debug
+ builds, failing to include that flag will lead to assertion failures.
+ . The zend_get_call_trampoline_func() API now takes the __call or
+ __callStatic zend_function* instead of a CE and a boolean argument.
+ . ZSTR_INIT_LITERAL(), zend_string_starts_with_literal(), and
+ zend_string_starts_with_literal_ci() now support strings containing NUL
+ bytes. Passing non-literal char* is no longer supported.
+ . Added zend_string_equals_cstr_ci().
+ . The zend_active_function{_ex}() functions now return a const zend_function
+ pointer.
+ . zend_function.arg_info is now always a zend_arg_info*. Before, it was a
+ zend_internal_arg_info on internal functions, unless the
+ ZEND_ACC_USER_ARG_INFO flag was set.
+ . ZEND_INI_GET_ADDR() is now a void* pointer instead of a char* pointer. This
+ more correctly represents the generic nature of the returned pointer and
+ allows to remove explicit casts, but possibly breaks pointer arithmetic
+ performed on the result.
+ . The zend_dval_to_lval_cap() function no longer takes a second
+ zend_string* parameter.
+ . EG(in_autoload) was renamed to EG(autoload_current_classnames) and no
+ longer is a pointer, but a directly embedded HashTable struct.
+ . Extended php_stream_filter_ops with seek method.
+
+- Added:
+ . New zend_class_entry.ce_flags2 and zend_function.fn_flags2 fields were
+ added, given the primary flags were running out of bits.
+ . Added zend_hash_str_lookup().
+ . Added zend_ast_call_get_args() to fetch the argument node from any call
+ node.
+ . Added Z_PARAM_ENUM().
+ . Added zend_enum_fetch_case_id().
+ . Added zend_enum_get_case_by_id().
+ . Added zend_bin2hex() and zend_bin2hex_str() as helper functions to remove
+ dependencies on /ext/hash in various extensions.
+ . Added a C23_ENUM() helper macro to define forward-compatible fixed-size
+ enums.
+ . Added zend_fcall_info.consumed_args together with
+ zend_fci_consumed_arg(), which allows moving a selected callback argument
+ instead of copying it in zend_call_function(). Currently only a single
+ consumed argument is supported.
+ . Added ZEND_CONTAINER_OF().
. Added zend_reflection_property_set_raw_value_without_lazy_initialization(),
zend_reflection_property_set_raw_value() to expose the functionality of
ReflectionProperty::setRawValueWithoutLazyInitialization() and
@@ -140,8 +145,6 @@ PHP 8.6 INTERNALS UPGRADE NOTES
file descriptors using the most efficient platform primitive available
(sendfile, splice, copy_file_range, TransmitFile), and is now used by
php_stream_copy_to_stream_ex(). The mmap-based copy fallback was removed.
- . The {_}php_stream_fopen_with_path() functions have been removed as they are
- unused.
========================
2. Build system changes
@@ -225,6 +228,8 @@ PHP 8.6 INTERNALS UPGRADE NOTES
. _php_error_log() now accepts zend_string* values instead of char*.
. _php_error_log_ex() has been removed.
. php_mail()'s extra_cmd parameter is now a zend_string*.
+ . The php_math_round_mode_from_enum() function now takes a
+ zend_enum_RoundingMode parameter.
- ext/uri:
. The value parameter of the php_uri_property_handler_write callback is now