Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 143 lines (106 sloc) 5.585 kb
11d24c1 @m6w6 * implement new output API, fixing some bugs and implementing some featu...
m6w6 authored
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);
846a376 @m6w6 fix protos, and unintential double-patched content
m6w6 authored
23 php_output_start_internal(handler_name, handler_name_len, my_php_output_handler_func_t, chunk_size, flags TSRMLS_CC);
11d24c1 @m6w6 * implement new output API, fixing some bugs and implementing some featu...
m6w6 authored
24
25 Starting an internal handler with context:
26 // not possible with old API
27 php_output_handler *h;
846a376 @m6w6 fix protos, and unintential double-patched content
m6w6 authored
28 h = php_output_handler_create_internal(handler_name, handler_name_len, my_php_output_handler_context_func_t, chunk_size, flags TSRMLS_CC);
11d24c1 @m6w6 * implement new output API, fixing some bugs and implementing some featu...
m6w6 authored
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);
846a376 @m6w6 fix protos, and unintential double-patched content
m6w6 authored
34 php_output_handler_started(handler_name, handler_name_len TSRMLS_CC);
11d24c1 @m6w6 * implement new output API, fixing some bugs and implementing some featu...
m6w6 authored
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);
846a376 @m6w6 fix protos, and unintential double-patched content
m6w6 authored
82 php_output_handler_conflict(new_handler_name, new_handler_name_len, set_handler_name, set_handler_name_len TSRMLS_CC);
11d24c1 @m6w6 * implement new output API, fixing some bugs and implementing some featu...
m6w6 authored
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
846a376 @m6w6 fix protos, and unintential double-patched content
m6w6 authored
86 php_output_handler_conflict_register(handler_name, handler_name_len, my_php_output_handler_conflict_check_t TSRMLS_CC);
11d24c1 @m6w6 * implement new output API, fixing some bugs and implementing some featu...
m6w6 authored
87
88 Registering a reverse conflict checking function, which will be checked prior starting the specified foreign handler:
89 // not possible with old API
846a376 @m6w6 fix protos, and unintential double-patched content
m6w6 authored
90 php_output_handler_reverse_conflict_register(foreign_handler_name, foreign_handler_name_len, my_php_output_handler_conflict_check_t TSRMLS_CC);
11d24c1 @m6w6 * implement new output API, fixing some bugs and implementing some featu...
m6w6 authored
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
Something went wrong with that request. Please try again.