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