* implement new output API, fixing some bugs and implementing some feature

  requests--let's see what I can dig out of the bugtracker for NEWS--
  and while crossing the road:
   * implemented new zlib API
   * fixed up ext/tidy (what was "s&" in zend_parse_parameters() supposed to do?)

Thanks to Jani and Felipe for pioneering.

1 files changed, 426 insertions, 0 deletions

diff --git a/README.NEW-OUTPUT-API b/README.NEW-OUTPUT-API
new file mode 100644
index 0000000000..82e3f485b5
--- /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