Return to README.NEW-OUTPUT-API CVS log

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

php 5.4.3+patches

    1: $Id: README.NEW-OUTPUT-API,v 1.1.1.1 2012/05/29 12:34:34 misho Exp $
    2: 
    3: 
    4: API adjustment to the old output control code:
    5: 
    6: 	Everything now resides beneath the php_output namespace, 
    7: 	and there's an API call for every output handler op.
    8: 
    9: 	Checking output control layers status:
   10: 		// Using OG()
   11: 		php_output_get_status(TSRMLS_C);
   12: 
   13: 	Starting the default output handler:
   14: 		// php_start_ob_buffer(NULL, 0, 1 TSRMLS_CC);
   15: 		php_output_start_default(TSRMLS_C);
   16: 
   17: 	Starting an user handler by zval:
   18: 		// php_start_ob_buffer(zhandler, chunk_size, erase TSRMLS_CC);
   19: 		php_output_start_user(zhandler, chunk_size, flags TSRMLS_CC);
   20: 
   21: 	Starting an internal handler whithout context:
   22: 		// php_ob_set_internal_handler(my_php_output_handler_func_t, buffer_size, "output handler name", erase TSRMLS_CC);
   23: 		php_output_start_internal(handler_name, handler_name_len, my_php_output_handler_func_t, chunk_size, flags TSRMLS_CC);
   24: 
   25: 	Starting an internal handler with context:
   26: 		// not possible with old API
   27: 		php_output_handler *h;
   28: 		h = php_output_handler_create_internal(handler_name, handler_name_len, my_php_output_handler_context_func_t, chunk_size, flags TSRMLS_CC);
   29: 		php_output_handler_set_context(h, my_context, my_context_dtor);
   30: 		php_output_handler_start(h TSRMLS_CC);
   31: 
   32: 	Testing whether a certain output handler has already been started:
   33: 		// php_ob_handler_used("output handler name" TSRMLS_CC);
   34: 		php_output_handler_started(handler_name, handler_name_len TSRMLS_CC);
   35: 
   36: 	Flushing one output buffer:
   37: 		// php_ob_end_buffer(1, 1 TSRMLS_CC);
   38: 		php_output_flush(TSRMLS_C);
   39: 
   40: 	Flushing all output buffers:
   41: 		// not possible with old API
   42: 		php_output_flush_all(TSRMLS_C);
   43: 
   44: 	Cleaning one output buffer:
   45: 		// php_ob_end_buffer(0, 1 TSRMLS_CC);
   46: 		php_output_clean(TSRMLS_C);
   47: 
   48: 	Cleaning all output buffers:
   49: 		// not possible with old API
   50: 		php_output_clean_all(TSRMLS_C);
   51: 
   52: 	Discarding one output buffer:
   53: 		// php_ob_end_buffer(0, 0 TSRMLS_CC);
   54: 		php_output_discard(TSRMLS_C);
   55: 
   56: 	Discarding all output buffers:
   57: 		// php_ob_end_buffers(0 TSRMLS_CC);
   58: 		php_output_discard_all(TSRMLS_C);
   59: 
   60: 	Stopping (and dropping) one output buffer:
   61: 		// php_ob_end_buffer(1, 0 TSRMLS_CC)
   62: 		php_output_end(TSRMLS_C);
   63: 
   64: 	Stopping (and dropping) all output buffers:
   65: 		// php_ob_end_buffers(1, 0 TSRMLS_CC);
   66: 		php_output_end_all(TSRMLS_C);
   67: 
   68: 	Retrieving output buffers contents:
   69: 		// php_ob_get_buffer(zstring TSRMLS_CC);
   70: 		php_output_get_contents(zstring TSRMLS_CC);
   71: 
   72: 	Retrieving output buffers length:
   73: 		// php_ob_get_length(zlength TSRMLS_CC);
   74: 		php_output_get_length(zlength TSRMLS_CC);
   75: 
   76: 	Retrieving output buffering level:
   77: 		// OG(nesting_level);
   78: 		php_output_get_level(TSRMLS_C);
   79: 
   80: 	Issue a warning because of an output handler conflict:
   81: 		// php_ob_init_conflict("to be started handler name", "to be tested if already started handler name" TSRMLS_CC);
   82: 		php_output_handler_conflict(new_handler_name, new_handler_name_len, set_handler_name, set_handler_name_len TSRMLS_CC);
   83: 
   84: 	Registering a conflict checking function, which will be checked prior starting the handler:
   85: 		// not possible with old API, unless hardcoding into output.c
   86: 		php_output_handler_conflict_register(handler_name, handler_name_len, my_php_output_handler_conflict_check_t TSRMLS_CC);
   87: 
   88: 	Registering a reverse conflict checking function, which will be checked prior starting the specified foreign handler:
   89: 		// not possible with old API
   90: 		php_output_handler_reverse_conflict_register(foreign_handler_name, foreign_handler_name_len, my_php_output_handler_conflict_check_t TSRMLS_CC);
   91: 
   92: 	Facilitating a context from within an output handler callable with ob_start():
   93: 		// not possible with old API
   94: 		php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_GET_OPAQ, (void *) &custom_ctx_ptr_ptr TSRMLS_CC);
   95: 
   96: 	Disabling of the output handler by itself:
   97: 		//not possible with old API
   98: 		php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_DISABLE, NULL TSRMLS_CC);
   99: 
  100: 	Marking an output handler immutable by itself because of irreversibility of its operation:
  101: 		// not possible with old API
  102: 		php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_IMMUTABLE, NULL TSRMLS_CC);
  103: 
  104: 	Restarting the output handler because of a CLEAN operation:
  105: 		// not possible with old API
  106: 		if (flags & PHP_OUTPUT_HANDLER_CLEAN) { ... }
  107: 
  108: 	Recognizing by the output handler itself if it gets discarded:
  109: 		// not possible with old API
  110: 		if ((flags & PHP_OUTPUT_HANDLER_CLEAN) && (flags & PHP_OUTPUT_HANDLER_FINAL)) { ... }
  111: 
  112: 
  113: Output handler hooks
  114: 
  115: 	The output handler can change its abilities at runtime. Eg. the gz handler can
  116: 	remove the CLEANABLE and REMOVABLE bits when the first output has passed through it;
  117: 	or handlers implemented in C to be used with ob_start() can contain a non-global
  118: 	context:
  119: 		PHP_OUTPUT_HANDLER_HOOK_GET_OPAQ
  120: 			pass a void*** pointer as second arg to receive the address of a pointer
  121: 			pointer to the opaque field of the output handler context
  122: 		PHP_OUTPUT_HANDLER_HOOK_GET_FLAGS
  123: 			pass a int* pointer as second arg to receive the flags set for the output handler
  124: 		PHP_OUTPUT_HANDLER_HOOK_GET_LEVEL
  125: 			pass a int* pointer as second arg to receive the level of this output handler
  126: 			(starts with 0)
  127: 		PHP_OUTPUT_HANDLER_HOOK_IMMUTABLE
  128: 			the second arg is ignored; marks the output handler to be neither cleanable
  129: 			nor removable
  130: 		PHP_OUTPUT_HANDLER_HOOK_DISABLE
  131: 			the second arg is ignored; marks the output handler as disabled
  132: 
  133: 
  134: Open questions
  135: 
  136: 	Should the userland API be adjusted and unified?
  137: 	
  138: 	Many bits of the manual (and very first implementation) do not comply
  139: 	with the behaviour of the current (to be obsoleted) code, thus should
  140: 	the manual or the behaviour be adjusted?
  141: 
  142: END