forked from php/php-src
/
UPGRADING.INTERNALS
207 lines (150 loc) · 8.36 KB
/
UPGRADING.INTERNALS
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
$Id$
UPGRADE NOTES - PHP X.Y
1. Internal API changes
a. virtual_file_ex
b. stat/lstat support
c. readlink support
d. layout of some core ZE structures (zend_op_array, zend_class_entry, ...)
e. Zend\zend_fast_cache.h has been removed
f. streams that enclose private streams
g. leak_variable
h. API Signature changes
i. new TSRM function expand_filepath_with_mode
2. Build system changes
a. Unix build system changes
b. Windows build system changes
========================
1. Internal API changes
========================
a. virtual_file_ex
virtual_file_ex takes now a TSRM context as last parameter:
CWD_API int virtual_file_ex(cwd_state *state, const char *path,
verify_path_func verify_path, int use_realpath TSRLS_DC);
b. stat/lstat support
lstat is now available on all platforms. On unix-like platform
php_sys_lstat is an alias to lstat (when avaible). On Windows it is now
available using php_sys_lstat. php_sys_stat and php_sys_lstat usage is recommended
instead of calling lstat directly, to ensure portability.
c. readlink support
readlink is now available on all platforms. On unix-like platform
php_sys_readlink is an alias to readlink (when avaible). On Windows it is now
available using php_sys_readlink. php_sys_readlink usage is recommended
instead of calling readlink directly, to ensure portability.
d. layout of some core ZE structures (zend_op_array, zend_class_entry, ...)
. zend_function.pass_rest_by_reference is replaced by
ZEND_ACC_PASS_REST_BY_REFERENCE in zend_function.fn_flags
. zend_function.return_reference is replaced by ZEND_ACC_RETURN_REFERENCE
in zend_function.fn_flags
. zend_arg_info.required_num_args removed. it was needed only for internal
functions. Now the first arg_info for internal function (which has special
meaning) is represented by zend_internal_function_info structure.
. zend_op_array.size, size_var, size_literal, current_brk_cont,
backpatch_count moved into CG(context), because they are used only during
compilation.
. zend_op_array.start_op is moved into EG(start_op), because it's used
only for 'interactive' execution of single top-level op-array.
. zend_op_array.done_pass_two is replaced by ZEND_ACC_DONE_PASS_TWO in
zend_op_array.fn_flags.
. op_array.vars array is trimmed (reallocated) during pass_two.
. zend_class_entry.constants_updated is replaced by
ZEND_ACC_CONSTANTS_UPDATED in zend_class_entry.ce_flags
. the size of zend_class_entry is reduced by sharing the same memory space
by different information for internal and user classes.
See zend_class_inttry.info union.
e. Zend\zend_fast_cache.h
It should not have been used anymore since php5, but now this header has
been removed. The following macros are not available anymore:
ZEND_FAST_ALLOC(p, type, fc_type)
ZEND_FAST_FREE(p, fc_type)
ZEND_FAST_ALLOC_REL(p, type, fc_type)
ZEND_FAST_FREE_REL(p, fc_type)
Use emalloc, emalloc_rel, efree or efree_rel instead.
f. Streams that enclose private streams
Some streams, like the temp:// stream, may enclose private streams. If the
outer stream leaks due to a programming error or is not exposed through a
zval (and therefore is not deleted when all the zvals are gone), it will
be destroyed on shutdown.
The problem is that the outer usually wants itself to close the inner stream,
so that it may do any other shutdown action that requires the inner stream to
be live (e.g. commit data to it). If the outer stream is exposed through a
zval and the inner one isn't, this is not a problem because the outer stream
will be freed when the zval is destroyed, which happens before the resources
are destroyed on shutdown.
On resource list shutdown, the cleanup happens in reverse order of resource
creation, so if the inner stream was created in the opener of the outer stream,
it will be destroyed first.
The following functions were added to the streams API to force a predictable
destruction order:
PHPAPI php_stream *php_stream_encloses(php_stream *enclosing, php_stream *enclosed);
#define php_stream_free_enclosed(stream_enclosed, close_options)
PHPAPI int _php_stream_free_enclosed(php_stream *stream_enclosed, int close_options TSRMLS_DC);
Additionally, the following member was added to php_stream:
struct _php_stream *enclosing_stream;
and the following macro was added:
#define PHP_STREAM_FREE_IGNORE_ENCLOSING 32
The function php_stream_encloses declares the first stream encloses the second.
This has the effect that, when the inner stream is closed from a resource
destructor it will abort and try to free its enclosing stream instead.
To prevent this from happening when the inner stream is freed from the outer
stream, the macro php_stream_free_enclosed should be used instead of
php_stream_free/php_stream_close/php_stream_pclose, or the flag
PHP_STREAM_FREE_IGNORE_ENCLOSING should be directly passed to php_stream_free.
The outer stream cannot abstain, in its close callback, from closing the inner
stream or clear the enclosing_stream pointer in its enclosed stream by calling
php_stream_encloses with the 2nd argument NULL. If this is not done, there will
be problems, so observe this requirement when using php_stream_encloses.
g. leak_variable
The function leak_variable(variable [, leak_data]) was added. It is only
available on debug builds. It increments the refcount of a zval or, if the
second argument is true and the variable is either an object or a resource
it increments the refcounts of those objects instead.
h. API Signature changes
. zend_list_insert
ZEND_API int zend_list_insert(void *ptr, int type TSRMLS_DC);
call: zend_list_insert(a, SOMETYPE TSRMLS_CC);
NB: If zend_list_insert is used to register a resource,
ZEND_REGISTER_RESOURCE could be used instead.
. php_le_stream_context(TSRMLS_C)
PHPAPI php_stream_context *php_stream_context_alloc(TSRMLS_D)
call: context = php_stream_context_alloc(TSRMLS_C);
. php_stream_context_alloc
PHPAPI php_stream_context *php_stream_context_alloc(TSRMLS_D);
call: context = php_stream_context_alloc(TSRMLS_C);
. sapi_get_request_time(TSRMLS_D);
SAPI_API double sapi_get_request_time(TSRMLS_D);
. sapi_register_default_post_reader
SAPI_API int sapi_register_default_post_reader(void (*default_post_reader)(TSRMLS_D) TSRMLS_DC);
. sapi_register_treat_data
SAPI_API int sapi_register_treat_data(void (*treat_data)(int arg, char *str, zval *destArray TSRMLS_DC) TSRMLS_DC);
. sapi_register_input_filter
SAPI_API int sapi_register_input_filter(unsigned int (*input_filter)(int arg, char *var, char **val, unsigned int val_len, unsigned int *new_val_len TSRMLS_DC), unsigned int (*input_filter_init)(TSRMLS_D) TSRMLS_DC);
. tsrm_win32_access
TSRM_API int tsrm_win32_access(const char *pathname, int mode TSRMLS_DC);
. popen_ex (win32)
TSRM_API FILE *popen_ex(const char *command, const char *type, const char *cwd, char *env TSRMLS_DC);
. php_get_current_user
PHPAPI php_get_current_user(TSRMLS_D)
Call: char *user = php_get_current_user(TSRMLS_C);
. php_idate
PHPAPI php_idate(char format, time_t ts, int localtime TSRMLS_DC)
Call: int ret = php_idate(format, ts, localtime TSRMLS_CC)
. php_escape_html_entities
(size_t parameters were ints, previous "quote_style" (now flags) has expanded meaning)
PHPAPI char *php_escape_html_entities(unsigned char *old, size_t oldlen, size_t *newlen, int all, int flags, char *hint_charset TSRMLS_DC);
. php_escape_html_entities_ex
PHPAPI char *php_escape_html_entities_ex(unsigned char *old, size_t oldlen, size_t *newlen, int all, int flags, char *hint_charset, zend_bool double_encode TSRMLS_DC);
. php_unescape_html_entities
PHPAPI char *php_unescape_html_entities(unsigned char *old, size_t oldlen, size_t *newlen, int all, int flags, char *hint_charset TSRMLS_DC);
i.
PHPAPI char *expand_filepath_with_mode(const char *filepath, char *real_path, const char *relative_to, size_t relative_to_len, int realpath_mode TSRMLS_DC);
expand_filepath_with_mode lets define how realpath will behave, using one of the existing mode: CWD_EXPAND , CWD_FILEPATH or CWD_REALPATH.
========================
2. Build system changes
========================
a. Unix build system changes
- Changes in SAPI module build:
. When adding new binary SAPI (executable, like CLI/CGI/FPM) use CLI config.m4 and Makefile.frag files as templates and replace CLI/cli with your SAPI name.
- New macros:
. PHP_INIT_DTRACE(providerdesc, header-file, sources [, module])
b. Windows build system changes
-