summaryrefslogtreecommitdiff
path: root/README.NEW-OUTPUT-API
diff options
context:
space:
mode:
Diffstat (limited to 'README.NEW-OUTPUT-API')
-rw-r--r--README.NEW-OUTPUT-API426
1 files changed, 426 insertions, 0 deletions
diff --git a/README.NEW-OUTPUT-API b/README.NEW-OUTPUT-API
new file mode 100644
index 0000000..82e3f48
--- /dev/null
+++ b/README.NEW-OUTPUT-API
@@ -0,0 +1,426 @@
+$Id: README.NEW-OUTPUT-API 219039 2006-08-30 07:39:09Z mike $
+
+
+API adjustment to the old output control code:
+
+ Everything now resides beneath the php_output namespace,
+ and there's an API call for every output handler op.
+
+ Checking output control layers status:
+ // Using OG()
+ php_output_get_status(TSRMLS_C);
+
+ Starting the default output handler:
+ // php_start_ob_buffer(NULL, 0, 1 TSRMLS_CC);
+ php_output_start_default(TSRMLS_C);
+
+ Starting an user handler by zval:
+ // php_start_ob_buffer(zhandler, chunk_size, erase TSRMLS_CC);
+ php_output_start_user(zhandler, chunk_size, flags TSRMLS_CC);
+
+ Starting an internal handler whithout context:
+ // php_ob_set_internal_handler(my_php_output_handler_func_t, buffer_size, "output handler name", erase TSRMLS_CC);
+ php_output_start_internal(handler_name_zval, my_php_output_handler_func_t, chunk_size, flags TSRMLS_CC);
+
+ Starting an internal handler with context:
+ // not possible with old API
+ php_output_handler *h;
+ h = php_output_handler_create_internal(handler_name_zval, my_php_output_handler_context_func_t, chunk_size, flags TSRMLS_CC);
+ php_output_handler_set_context(h, my_context, my_context_dtor);
+ php_output_handler_start(h TSRMLS_CC);
+
+ Testing whether a certain output handler has already been started:
+ // php_ob_handler_used("output handler name" TSRMLS_CC);
+ php_output_handler_started(handler_name_zval TSRMLS_CC);
+
+ Flushing one output buffer:
+ // php_ob_end_buffer(1, 1 TSRMLS_CC);
+ php_output_flush(TSRMLS_C);
+
+ Flushing all output buffers:
+ // not possible with old API
+ php_output_flush_all(TSRMLS_C);
+
+ Cleaning one output buffer:
+ // php_ob_end_buffer(0, 1 TSRMLS_CC);
+ php_output_clean(TSRMLS_C);
+
+ Cleaning all output buffers:
+ // not possible with old API
+ php_output_clean_all(TSRMLS_C);
+
+ Discarding one output buffer:
+ // php_ob_end_buffer(0, 0 TSRMLS_CC);
+ php_output_discard(TSRMLS_C);
+
+ Discarding all output buffers:
+ // php_ob_end_buffers(0 TSRMLS_CC);
+ php_output_discard_all(TSRMLS_C);
+
+ Stopping (and dropping) one output buffer:
+ // php_ob_end_buffer(1, 0 TSRMLS_CC)
+ php_output_end(TSRMLS_C);
+
+ Stopping (and dropping) all output buffers:
+ // php_ob_end_buffers(1, 0 TSRMLS_CC);
+ php_output_end_all(TSRMLS_C);
+
+ Retrieving output buffers contents:
+ // php_ob_get_buffer(zstring TSRMLS_CC);
+ php_output_get_contents(zstring TSRMLS_CC);
+
+ Retrieving output buffers length:
+ // php_ob_get_length(zlength TSRMLS_CC);
+ php_output_get_length(zlength TSRMLS_CC);
+
+ Retrieving output buffering level:
+ // OG(nesting_level);
+ php_output_get_level(TSRMLS_C);
+
+ Issue a warning because of an output handler conflict:
+ // php_ob_init_conflict("to be started handler name", "to be tested if already started handler name" TSRMLS_CC);
+ php_output_handler_conflict(new_handler_name_zval, set_handler_name_zval TSRMLS_CC);
+
+ Registering a conflict checking function, which will be checked prior starting the handler:
+ // not possible with old API, unless hardcoding into output.c
+ php_output_handler_conflict_register(handler_name_zval, my_php_output_handler_conflict_check_t TSRMLS_CC);
+
+ Registering a reverse conflict checking function, which will be checked prior starting the specified foreign handler:
+ // not possible with old API
+ php_output_handler_reverse_conflict_register(foreign_handler_name_zval, my_php_output_handler_conflict_check_t TSRMLS_CC);
+
+ Facilitating a context from within an output handler callable with ob_start():
+ // not possible with old API
+ php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_GET_OPAQ, (void *) &custom_ctx_ptr_ptr TSRMLS_CC);
+
+ Disabling of the output handler by itself:
+ //not possible with old API
+ php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_DISABLE, NULL TSRMLS_CC);
+
+ Marking an output handler immutable by itself because of irreversibility of its operation:
+ // not possible with old API
+ php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_IMMUTABLE, NULL TSRMLS_CC);
+
+ Restarting the output handler because of a CLEAN operation:
+ // not possible with old API
+ if (flags & PHP_OUTPUT_HANDLER_CLEAN) { ... }
+
+ Recognizing by the output handler itself if it gets discarded:
+ // not possible with old API
+ if ((flags & PHP_OUTPUT_HANDLER_CLEAN) && (flags & PHP_OUTPUT_HANDLER_FINAL)) { ... }
+
+
+Output handler hooks
+
+ The output handler can change its abilities at runtime. Eg. the gz handler can
+ remove the CLEANABLE and REMOVABLE bits when the first output has passed through it;
+ or handlers implemented in C to be used with ob_start() can contain a non-global
+ context:
+ PHP_OUTPUT_HANDLER_HOOK_GET_OPAQ
+ pass a void*** pointer as second arg to receive the address of a pointer
+ pointer to the opaque field of the output handler context
+ PHP_OUTPUT_HANDLER_HOOK_GET_FLAGS
+ pass a int* pointer as second arg to receive the flags set for the output handler
+ PHP_OUTPUT_HANDLER_HOOK_GET_LEVEL
+ pass a int* pointer as second arg to receive the level of this output handler
+ (starts with 0)
+ PHP_OUTPUT_HANDLER_HOOK_IMMUTABLE
+ the second arg is ignored; marks the output handler to be neither cleanable
+ nor removable
+ PHP_OUTPUT_HANDLER_HOOK_DISABLE
+ the second arg is ignored; marks the output handler as disabled
+
+
+Open questions
+
+ Should the userland API be adjusted and unified?
+
+ Many bits of the manual (and very first implementation) do not comply
+ with the behaviour of the current (to be obsoleted) code, thus should
+ the manual or the behaviour be adjusted?
+
+END
+$Id: README.NEW-OUTPUT-API 219039 2006-08-30 07:39:09Z mike $
+
+
+API adjustment to the old output control code:
+
+ Everything now resides beneath the php_output namespace,
+ and there's an API call for every output handler op.
+
+ Checking output control layers status:
+ // Using OG()
+ php_output_get_status(TSRMLS_C);
+
+ Starting the default output handler:
+ // php_start_ob_buffer(NULL, 0, 1 TSRMLS_CC);
+ php_output_start_default(TSRMLS_C);
+
+ Starting an user handler by zval:
+ // php_start_ob_buffer(zhandler, chunk_size, erase TSRMLS_CC);
+ php_output_start_user(zhandler, chunk_size, flags TSRMLS_CC);
+
+ Starting an internal handler whithout context:
+ // php_ob_set_internal_handler(my_php_output_handler_func_t, buffer_size, "output handler name", erase TSRMLS_CC);
+ php_output_start_internal(handler_name_zval, my_php_output_handler_func_t, chunk_size, flags TSRMLS_CC);
+
+ Starting an internal handler with context:
+ // not possible with old API
+ php_output_handler *h;
+ h = php_output_handler_create_internal(handler_name_zval, my_php_output_handler_context_func_t, chunk_size, flags TSRMLS_CC);
+ php_output_handler_set_context(h, my_context, my_context_dtor);
+ php_output_handler_start(h TSRMLS_CC);
+
+ Testing whether a certain output handler has already been started:
+ // php_ob_handler_used("output handler name" TSRMLS_CC);
+ php_output_handler_started(handler_name_zval TSRMLS_CC);
+
+ Flushing one output buffer:
+ // php_ob_end_buffer(1, 1 TSRMLS_CC);
+ php_output_flush(TSRMLS_C);
+
+ Flushing all output buffers:
+ // not possible with old API
+ php_output_flush_all(TSRMLS_C);
+
+ Cleaning one output buffer:
+ // php_ob_end_buffer(0, 1 TSRMLS_CC);
+ php_output_clean(TSRMLS_C);
+
+ Cleaning all output buffers:
+ // not possible with old API
+ php_output_clean_all(TSRMLS_C);
+
+ Discarding one output buffer:
+ // php_ob_end_buffer(0, 0 TSRMLS_CC);
+ php_output_discard(TSRMLS_C);
+
+ Discarding all output buffers:
+ // php_ob_end_buffers(0 TSRMLS_CC);
+ php_output_discard_all(TSRMLS_C);
+
+ Stopping (and dropping) one output buffer:
+ // php_ob_end_buffer(1, 0 TSRMLS_CC)
+ php_output_end(TSRMLS_C);
+
+ Stopping (and dropping) all output buffers:
+ // php_ob_end_buffers(1, 0 TSRMLS_CC);
+ php_output_end_all(TSRMLS_C);
+
+ Retrieving output buffers contents:
+ // php_ob_get_buffer(zstring TSRMLS_CC);
+ php_output_get_contents(zstring TSRMLS_CC);
+
+ Retrieving output buffers length:
+ // php_ob_get_length(zlength TSRMLS_CC);
+ php_output_get_length(zlength TSRMLS_CC);
+
+ Retrieving output buffering level:
+ // OG(nesting_level);
+ php_output_get_level(TSRMLS_C);
+
+ Issue a warning because of an output handler conflict:
+ // php_ob_init_conflict("to be started handler name", "to be tested if already started handler name" TSRMLS_CC);
+ php_output_handler_conflict(new_handler_name_zval, set_handler_name_zval TSRMLS_CC);
+
+ Registering a conflict checking function, which will be checked prior starting the handler:
+ // not possible with old API, unless hardcoding into output.c
+ php_output_handler_conflict_register(handler_name_zval, my_php_output_handler_conflict_check_t TSRMLS_CC);
+
+ Registering a reverse conflict checking function, which will be checked prior starting the specified foreign handler:
+ // not possible with old API
+ php_output_handler_reverse_conflict_register(foreign_handler_name_zval, my_php_output_handler_conflict_check_t TSRMLS_CC);
+
+ Facilitating a context from within an output handler callable with ob_start():
+ // not possible with old API
+ php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_GET_OPAQ, (void *) &custom_ctx_ptr_ptr TSRMLS_CC);
+
+ Disabling of the output handler by itself:
+ //not possible with old API
+ php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_DISABLE, NULL TSRMLS_CC);
+
+ Marking an output handler immutable by itself because of irreversibility of its operation:
+ // not possible with old API
+ php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_IMMUTABLE, NULL TSRMLS_CC);
+
+ Restarting the output handler because of a CLEAN operation:
+ // not possible with old API
+ if (flags & PHP_OUTPUT_HANDLER_CLEAN) { ... }
+
+ Recognizing by the output handler itself if it gets discarded:
+ // not possible with old API
+ if ((flags & PHP_OUTPUT_HANDLER_CLEAN) && (flags & PHP_OUTPUT_HANDLER_FINAL)) { ... }
+
+
+Output handler hooks
+
+ The output handler can change its abilities at runtime. Eg. the gz handler can
+ remove the CLEANABLE and REMOVABLE bits when the first output has passed through it;
+ or handlers implemented in C to be used with ob_start() can contain a non-global
+ context:
+ PHP_OUTPUT_HANDLER_HOOK_GET_OPAQ
+ pass a void*** pointer as second arg to receive the address of a pointer
+ pointer to the opaque field of the output handler context
+ PHP_OUTPUT_HANDLER_HOOK_GET_FLAGS
+ pass a int* pointer as second arg to receive the flags set for the output handler
+ PHP_OUTPUT_HANDLER_HOOK_GET_LEVEL
+ pass a int* pointer as second arg to receive the level of this output handler
+ (starts with 0)
+ PHP_OUTPUT_HANDLER_HOOK_IMMUTABLE
+ the second arg is ignored; marks the output handler to be neither cleanable
+ nor removable
+ PHP_OUTPUT_HANDLER_HOOK_DISABLE
+ the second arg is ignored; marks the output handler as disabled
+
+
+Open questions
+
+ Should the userland API be adjusted and unified?
+
+ Many bits of the manual (and very first implementation) do not comply
+ with the behaviour of the current (to be obsoleted) code, thus should
+ the manual or the behaviour be adjusted?
+
+END
+$Id: README.NEW-OUTPUT-API 219039 2006-08-30 07:39:09Z mike $
+
+
+API adjustment to the old output control code:
+
+ Everything now resides beneath the php_output namespace,
+ and there's an API call for every output handler op.
+
+ Checking output control layers status:
+ // Using OG()
+ php_output_get_status(TSRMLS_C);
+
+ Starting the default output handler:
+ // php_start_ob_buffer(NULL, 0, 1 TSRMLS_CC);
+ php_output_start_default(TSRMLS_C);
+
+ Starting an user handler by zval:
+ // php_start_ob_buffer(zhandler, chunk_size, erase TSRMLS_CC);
+ php_output_start_user(zhandler, chunk_size, flags TSRMLS_CC);
+
+ Starting an internal handler whithout context:
+ // php_ob_set_internal_handler(my_php_output_handler_func_t, buffer_size, "output handler name", erase TSRMLS_CC);
+ php_output_start_internal(handler_name_zval, my_php_output_handler_func_t, chunk_size, flags TSRMLS_CC);
+
+ Starting an internal handler with context:
+ // not possible with old API
+ php_output_handler *h;
+ h = php_output_handler_create_internal(handler_name_zval, my_php_output_handler_context_func_t, chunk_size, flags TSRMLS_CC);
+ php_output_handler_set_context(h, my_context, my_context_dtor);
+ php_output_handler_start(h TSRMLS_CC);
+
+ Testing whether a certain output handler has already been started:
+ // php_ob_handler_used("output handler name" TSRMLS_CC);
+ php_output_handler_started(handler_name_zval TSRMLS_CC);
+
+ Flushing one output buffer:
+ // php_ob_end_buffer(1, 1 TSRMLS_CC);
+ php_output_flush(TSRMLS_C);
+
+ Flushing all output buffers:
+ // not possible with old API
+ php_output_flush_all(TSRMLS_C);
+
+ Cleaning one output buffer:
+ // php_ob_end_buffer(0, 1 TSRMLS_CC);
+ php_output_clean(TSRMLS_C);
+
+ Cleaning all output buffers:
+ // not possible with old API
+ php_output_clean_all(TSRMLS_C);
+
+ Discarding one output buffer:
+ // php_ob_end_buffer(0, 0 TSRMLS_CC);
+ php_output_discard(TSRMLS_C);
+
+ Discarding all output buffers:
+ // php_ob_end_buffers(0 TSRMLS_CC);
+ php_output_discard_all(TSRMLS_C);
+
+ Stopping (and dropping) one output buffer:
+ // php_ob_end_buffer(1, 0 TSRMLS_CC)
+ php_output_end(TSRMLS_C);
+
+ Stopping (and dropping) all output buffers:
+ // php_ob_end_buffers(1, 0 TSRMLS_CC);
+ php_output_end_all(TSRMLS_C);
+
+ Retrieving output buffers contents:
+ // php_ob_get_buffer(zstring TSRMLS_CC);
+ php_output_get_contents(zstring TSRMLS_CC);
+
+ Retrieving output buffers length:
+ // php_ob_get_length(zlength TSRMLS_CC);
+ php_output_get_length(zlength TSRMLS_CC);
+
+ Retrieving output buffering level:
+ // OG(nesting_level);
+ php_output_get_level(TSRMLS_C);
+
+ Issue a warning because of an output handler conflict:
+ // php_ob_init_conflict("to be started handler name", "to be tested if already started handler name" TSRMLS_CC);
+ php_output_handler_conflict(new_handler_name_zval, set_handler_name_zval TSRMLS_CC);
+
+ Registering a conflict checking function, which will be checked prior starting the handler:
+ // not possible with old API, unless hardcoding into output.c
+ php_output_handler_conflict_register(handler_name_zval, my_php_output_handler_conflict_check_t TSRMLS_CC);
+
+ Registering a reverse conflict checking function, which will be checked prior starting the specified foreign handler:
+ // not possible with old API
+ php_output_handler_reverse_conflict_register(foreign_handler_name_zval, my_php_output_handler_conflict_check_t TSRMLS_CC);
+
+ Facilitating a context from within an output handler callable with ob_start():
+ // not possible with old API
+ php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_GET_OPAQ, (void *) &custom_ctx_ptr_ptr TSRMLS_CC);
+
+ Disabling of the output handler by itself:
+ //not possible with old API
+ php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_DISABLE, NULL TSRMLS_CC);
+
+ Marking an output handler immutable by itself because of irreversibility of its operation:
+ // not possible with old API
+ php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_IMMUTABLE, NULL TSRMLS_CC);
+
+ Restarting the output handler because of a CLEAN operation:
+ // not possible with old API
+ if (flags & PHP_OUTPUT_HANDLER_CLEAN) { ... }
+
+ Recognizing by the output handler itself if it gets discarded:
+ // not possible with old API
+ if ((flags & PHP_OUTPUT_HANDLER_CLEAN) && (flags & PHP_OUTPUT_HANDLER_FINAL)) { ... }
+
+
+Output handler hooks
+
+ The output handler can change its abilities at runtime. Eg. the gz handler can
+ remove the CLEANABLE and REMOVABLE bits when the first output has passed through it;
+ or handlers implemented in C to be used with ob_start() can contain a non-global
+ context:
+ PHP_OUTPUT_HANDLER_HOOK_GET_OPAQ
+ pass a void*** pointer as second arg to receive the address of a pointer
+ pointer to the opaque field of the output handler context
+ PHP_OUTPUT_HANDLER_HOOK_GET_FLAGS
+ pass a int* pointer as second arg to receive the flags set for the output handler
+ PHP_OUTPUT_HANDLER_HOOK_GET_LEVEL
+ pass a int* pointer as second arg to receive the level of this output handler
+ (starts with 0)
+ PHP_OUTPUT_HANDLER_HOOK_IMMUTABLE
+ the second arg is ignored; marks the output handler to be neither cleanable
+ nor removable
+ PHP_OUTPUT_HANDLER_HOOK_DISABLE
+ the second arg is ignored; marks the output handler as disabled
+
+
+Open questions
+
+ Should the userland API be adjusted and unified?
+
+ Many bits of the manual (and very first implementation) do not comply
+ with the behaviour of the current (to be obsoleted) code, thus should
+ the manual or the behaviour be adjusted?
+
+END