rfc:internal_serialize_api
no way to compare when less than two revisions
Differences
This shows you the differences between two versions of the page.
Previous revisionNext revision | |||
— | rfc:internal_serialize_api [2013/07/27 21:38] – [Examples] bukka | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | ====== PHP RFC: Internal Serialize API ====== | ||
+ | * Version: 0.1 | ||
+ | * Date: 2013-07-27 | ||
+ | * Author: Jakub Zelenka, bukka@php.net | ||
+ | * Status: Under Discussion | ||
+ | |||
+ | ===== Introduction ===== | ||
+ | |||
+ | This RFC proposes API for internal generating of serialization. | ||
+ | |||
+ | ===== Proposal ===== | ||
+ | |||
+ | The idea is that extension writers will be able to use class serialize callback for object serialization | ||
+ | |||
+ | === Serialize hook changes === | ||
+ | |||
+ | Currently '' | ||
+ | |||
+ | < | ||
+ | #define PHP_SERIALIZE_FAILURE (FAILURE) | ||
+ | #define PHP_SERIALIZE_CUSTOM | ||
+ | #define PHP_SERIALIZE_OBJECT | ||
+ | </ | ||
+ | |||
+ | If the return value is '' | ||
+ | |||
+ | If the return value is '' | ||
+ | |||
+ | |||
+ | === Serialization state structure === | ||
+ | |||
+ | The new structure '' | ||
+ | |||
+ | === Functions === | ||
+ | |||
+ | < | ||
+ | /* initialize serialize state */ | ||
+ | int php_serialize_init(php_serialize_state *state, unsigned char **buffer, zend_uint *buf_len); | ||
+ | |||
+ | /* the final operations for internal data serialization */ | ||
+ | int php_serialize_finish(php_serialize_state *state); | ||
+ | |||
+ | /* initialize serialize state and pre-allocate size of memory */ | ||
+ | int php_serialize_init_ex(php_serialize_state *state, unsigned char **buffer, zend_uint *buf_len, size_t size); | ||
+ | |||
+ | /* add object serialization string prefix */ | ||
+ | int php_serialize_object_start(php_serialize_state *state, zval *object, zend_uint nprops); | ||
+ | |||
+ | /* add object serialization string prefix */ | ||
+ | int php_serialize_object_start_ex(php_serialize_state *state, const char *class_name, | ||
+ | |||
+ | /* append string that ends the object definition */ | ||
+ | int php_serialize_object_end(php_serialize_state *state); | ||
+ | |||
+ | /* append null property */ | ||
+ | int php_serialize_property_null(php_serialize_state *state, const char *key); | ||
+ | |||
+ | /* append boolean property */ | ||
+ | int php_serialize_property_bool(php_serialize_state *state, const char *key, long value); | ||
+ | |||
+ | /* append long property */ | ||
+ | int php_serialize_property_long(php_serialize_state *state, const char *key, long value); | ||
+ | |||
+ | /* append double property */ | ||
+ | int php_serialize_property_double(php_serialize_state *state, const char *key, double value); | ||
+ | |||
+ | /* append string property */ | ||
+ | int php_serialize_property_string(php_serialize_state *state, const char *key, const char *value); | ||
+ | |||
+ | /* append string property */ | ||
+ | int php_serialize_property_stringl(php_serialize_state *state, const char *key, const char *value, size_t value_length); | ||
+ | |||
+ | /* allocate data to value buffer that needs to filled afterwards */ | ||
+ | int php_serialize_property_stringl_ptr(php_serialize_state *state, const char *key, char **value, size_t value_length); | ||
+ | |||
+ | /* append string property zval */ | ||
+ | int php_serialize_property_zval(php_serialize_state *state, const char *key, zval *value); | ||
+ | |||
+ | /* append properties taken from HashTable */ | ||
+ | int php_serialize_hash_table(php_serialize_state *state, HashTable *properties); | ||
+ | </ | ||
+ | |||
+ | All defined function return SUCCESS on success, otherwise FAILURE (it can happen if they are called in order that is not allowed). Some functions might be internally defined as macros. | ||
+ | |||
+ | The functionality for all functions should be clear from the comments. The exception is function '' | ||
+ | |||
+ | ===== Examples ===== | ||
+ | |||
+ | This example shows how the new API could be used in DateTime serialization. There would be some extra checks if it was used. This is just an example of the API. | ||
+ | |||
+ | < | ||
+ | int date_object_serialize(zval *object, unsigned char **buffer, zend_uint *buf_len, zend_serialize_data *data TSRMLS_DC) | ||
+ | { | ||
+ | php_serialize_state state; | ||
+ | char *value, *date_str; | ||
+ | php_date_obj *dateobj = (php_date_obj *) zend_object_store_get_object(object TSRMLS_CC); | ||
+ | |||
+ | php_serialize_init(& | ||
+ | php_serialize_object_start(& | ||
+ | date_str = date_format(" | ||
+ | php_serialize_property_string(& | ||
+ | efree(date_str); | ||
+ | php_serialize_property_long(& | ||
+ | php_serialize_property_stringl_ptr(& | ||
+ | snprintf(value, | ||
+ | php_serialize_object_end(& | ||
+ | php_serialize_finish(& | ||
+ | |||
+ | return PHP_SERIALIZE_OBJECT; | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | ===== Patches and Tests ===== | ||
+ | |||
+ | Will be after agreeing on API spec... |
rfc/internal_serialize_api.txt · Last modified: 2018/06/18 10:15 by cmb