|
| 1 | +$Id: README.NEW-OUTPUT-API 219039 2006-08-30 07:39:09Z mike $ |
| 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_zval, 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_zval, 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_zval 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_zval, set_handler_name_zval 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_zval, 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_zval, 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 |
0 commit comments