php-src/UPGRADING.INTERNALS
Peter Kokot 8fe127a55e
Autotools: Enhance PHP_EVAL_LIBLINE M4 macro (#14924)
PHP_EVAL_LIBALINE macro processes the given libraries flags (-l) and/or
library paths flags (-L) and appends the -l flags to either LIBS or the
given *_SHARED_LIBADD variables. The -L flags are appended to the
LDFLAGS. The new 3rd argument enables appending libraries to the given
variable in the 2nd argument without manual setting whether the
extension is shared. For example, to simplify usage in SAPIs where
additional libraries need to be appended but they shouldn't go to the
global LIBS. This can be then used in PHP-FPM SAPI to link apparmor,
SELinux, systemd, etc.
2024-07-12 23:48:36 +02:00

322 lines
16 KiB
Plaintext

PHP 8.4 INTERNALS UPGRADE NOTES
1. Internal API changes
2. Build system changes
3. Module changes
4. OpCode changes
5. SAPI changes
========================
1. Internal API changes
========================
* zend_register_module_ex() now takes an additional int module_type argument.
This function will also assign the module number and type, there is no need
to do this at the call site anymore. Writing the handle should happen after
successful registration.
* ZPP now accepts a F or Z_PARAM_FUNC_NO_TRAMPOLINE_FREE type check.
This is identical to the 'f' or Z_PARAM_FUNC type check, except the FCC is
always initialized because it doesn't free trampolines.
Trampolines MUST be freed using zend_release_fcall_info_cache() or consumed.
Z_PARAM_FUNC_EX2 was added as well with the same arguments as Z_PARAM_FUNC_EX
plus an additional argument free_trampoline.
* The zend_object_iterator_funcs valid member has changed its signature from
int(*)(zend_object_iterator *) to zend_result(*)(zend_object_iterator *) to
be more in line with what callbacks are returning.
* The backwards compatibility headers ext/standard/{php_lcg.h,php_mt_rand.h,
php_rand.h,php_random.h} have been removed. Include ext/random/php_random.h
directly.
* The zend_*printf family of functions now supports the "%S" modifier to print
out zend_string*. This won't cut off the string if it embeds a NUL byte.
* The inet_aton() and win32/inet.h have been removed. Use platform-agnostic
inet_pton() from arpa/inet.h or ws2tcpip.h on Windows.
* zend_mm_set_custom_debug_handlers() has been removed from ZendMM, use
zend_mm_set_custom_handlers() instead which now supports DEBUG builds
* zend_mm_set_custom_handlers() has changed its signature from
void()(zend_mm_heap *heap,
void* (*_malloc)(size_t),
void (*_free)(void*),
void* (*_realloc)(void*, size_t))
to
void()(zend_mm_heap *heap,
void* (*_malloc)(size_t ZEND_FILE_LINE_DC ZEND_FILE_LINE_ORIG_DC),
void (*_free)(void* ZEND_FILE_LINE_DC ZEND_FILE_LINE_ORIG_DC),
void* (*_realloc)(void*, size_t ZEND_FILE_LINE_DC ZEND_FILE_LINE_ORIG_DC))
* zend_mm_get_custom_handlers() has changed its signature from
void()(zend_mm_heap *heap,
void* (**_malloc)(size_t),
void (**_free)(void*),
void* (**_realloc)(void*, size_t))
to
void()(zend_mm_heap *heap,
void* (**_malloc)(size_t ZEND_FILE_LINE_DC ZEND_FILE_LINE_ORIG_DC),
void (**_free)(void* ZEND_FILE_LINE_DC ZEND_FILE_LINE_ORIG_DC),
void* (**_realloc)(void*, size_t ZEND_FILE_LINE_DC ZEND_FILE_LINE_ORIG_DC))
* Added gc and shutdown custom handlers, settable via
zend_mm_set_custom_handlers_ex()
* __zend_malloc() has changed their signature from
void(*)(size_t) to
void(*)(size_t ZEND_FILE_LINE_DC ZEND_FILE_LINE_ORIG_DC)
* __zend_calloc() has changed their signature from
void(*)(size_t, size_t) to
void(*)(size_t, size_t ZEND_FILE_LINE_DC ZEND_FILE_LINE_ORIG_DC)
* __zend_realloc() has changed their signature from
void(*)(void *, size_t) to
void(*)(void *, size_t ZEND_FILE_LINE_DC ZEND_FILE_LINE_ORIG_DC)
* zend_observer_remove_begin_handler() and zend_observer_remove_end_handler()
got each a new parameter returning an observer which must be called, if the
removal happened during observer execution.
* zend_get_internal_function_extension_handle[s]() must now be used over
zend_get_op_array_extension_handle[s]() when registering run_time_cache slots
for internal functions. If you need a cache slot for both internal and user
functions, you may obtain a slot for each through the corresponding function.
* zend_is_true now returns bool rather than int. Note that on PHP 8 this has
always returned 0 or 1, so conversion should be trivial.
* Added zend_hash_get_current_pos_ex() variant of zend_hash_get_current_pos().
========================
2. Build system changes
========================
a. Abstract
- The configure option --with-imap has been removed.
- The configure option --with-mhash emits deprecation warning.
- The configure option --with-pdo-oci has been removed.
- The configure option --with-pspell has been removed.
- Symbol SIZEOF_SHORT removed (size of 2 on 32-bit and 64-bit platforms).
- Symbol DBA_CDB_MAKE removed in ext/dba.
- Symbol HAVE_LIBM has been removed.
- Symbol HAVE_INET_ATON has been removed.
- The Zend/zend_istdiostream.h header has been removed.
b. Unix build system changes
- The configure option --with-imap-ssl has been removed.
- The configure option --with-oci8 has been removed.
- The configure option --with-zlib-dir has been removed.
- The configure option --with-kerberos has been removed.
- The configure option --with-openssl-dir has been removed. SSL support in
ext/ftp and ext/mysqlnd is enabled implicitly, when building with
ext/openssl (--with-openssl), or explicitly by using new configure options
--with-ftp-ssl and --with-mysqlnd-ssl.
- COOKIE_IO_FUNCTIONS_T symbol has been removed (use cookie_io_functions_t).
- HAVE_SOCKADDR_UN_SUN_LEN symbol renamed to HAVE_STRUCT_SOCKADDR_UN_SUN_LEN.
- HAVE_UTSNAME_DOMAINNAME symbol renamed to HAVE_STRUCT_UTSNAME_DOMAINNAME.
- PHP_CHECK_IN_ADDR_T M4 macro and 'in_addr_t' fallback definition to 'u_int'
removed (use AC_CHECK_TYPES Autoconf macro instead).
- HAVE_ODBC2 symbol has been removed in ext/odbc.
- Removed linking with obsolete dnet_stub library in ext/pdo_dblib.
- Removed checking and linking with obsolete libbind for some functions.
- Symbol HAVE_JSON has been removed (ext/json is always available since PHP
8.0).
- Symbol DARWIN has been removed (use __APPLE__ to target Darwin systems).
- Symbol MISSING_FCLOSE_DECL and M4 macro PHP_MISSING_FCLOSE_DECL removed.
- Symbol HAVE_BSD_ICONV has been removed.
- Symbol ZEND_FIBER_ASM has been removed.
- Symbols HAVE_DLOPEN and HAVE_DLSYM have been removed.
- Symbol HAVE_MYSQL has been removed.
- Symbol HAVE_PDO_SQLITELIB has been removed.
- Symbol HAVE_WAITPID has been removed.
- Symbol HAVE_LIBPQ has been removed.
- Symbols HAVE_LIBRT and HAVE_TIMER_CREATE removed.
- Symbols PHP_FPM_SYSTEMD, PHP_FPM_USER, and PHP_FPM_GROUP removed.
- Symbol PTHREADS has been removed.
- Symbol HAVE_STRPTIME_DECL_FAILS has been removed (use HAVE_DECL_STRPTIME).
- Symbol HAVE_PHPDBG has been removed.
- Symbols PHP_HAVE_AVX512_SUPPORTS and PHP_HAVE_AVX512_VBMI_SUPPORTS are now
either defined to 1 or undefined.
- M4 macro PHP_DEFINE (atomic includes) removed (use AC_DEFINE and config.h).
- M4 macro PHP_WITH_SHARED has been removed (use PHP_ARG_WITH).
- M4 macro PHP_STRUCT_FLOCK has been removed (use AC_CHECK_TYPES).
- M4 macro PHP_SOCKADDR_CHECKS has been removed (use AC_CHECK_TYPES and
AC_CHECK_MEMBERS).
- M4 macro PHP_CHECK_GCC_ARG has been removed since PHP 8.0 (use
AX_CHECK_COMPILE_FLAG).
- M4 macro PHP_PROG_RE2C got a new 2nd argument to define common default re2c
command-line options substituted to the Makefile RE2C_FLAGS variable.
- M4 macros PHP_CHECK_BUILTIN_* have been removed in favor of
PHP_CHECK_BUILTIN and all PHP_HAVE_BUILTIN_* symbols changed to be either
undefined or defined to 1 whether compiler supports the builtin.
- Added php-config --lib-dir and --lib-embed options for PHP embed SAPI.
- PDO extensions in php-src don't have the include flag -I$pdo_cv_inc_path
directory anymore.
- M4 macro PHP_SETUP_OPENSSL doesn't accept the 3rd argument anymore.
- M4 macro PHP_EVAL_LIBLINE got a new 3rd argument to override the ext_shared
checks.
- TSRM/tsrm.m4 file and its TSRM_CHECK_PTHREADS M4 macro have been removed.
- Added pkg-config support to find libpq for the pdo_pgsql and pgsql
extensions. The libpq paths can be customized with the PGSQL_CFLAGS and
PGSQL_LIBS environment variables. When a directory argument is provided to
configure options (--with-pgsql=DIR or --with-pdo-pgsql=DIR), it will be
used instead of the pkg-config search.
- Removed BC enable_pear variable check due to --enable-pear configure option
once used (use with_pear variable name).
c. Windows build system changes
- The configure options --with-oci8-11g, --with-oci8-12c, --with-oci8-19,
--enable-apache2-2handler have been removed.
- The configure option --enable-apache2-4handler is now an alias for the
preferred --enable-apache2handler.
- Added Bison flag '-Wall' when generating lexer files as done in *nix build
system.
- HAVE_WIN32_NATIVE_THREAD, USE_WIN32_NATIVE_THREAD, ENABLE_THREADS symbols
in ext/mbstring/libmbfl removed.
- FIBER_ASSEMBLER and FIBER_ASM_ARCH Makefile variables removed in favor of
PHP_ASSEMBLER and FIBER_ASM_ABI.
- HAVE_PHP_SOAP symbol renamed to HAVE_SOAP.
- Unused symbols CONFIGURATION_FILE_PATH, DISCARD_PATH, HAVE_ERRMSG_H,
HAVE_REGCOMP, HAVE_RINT, NEED_ISBLANK, PHP_URL_FOPEN, REGEX, HSREGEX,
USE_CONFIG_FILE have been removed.
- The HAVE_OPENSSL symbol has been removed.
- The HAVE_OPENSSL_EXT symbol is now consistently defined to value 1 whether
the openssl extension is available either as shared or built statically.
- Added configure option --enable-phpdbg-debug to build phpdbg in debug mode.
- The win32/build/libs_version.txt file has been removed.
========================
3. Module changes
========================
a. ext/dom
- dom_read_t and dom_write_t now expect the function to return zend_result
instead of int.
- The macros DOM_NO_ARGS() and DOM_NOT_IMPLEMENTED() have been removed.
- New public APIs are available to handle callbacks from XPath, see
xpath_callbacks.h.
- Added public APIs to manipulate namespace data, see namespace_compat.h.
- php_dom_create_object() now no longer accepts a NULL obj argument.
- Removed the `ret` argument from the DOM_RET_OBJ macro, use the return
value instead.
- Removed DOM_XMLNS_NAMESPACE from xml_common.h. Use DOM_XMLNS_NS_URI
from namespace_compat.h instead.
- Added php_dom_get_ns_mapper(), php_dom_next_in_tree_order(),
php_dom_follow_spec_doc_ref(), and php_dom_follow_spec_doc_ref().
b. ext/random
- The macro RAND_RANGE_BADSCALING() has been removed. The implementation
should either be inlined and undefined behavior fixed or it should be
replaced by a non-biased scaler.
- The php_srand() and php_rand() functions have been removed. These were
slim wrappers around the corresponding php_mt_srand() and php_mt_rand()
function since PHP 7.1, but using zend_long instead of uint32_t as their
input/output types. This made their behavior incompatible between 32-bit
and 64-bit builds of PHP. Users of these functions are encouraged to
migrate to one of the more modern engines provided since PHP 8.2. If that
is not possible, due to backwards compatibility requirements, then the
php_mt_srand() and php_mt_rand() functions should be called directly and
the values appropriately casted.
- The PHP_RAND_MAX and RAND_MAX constants corresponding to the removed
php_rand() have also been removed.
- The generate member of a php_random_algo is now expected to return
the new php_random_result struct, replacing the last_generated_size
member of the php_random_status struct and the generate_size member of
the php_random_algo struct.
- The php_random_status struct has been removed, since the previous change
reduced it to a single void* member containing the actual state, resulting
in needless indirection. Functions taking a php_random_algo struct pointer
and a php_random_status struct pointer as separate parameters now take a
single php_random_algo_with_state struct by value, making it easier to
pass around the state with its associated algorithm and thus reducing
the chance for mistakes.
- The seed member of a php_random_algo has been removed. As a replacement
engine-specific seeding functions are now exposed. This change allows
users to better take engine-specific behavior into account. As an example
Mt19937 ignored the upper half of the seed parameter of the generic
seeding function.
- The CSPRNG API (php_random_(bytes|int)_*) is now provided by the new
and much smaller php_random_csprng.h header. The new header is included
in php_random.h for compatibility with existing users.
- A new php_random_generate_fallback_seed() function has been added as a
replacement for the generically named GENERATE_SEED(). The internal
implementation has been improved to generate better seeds, however any
users should use the opportunity to verify that seeding is first
attempted using the CSPRNG for better output size flexibility.
c. ext/xsl
- The function php_xsl_create_object() was removed as it was not used
nor exported.
d. ext/libxml
- Added php_libxml_pretend_ctx_error_ex() to emit errors as if they had come
from libxml.
- Added php_libxml_error_handler_va() to pass libxml errors, and
corresponding php_libxml_error_level enum.
- Removed the "properties" HashTable field from php_libxml_node_object.
- Added a way to attached private data to a php_libxml_ref_obj.
- Added a way to fix a class type onto php_libxml_ref_obj.
- Added a way to record quirks mode in php_libxml_ref_obj.
- Added php_libxml_uses_internal_errors().
- Added a way to override document handlers (e.g. serialization) with
php_libxml_document_handlers.
e. ext/date
- Added the php_format_date_ex() API to format instances of php_date_obj.
- Added the php_date_initialize_from_ts_long() and
php_date_initialize_from_ts_double() to initialize a php_date_obj with
the given unix timestamp using GMT +00:00.
f. ext/pcre
- php_pcre_match_impl() now no longer has a use_flags argument.
When flags should be ignored, pass 0 to the flags argument.
- php_pcre_match_impl() and pcre_get_compiled_regex_cache_ex() now use
proper boolean argument types instead of integer types.
- pcre_get_compiled_regex_cache_ex() now provides an option to collect extra
options (from modifiers used in the expression, for example), and calls
pcre2_set_compile_extra_options() with those options.
g. ext/standard
- Added the php_base64_encode_ex() API with flag parameters, value can be
PHP_BASE64_NO_PADDING to encode without the padding character '='.
- The php_escape_shell_cmd() now takes a zend_string* instead of a char*
Moreover, providing it with a binary safe string is the responsibility of
the caller now.
- The php_escape_shell_arg() now takes a zend_string* instead of a char*
Moreover, providing it with a binary safe string is the responsibility of
the caller now.
h. ext/session
- Added the php_get_session_status() API to get the session status, which is
equivalent to reading PS(session_status) but works with shared objects too.
- Added the php_get_session_var_str() API to set a session variable without
needing to create a zend_string.
- The ext/session/php_session.h doesn't transitively include the
ext/hash/php_hash.h header anymore.
i. ext/xml
- Made the expat compatibility wrapper XML_GetCurrentByteIndex return a long
instead of an int. This corresponds to the XML_Index type when
XML_LARGE_SIZE is not used in expat.
========================
4. OpCode changes
========================
* New FRAMELESS_ICALL_[0,3] opcodes for faster internal function calls have been
added. These opcodes don't create a stack frame, but pass arguments via opcode
operands. They only work for functions that are known at compile-time, and
that provide a frameless handler (search for usages of the
ZEND_FRAMELESS_FUNCTION macro).
========================
5. SAPI changes
========================