Return to UPGRADING.INTERNALS CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php

php 5.4.3+patches

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