xref: /PHP-8.1/UPGRADING.INTERNALS (revision 14f599ea)
1PHP 8.1 INTERNALS UPGRADE NOTES
2
31. Internal API changes
4  a. Removed Zend APIs
5  b. Zend Stream API
6  c. zend_get_opcode_id()
7  d. Removed support for "p" printf format specifier
8  e. ZEND_ATOL() changes
9  f. Non-serializable classes should use ZEND_ACC_NOT_SERIALIZABLE
10  g. _zend_hash_find_known_hash renamed to zend_hash_find_known_hash
11  h. Renaming of ZEND_TYPE_HAS_CLASS() into ZEND_TYPE_IS_COMPLEX()
12  i. zend_resource handle is now zend_long
13
142. Build system changes
15  a. New compiler flags
16
173. Module changes
18  a. ext/hash
19  b. ext/pdo
20  c. ext/standard
21  d. ext/pgsql
22  e. ext/pcre
23
24========================
251. Internal API changes
26========================
27  a. The following APIs have been removed from the Zend Engine:
28     - The spl_ce_Aggregate, spl_ce_ArrayAccess, spl_ce_Countable, spl_ce_Iterator, spl_ce_Serializable,
29       spl_ce_Stringable, spl_ce_Traversable alias class entries have been removed in favor of zend_ce_aggregate,
30       zend_ce_arrayaccess, zend_ce_countable, zend_ce_iterator, zend_ce_serializable, zend_ce_stringable,
31       zend_ce_traversable.
32     - The ZVAL_NEW_ARR() macro has been removed. Use array_init() or ZVAL_ARR
33       with zend_new_array() instead.
34     - The IGNORE_URL_WIN macro has been removed; it had no effect as of PHP 5.0.0.
35     - TsHashTable has been removed, it was not used in php-src and was not useful outside of php-src.
36  b. Zend Stream API has been changed to use "zend_string*" instead of "char*"
37      - zend_file_handle.filename now is zend_string*
38      - zend_file_handle.free_filename is removed. Now zend_file_handle.filename is always released.
39      - added zend_file_handle.primary_script flag. SAPIs should set it for main executed script.
40      - added zend_file_handle.in_list flag, which is set when a file_handle is added into CG(open_files)
41      - added zend_stream_init_filename_ex() function, that takes filename as zend_string*
42      - the "filename" parameter of functons zend_stream_open(), php_stream_open_for_zend_ex() and
43        callback zend_stream_open_function() has been removed (it's now passed as a "filename" field of the
44        file_handle parameter)
45      - in zend_fopen() and zend_resolve_path() callbacks filename now passed as zend_string*
46      - file_handles should be destroyed by zend_destroy_file_handle() function (usually in the same function
47        the same function where they were created by zend_stream_init_*()). Previously there were two different
48        destructors zend_destroy_file_handle() and zend_file_handle_dtor().
49      - zend_ini_scanner_globals.filename now is zend_string*
50  c. Added the zend_get_opcode_id() function, which is intended to get opcode id from name.
51  d. Removed support for "p" modifier (%pd, %pu, etc) in PHP's printf
52     implementations. Use ZEND_LONG_FMT and ZEND_ULONG_FMT instead.
53  e. ZEND_ATOL() now returns the integer instead of assigning it as part of the
54     macro. Replace ZEND_ATOL(i, s) with i = ZEND_ATOL(s).
55  f. Non-serializable classes should be indicated using the
56     ZEND_ACC_NOT_SERIALIZABLE (@not-serializable in stubs) rather than the
57     zend_class_(un)serialize_deny handlers which are removed.
58  g. _zend_hash_find_known_hash has been renamed to zend_hash_find_known_hash.
59  h. ZEND_TYPE_HAS_CLASS() has been renamed to ZEND_TYPE_IS_COMPLEX() for clarity.
60     A zend_type element can contain a zend_type_list which might be either a union or an intersection,
61     or a single class stored as either a zend_string* or a zend_class_entry*.
62  i. The handle member of zend_resource (the resource ID) now has type zend_long
63     rather than int. This should be transparent to most code, but uses in
64     printf may need to switch from "%d" to ZEND_LONG_FMT.
65
66========================
672. Build system changes
68========================
69  a. New compiler flags
70     - [-Wimplicit-fallthrough=1] is now enabled by default.
71       It is possible to use the new ZEND_FALLTHROUGH macro keyword to suppress the warning.
72========================
733. Module changes
74========================
75
76  a. ext/hash
77    - The init signatures are extended with an additional `HashTable*`
78      argument. The passed HT is to contain the algorithm specific
79      configuration. If an algorithm doesn't make use of any additional
80      configuration, the argument is to be marked with ZEND_ATTRIBUTE_UNUSED.
81
82  b. ext/pdo
83    - The "preparer" callback now accepts a zend_string* instead of
84      char* + size_t pair the query string. Similarly, the query_string and
85      active_query_string members of pdo_stmt_t are now zend_string*.
86    - The way in which drivers provide results has changed: Previously,
87      the "describer" callback populated the "pdo_type" member in the
88      pdo_column_data structure, and the "get_col" callback then had to return
89      pointers to data of appropriate type.
90
91      In PHP 8.1, the "describer" callback no longer determines the pdo_type
92      (and this member has been removed from pdo_column_data). Instead, the
93      "get_col" callback accepts a zval pointer that may be populated with a
94      value of arbitrary type. This gives drivers more flexibility in
95      determining result types (e.g. based on whether a specific integer fits
96      the PHP integer type) and avoid awkward juggling of temporary buffers.
97
98      As the "describer" no longer determines pdo_type, the "get_column_meta"
99      function is now responsible for providing this information for use by
100      getColumnMeta(). The type provided here does not need to match the type
101      returned by get_col (in fact no corresponding type might exist, e.g. for
102      floats). It should be the closest logical equivalent for the column type.
103    - The transaction, set_attribute, and preparer handler's return type
104      has been formalized to bool instead of int.
105    - The check_liveness handler's return type has been formalized to zend_return
106      instead of int.
107    - The closer, and fetch_error handlers have been voidified.
108    - The quoter handler now returns the quoted string as zend_string* instead
109      of returning a boolean, and the quoted string as a pair of out params.
110      Similarly the unquoted string is now a zend_string* instead of a pair of
111      char* and size_t length.
112    - The doer handler now accepts a zend_string* instead of char* + size_t
113      pair for the SQL statement.
114    - The last_id handler now returns a zend_string* instead of returning a
115      char* and the length as an out param, and accepts a zend_string* instead
116      of char* for the optional sequence/table name.
117    - The php_pdo_str_tolower_dup() PDO_API has been removed use zend_str_tolower_dup()
118      or zend_string_tolower_ex().
119
120  c. ext/standard
121    - The PHP API php_fputcsv() now takes an extra zend_string* argument at the end
122      for a custom EOL sequence, passing NULL provides the old default of "\n".
123
124  d. ext/pgsql
125    - The functions php_pgsql_meta_data(), php_pgsql_convert(), php_pgsql_insert(),
126      php_pgsql_update(), php_pgsql_delete(), and php_pgsql_select() have had
127      their return type formalized to zend_result.
128    - The functions php_pgsql_meta_data(), php_pgsql_convert(), php_pgsql_insert(),
129      php_pgsql_update(), php_pgsql_delete(), and php_pgsql_select() now accept a
130      zend_string* instead of a char* for the table name.
131
132  e. ext/pcre
133    - Bundled PCRE2 is at version 10.37. The most important diff to the previous
134      version is the JIT support on the S390 platform.
135