UPGRADING.INTERNALS [plain text]
$Id$
PHP 5.6 INTERNALS UPGRADE NOTES
1. Internal API changes
a. Addition of do_operation and compare object handlers
b. return_value_ptr now always available, RETVAL_ZVAL_FAST macros
c. POST data handling
d. Arginfo changes
e. tsrm_virtual_cwd.h moved to zend_virtual_cwd.h
f. empty strings are interned
g. Additional str_* APIs
h. Addition of zend_hash_reindex
i. Addition of zend_hash_splice
j. Unserialization of manipulated object strings
k. Removal of IS_CONSTANT_ARRAY and IS_CONSTANT_INDEX hack
2. Build system changes
a. Unix build system changes
b. Windows build system changes
========================
1. Internal API changes
========================
a. Addition of do_operation and compare object handlers
Two new object handlers have been added:
do_operation:
typedef int (*zend_object_do_operation_t)(
zend_uchar opcode, zval *result, zval *op1, zval *op2 TSRMLS_DC
);
compare:
typedef int (*zend_object_compare_zvals_t)(
zval *result, zval *op1, zval *op2 TSRMLS_DC
);
The first handler is used to overload arithmetic operations. The first
argument specifies the opcode of the operator, result is the target zval,
op1 the first operand and op2 the second operand. For unary operations
op2 is NULL. If the handler returns FAILURE PHP falls back to the default
behavior for the operation.
The second handler is used to perform comparison operations with
non-objects. The value written into result must be an IS_LONG with value
-1 (smaller), 0 (equal) or 1 (greater). The return value is a SUCCESS/FAILURE
return code. The difference between this handler and compare_objects is
that it will be triggered for comparisons with non-objects and objects of
different types. It takes precedence over compare_objects.
Further docs in the RFC: https://wiki.php.net/rfc/operator_overloading_gmp
b. return_value_ptr now always available, RETVAL_ZVAL_FAST macros
The return_value_ptr argument to internal functions is now always set.
Previously it was only available for functions returning by-reference.
return_value_ptr can now be used to return zvals without copying them.
For this purpose two new macros are provided:
RETVAL_ZVAL_FAST(zv); /* analog to RETVAL_ZVAL(zv, 1, 0) */
RETURN_ZVAL_FAST(zv); /* analog to RETURN_ZVAL(zv, 1, 0) */
The macros behave similarly to the non-FAST variants with copy=1 and
dtor=0, but will try to return the zval without making a copy by utilizing
return_value_ptr.
c. POST data handling
The sapi_request_info's members post_data, post_data_len and raw_post_data as
well as raw_post_data_len have been replaced with a temp PHP stream
request_body.
The recommended way to access raw POST data is to open and use a php://input
stream wrapper. It is safe to be used concurrently and more than once.
d. Arginfo changes
The pass_rest_by_reference argument of the ZEND_BEGIN_ARG_INFO and
ZEND_BEGIN_ARG_INFO_EX() is no longer used. The value passed to it is ignored.
Instead a variadic argument is created using ZEND_ARG_VARIADIC_INFO():
ZEND_ARG_VARIADIC_INFO(0, name) /* pass rest by value */
ZEND_ARG_VARIADIC_INFO(1, name) /* pass rest by reference */
ZEND_ARG_VARIADIC_INFO(ZEND_SEND_PREFER_REF, name)
/* pass rest by prefer-ref */
ZEND_ARG_VARIADIC_INFO() should only be used for the last argument.
The following changes were applied to the zend_arg_info struct:
typedef struct _zend_arg_info {
const char *class_name;
zend_uint class_name_len;
zend_uchar type_hint;
+ zend_uchar pass_by_reference;
zend_bool allow_null;
- zend_bool pass_by_reference;
+ zend_bool is_variadic;
} zend_arg_info;
The following changes were applied to the zend_internal_function_info struct:
typedef struct _zend_internal_function_info {
zend_uint required_num_args;
zend_uchar _type_hint;
zend_bool return_reference;
- zend_bool pass_rest_by_reference;
+ zend_bool _allow_null;
+ zend_bool _is_variadic;
} zend_internal_function_info;
The CHECK_ARG_SEND_TYPE(), ARG_MUST_BE_SENT_BY_REF(),
ARG_SHOULD_BE_SENT_BY_REF() and ARG_MAY_BE_SENT_BY_REF() macros now assume
that the argument passed to them is a zend_function* and that it is non-NULL.
e. tsrm_virtual_cwd.h moved to zend_virtual_cwd.h
Memory allocation is now managed by emalloc/efree instead of malloc/free.
f. empty strings are interned
String created using STR_EMPTY_ALLOC() are now interned.
convert_to_string use STR_EMPTY_ALLOC() for zval when IS_NULL.
str_efree() shoud be preferred as efree() on such strings can cause memory
corruption.
g. Additional str_* APIs
In addition to the previously existing str_free() and str_efree() macros, the
following macros have been introduced to simplify dealing with potentially
interned strings:
str_efree_rel(str) - efree_rel() if not interned
str_erealloc(str, new_len) - erealloc() or emalloc+memcpy if interned
str_estrndup(str, len) - estrndup() if not interned
str_strndup(str, len) - zend_strndup() if not interned
str_hash(str, len) - INTERNED_HASH(str) if interned,
zend_hash_func(str, len+1) otherwise
h. Addition of zend_hash_reindex
A zend_hash_reindex() function with the following prototype has been added:
void zend_hash_reindex(HashTable *ht, zend_bool only_integer_keys);
If only_integer_keys==0, this function will change all keys to be continuous,
zero-based integers in hash order. If only_integer_keys==1 the same will be
done only for keys that were already integers previously, while leaving
string keys alone.
i. Addition of zend_hash_splice
A zend_hash_splice() macro with the following prototype has been added:
void zend_hash_splice(
HashTable *ht, uint nDataSize, copy_ctor_func_t pCopyConstructor,
uint offset, uint length,
void **list, uint list_count, HashTable *removed
);
This function performs an in-place splice operation on a hashtable:
The elements between offset and offset+length are removed and the elements in
list[list_count] are inserted in their place. The removed elements can be
optionally collected into a hashtable.
This operation reindexes the hashtable, i.e. integer keys will be zero-based
and sequential, while string keys stay intact. The same applies to the
elements inserted into the removed HT.
As a side-effect of this addition the signature of the php_splice() function
changed:
void php_splice(
HashTable *ht, zend_uint offset, zend_uint length,
zval ***list, zend_uint list_count, HashTable *removed TSRMLS_DC
)
This function now directly forwards to zend_hash_splice(), resets the
IAP of ht (for compatibility with the previous implementation) and resets
CVs if the passed hashtable is the global symbol table.
j. Unserialization of manipulated object strings
Strings requiring unserialization of objects are now explicitly checked
whether the object they contain implements the Serializable interface.
This solves the situation where manipulated strings could be passed for
objects using Serializable to disallow serialization. An object
implementing Serializable will always start with "C:" in the serialized
string, all other objects are represented with starting "O:". Objects
implementing Serializable to disable serialization using
zend_class_unserialize_deny and zend_class_serialize_deny, when
instantiated from the serializer with a manipulated "O:" string at the
start, will most likely be defectively initialized. This is now
fixed at the appropriate place by checking for the presence of the
serialize callback in the class entry.
k. Removal of IS_CONSTANT_ARRAY and IS_CONSTANT_INDEX hack
These two #defines disappeared. Instead we have now IS_CONSTANT_AST which
covers also the functionality IS_CONSTANT_ARRAY bid and furthermore the
hack for marking zvals as constant index with IS_CONSTANT_INDEX is now
superfluous and so removed.
Please note that IS_CONSTANT_AST now has the same value than
IS_CONSTANT_ARRAY had.
========================
2. Build system changes
========================
a. Unix build system changes
- The bison version check is now a blacklist instead of a whitelist.
- The bison binary can be specified through the YACC environment/configure
variable. Previously `bison` was assumed to be in $PATH.
b. Windows build system changes
- The configure option --enable-static-analyze isn't available anymore.
The new option was introduced --with-analyzer.
- It is possible to disable PGO for single extensions, to do that
define a global variable PHP_MYMODULE_PGO evaluating to false
inside config.w32