php-src/UPGRADING.INTERNALS

PHP 8.3 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_class_entry now possesses a default_object_handlers field, which
  provides a default object handler when create_object() is not overriding it.
* Custom Fiber implementations have to initialize EG(stack_limit) and
  EG(stack_base).
* EG(opline_before_exception) may now be null if the VM throws an exception
  before executing any opline.
* Many C header files have been cleaned up and include dependencies
  have been reduced.  Many headers which used to be always included by
  Zend headers (e.g. "errno.h") are no longer implied, and this may
  break the build of third-party extensions which relied on this
  implementation detail.  Those extensions may need to add the missing
  #include lines.
* Since version 8, PHP requires a C99 compiler.  Configure-time checks
  for C99 features have been removed and therefore macro definitions
  from php_config.h have disappeared.  Do not use those feature
  macros.
* Internal class aliases created during request time can now exist in
  the class table. zend_register_class_alias_ex() will not increase
  the refcount for class aliases and the cleanup function takes this
  into account.
* The return types of the following functions have been changed from
  `bool` to `zend_result`:
  - zend_fiber_init_context()
* The fast_add_function() has been removed, use add_function() that will
  call the static inline add_function_fast() instead.
* The order of members of zend_op_array, zend_ssa_var, zend_ssa_var_info,
  zend_executor_globals and php_core_globals have changed to improve
  struct packing which reduces their size.
* Many calls to zend_assign_to_variable have been replaced with
  zend_assign_to_variable_ex which allows delaying the releasing of the old
  variable value. This avoids side-effects through destructors between the
  assignment of the variable and the assignment to the result zval in the VM
  (i.e. it may free the new value). See GH-10168 for details.
* The return types of the following functions were changed from int to
  zend_result:
  - open_file_for_scanning
  - php_rfc1867_callback
  - virtual_chdir
  - zend_execute_scripts
  - zend_get_module_started
  - zend_handle_undef_args
  - zend_list_delete
  - zend_multibyte_parse_encoding_list
  - zend_multibyte_set_internal_encoding
  - zend_parse_ini_file
  - zend_parse_ini_string
  - zend_set_user_opcode_handler
  - zend_ssa_inference
* Removed unused macros PHP_FNV1_32A_INIT and PHP_FNV1A_64_INIT. See GH-11114.
* ext/standard/hrtime.h was moved to Zend/zend_hrtime.h
  * The prefix of the PHP_HRTIME_ macros was changed to ZEND_HRTIME_
  * The HRTIME_AVAILABLE macro was renamed to ZEND_HRTIME_AVAILABLE
  * The php_hrtime_current() function was renamed to zend_hrtime()
* _php_stream_dirent now has an extra d_type field that is used to store the
  directory entry type. This can be used to avoid additional stat calls for
  types when the type is already known.
* The misspelled ZEND_CGG_DIAGNOSTIC_IGNORED_(START|END) macros are deprecated.
  Use ZEND_DIAGNOSTIC_IGNORED_(START|END) instead. These macros now also support
  Clang.

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

* PHP_EXTRA_VERSION can be passed to configure script to control custom PHP
  build versions: ./configure PHP_EXTRA_VERSION="-acme"

* LDFLAGS are not unset anymore allowing them to be adjusted e.g.
  LDFLAGS="..." ./configure

* Removed the HAVE_DEV_URANDOM compile time check.  HAVE_DEV_URANDOM will
  now never be defined. Any checks relying on HAVE_DEV_URANDOM should be
  removed.  Even with HAVE_DEV_URANDOM it was not guaranteed that
  /dev/urandom is actually available at run time and thus a runtime
  check needs to happen in all cases.

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

 a. ext/json
   - A new function php_json_validate_ex has been added to check if the
     provided C string is valid for the given depth and options.

 b. ext/standard
   - The PHPAPI php_url_encode_hash_ex() function has had its signature change
     from:
     PHPAPI void php_url_encode_hash_ex(HashTable *ht, smart_str *formstr,
     				const char *num_prefix, size_t num_prefix_len,
     				const char *key_prefix, size_t key_prefix_len,
     				const char *key_suffix, size_t key_suffix_len,
     				zval *type, const char *arg_sep, int enc_type);
     to:
     PHPAPI void php_url_encode_hash_ex(HashTable *ht, smart_str *formstr,
     				const char *num_prefix, size_t num_prefix_len,
     				const zend_string *key_prefix,
     				zval *type, const zend_string *arg_sep, int enc_type);
     The change to use zend_string prevent the computation of the arg_sep
     length at each call. The key_suffix parameter was dropped as it was a
     constant value and depended on the key_prefix parameter to not be NULL.

 c. ext/mysqlnd
   - The function mysqlnd_shutdown and its corresponding internal methods
   mysqlnd_command::shutdown & mysqlnd_conn_data::shutdown have been removed.
   These functions are deprecated by MySQL in favour of SHUTDOWN SQL statement.

 d. ext/pcre
   - The function pcre_get_compiled_regex_ex has been removed.
   Use pcre_get_compiled_regex instead.

 e. ext/spl
   - The PHPAPI spl_iterator_apply() function now returns zend_result instead of int.
     There are no functional changes.
   - The field _spl_filesystem_object->is_recursive has been removed.

 f. ext/dom
   - A new function dom_get_doc_props_read_only() is added to gather the document
     properties in a read-only way. This function avoids allocation when there are
     no document properties changed yet.
   - The node list returned by DOMNode::getElementsByTagName() and
	   DOMNode::getElementsByTagNameNS() now caches the length and the last requested item.
	   This means that the length and the last requested item are not recalculated
	   when the node list is iterated over multiple times.
	   If you do not use the internal PHP dom APIs to modify the document, you need to
	   manually invalidate the cache using php_libxml_invalidate_node_list_cache_from_doc().
	   Furthermore, the following internal APIs were added to handle the cache:
	     . php_dom_is_cache_tag_stale_from_doc_ptr()
	     . php_dom_is_cache_tag_stale_from_node()
	     . php_dom_mark_cache_tag_up_to_date_from_node()
   - The function dom_get_elements_by_tag_name_ns_raw() has an additional parameter to indicate
     the base node of the node list. This function also no longer accepts -1 as the index argument.
   - The function dom_namednode_iter() has additional arguments to avoid recomputing the length of
     the strings.
   - The functions dom_parent_node_prepend(), dom_parent_node_append(), dom_parent_node_after(), and
     dom_parent_node_before() now use an uint32_t argument for the number of nodes instead of int.
   - There is now a helper function php_dom_get_content_into_zval() to get the contents of a node.
     This avoids allocation if possible.
   - The function dom_set_old_ns() has been moved into ext/libxml as php_libxml_set_old_ns() and
     is now publicly exposed as an API.

 g. ext/libxml
   - Two new functions: php_libxml_invalidate_node_list_cache_from_doc() and
     php_libxml_invalidate_node_list_cache() were added to invalidate the cache of a node list.

========================
4. OpCode changes
========================

========================
5. SAPI changes
========================

* SAPIs that may execute in alternative stacks have to set EG(stack_limit) and
  EG(stack_base)