xref: /PHP-5.4/UPGRADING.INTERNALS (revision 53c68811)
1$Id$
2
3UPGRADE NOTES - PHP X.Y
4
51. Internal API changes
6  a. virtual_file_ex
7  b. stat/lstat support
8  c. readlink support
9  d. layout of some core ZE structures (zend_op_array, zend_class_entry, ...)
10  e. Zend\zend_fast_cache.h has been removed
11  f. streams that enclose private streams
12  g. leak_variable
13  h. API Signature changes
14  i. new TSRM function expand_filepath_with_mode
15  j. unserialization of manipulated object strings
16
172. Build system changes
18  a. Unix build system changes
19  b. Windows build system changes
20
21
22========================
231. Internal API changes
24========================
25
26	a. virtual_file_ex
27
28virtual_file_ex takes now a TSRM context as last parameter:
29CWD_API int virtual_file_ex(cwd_state *state, const char *path,
30 verify_path_func verify_path, int use_realpath TSRLS_DC);
31
32
33	b. stat/lstat support
34
35lstat is now available on all platforms. On unix-like platform
36php_sys_lstat is an alias to lstat (when avaible). On Windows it is now
37available using php_sys_lstat. php_sys_stat and php_sys_lstat usage is recommended
38instead of calling lstat directly, to ensure portability.
39
40
41	c. readlink support
42
43readlink is now available on all platforms. On unix-like platform
44php_sys_readlink is an alias to readlink (when avaible). On Windows it is now
45available using php_sys_readlink. php_sys_readlink usage is recommended
46instead of calling readlink directly, to ensure portability.
47
48
49	d. layout of some core ZE structures (zend_op_array, zend_class_entry, ...)
50
51. zend_function.pass_rest_by_reference is replaced by
52  ZEND_ACC_PASS_REST_BY_REFERENCE in zend_function.fn_flags
53. zend_function.return_reference is replaced by ZEND_ACC_RETURN_REFERENCE
54  in zend_function.fn_flags
55. zend_arg_info.required_num_args removed. it was needed only for internal
56  functions. Now the first arg_info for internal function (which has special
57  meaning) is represented by zend_internal_function_info structure.
58. zend_op_array.size, size_var, size_literal, current_brk_cont,
59  backpatch_count moved into CG(context), because they are used only during
60  compilation.
61. zend_op_array.start_op is moved into EG(start_op), because it's used
62  only for 'interactive' execution of single top-level op-array.
63. zend_op_array.done_pass_two is replaced by ZEND_ACC_DONE_PASS_TWO in
64  zend_op_array.fn_flags.
65. op_array.vars array is trimmed (reallocated) during pass_two.
66. zend_class_entry.constants_updated is replaced by
67  ZEND_ACC_CONSTANTS_UPDATED in zend_class_entry.ce_flags
68. the size of zend_class_entry is reduced by sharing the same memory space
69  by different information for internal and user classes.
70  See zend_class_inttry.info union.
71
72
73	e. Zend\zend_fast_cache.h
74
75It should not have been used anymore since php5, but now this header has
76been removed. The following macros are not available anymore:
77
78ZEND_FAST_ALLOC(p, type, fc_type)
79ZEND_FAST_FREE(p, fc_type)
80ZEND_FAST_ALLOC_REL(p, type, fc_type)
81ZEND_FAST_FREE_REL(p, fc_type)
82
83Use emalloc, emalloc_rel, efree or efree_rel instead.
84
85
86	f. Streams that enclose private streams
87
88Some streams, like the temp:// stream, may enclose private streams. If the
89outer stream leaks due to a programming error or is not exposed through a
90zval (and therefore is not deleted when all the zvals are gone), it will
91be destroyed on shutdown.
92The problem is that the outer usually wants itself to close the inner stream,
93so that it may do any other shutdown action that requires the inner stream to
94be live (e.g. commit data to it). If the outer stream is exposed through a
95zval and the inner one isn't, this is not a problem because the outer stream
96will be freed when the zval is destroyed, which happens before the resources
97are destroyed on shutdown.
98On resource list shutdown, the cleanup happens in reverse order of resource
99creation, so if the inner stream was created in the opener of the outer stream,
100it will be destroyed first.
101The following functions were added to the streams API to force a predictable
102destruction order:
103
104PHPAPI php_stream *php_stream_encloses(php_stream *enclosing, php_stream *enclosed);
105#define php_stream_free_enclosed(stream_enclosed, close_options)
106PHPAPI int _php_stream_free_enclosed(php_stream *stream_enclosed, int close_options TSRMLS_DC);
107
108Additionally, the following member was added to php_stream:
109
110	struct _php_stream *enclosing_stream;
111
112and the following macro was added:
113
114#define PHP_STREAM_FREE_IGNORE_ENCLOSING	32
115
116The function php_stream_encloses declares the first stream encloses the second.
117This has the effect that, when the inner stream is closed from a resource
118destructor it will abort and try to free its enclosing stream instead.
119To prevent this from happening when the inner stream is freed from the outer
120stream, the macro php_stream_free_enclosed should be used instead of
121php_stream_free/php_stream_close/php_stream_pclose, or the flag
122PHP_STREAM_FREE_IGNORE_ENCLOSING should be directly passed to php_stream_free.
123The outer stream cannot abstain, in its close callback, from closing the inner
124stream or clear the enclosing_stream pointer in its enclosed stream by calling
125php_stream_encloses with the 2nd argument NULL. If this is not done, there will
126be problems, so observe this requirement when using php_stream_encloses.
127
128
129	g. leak_variable
130
131The function leak_variable(variable [, leak_data]) was added. It is only
132available on debug builds. It increments the refcount of a zval or, if the
133second argument is true and the variable is either an object or a resource
134it increments the refcounts of those objects instead.
135
136
137	h. API Signature changes
138
139. zend_list_insert
140  ZEND_API int zend_list_insert(void *ptr, int type TSRMLS_DC);
141  call: zend_list_insert(a, SOMETYPE TSRMLS_CC);
142  NB: If zend_list_insert is used to register a resource,
143  ZEND_REGISTER_RESOURCE could be used instead.
144
145. php_le_stream_context(TSRMLS_C)
146  PHPAPI php_stream_context *php_stream_context_alloc(TSRMLS_D)
147  call: context  = php_stream_context_alloc(TSRMLS_C);
148
149. php_stream_context_alloc
150  PHPAPI php_stream_context *php_stream_context_alloc(TSRMLS_D);
151  call: context  = php_stream_context_alloc(TSRMLS_C);
152
153. sapi_get_request_time(TSRMLS_D);
154  SAPI_API double sapi_get_request_time(TSRMLS_D);
155
156. sapi_register_default_post_reader
157  SAPI_API int sapi_register_default_post_reader(void (*default_post_reader)(TSRMLS_D) TSRMLS_DC);
158
159. sapi_register_treat_data
160  SAPI_API int sapi_register_treat_data(void (*treat_data)(int arg, char *str, zval *destArray TSRMLS_DC) TSRMLS_DC);
161
162. sapi_register_input_filter
163  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);
164
165. tsrm_win32_access
166  TSRM_API int tsrm_win32_access(const char *pathname, int mode TSRMLS_DC);
167
168. popen_ex (win32)
169  TSRM_API FILE *popen_ex(const char *command, const char *type, const char *cwd, char *env TSRMLS_DC);
170
171. php_get_current_user
172  PHPAPI php_get_current_user(TSRMLS_D)
173  Call: char *user = php_get_current_user(TSRMLS_C);
174
175. php_idate
176  PHPAPI php_idate(char format, time_t ts, int localtime TSRMLS_DC)
177  Call: int ret = php_idate(format, ts, localtime TSRMLS_CC)
178
179. php_escape_html_entities
180  (size_t parameters were ints, previous "quote_style" (now flags) has expanded meaning)
181  PHPAPI char *php_escape_html_entities(unsigned char *old, size_t oldlen, size_t *newlen, int all, int flags, char *hint_charset TSRMLS_DC);
182
183. php_escape_html_entities_ex
184  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);
185
186. php_unescape_html_entities
187  PHPAPI char *php_unescape_html_entities(unsigned char *old, size_t oldlen, size_t *newlen, int all, int flags, char *hint_charset TSRMLS_DC);
188
189  i.
190  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);
191  expand_filepath_with_mode lets define how realpath will behave, using one of the existing mode: CWD_EXPAND , CWD_FILEPATH or CWD_REALPATH.
192
193  j.
194  Strings requiring unserialization of objects are now explicitly checked
195  whether the object they contain implements the Serializable interface.
196  This solves the situation where manipulated strings could be passed for
197  objects using Serializable to disallow serialization. An object
198  implementing Serializable will always start with "C:" in the serialized
199  string, all other objects are represented with starting "O:". Objects
200  implementing Serializable to disable serialization using
201  zend_class_unserialize_deny and zend_class_serialize_deny, when
202  instantiated from the serializer with a manipulated "O:" string at the
203  start, will most likely be defectively initialized. This is now
204  fixed at the appropriate place by checking for the presence of the
205  serialize callback in the class entry.
206
207========================
2082. Build system changes
209========================
210
211  a. Unix build system changes
212
213    - Changes in SAPI module build:
214      . 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.
215
216    - New macros:
217      . PHP_INIT_DTRACE(providerdesc, header-file, sources [, module])
218
219
220  b. Windows build system changes
221    -
222
223