HTTP Class Technical Documentation (diff)

Difference between revisions for Users / Eo Ny / dev

Version1		Version2
1	~~# HTTP Class Technical Documentation~~	1	== HTTP Class Technical Documentation ==
2		2
3	~~## Overview~~	3	=== Overview ===
4		4
5	The ~~`Http` class (`src/class/http.php`~~) is a core component of the WackoWiki system responsible for handling HTTP request/response processing, session management, caching, and security features. This class acts as a bridge between the web server and the wiki engine.	5	The ##Http## class (##src/class/http.php##) is a core component of the WackoWiki system responsible for handling HTTP request/response processing, session management, caching, and security features. This class acts as a bridge between the web server and the wiki engine.
6		6
7	File Location: ~~`src/class/http.php`~~	7	File Location: ##src/class/http.php##
8	Language: PHP	8	Language: PHP
9	Dependencies: Database class, Session classes, Utility classes (`Ut`), Diagnostics class (`Diag`)	9	Dependencies: Database class, Session classes, Utility classes (##Ut##), Diagnostics class (##Diag##)
10		10
11	---	11	----
12		12
13	## Class Properties	13	=== Class Properties ===
14		14
15	### Public Properties	15	====Public Properties====
16		16
17	\| Property \| Type \| Description \|	17	#\|
18	\|----------\|------\|-------------\|	18	\| Property \| Type \| Description \|
19	\| `$tls_session` \| bool \| Indicates if the current session uses HTTPS/TLS encryption \|	19	\|\| ##$tls_session## \| bool \| Indicates if the current session uses HTTPS/TLS encryption \|\|
20	\| `$request_uri` \| string \| Normalized REQUEST_URI (e.g., 'PageOfNoReturn/show?a=1') \|	20	\|\| ##$request_uri## \| string \| Normalized REQUEST_URI (e.g., 'PageOfNoReturn/show?a=1') \|\|
21	\| `$ip` \| string \| Client's real IP address (accounts for proxies) \|	21	\|\| ##$ip## \| string \| Client's real IP address (accounts for proxies) \|\|
22	\| `$sess` \| Session \| Reference to the Session object \|	22	\|\| ##$sess## \| Session \| Reference to the Session object \|\|
23	\| `$method` \| string \| Current HTTP method/request type \|	23	\|\| ##$method## \| string \| Current HTTP method/request type \|\|
24		24	\|#
25	### Private Properties	25
26		26	==== Private Properties ====
27	\| Property \| Type \| Description \|	27
28	\|----------\|------\|-------------\|	28
29	\| `$db` \| object \| Database connection reference \|	29	=== Constructor ===
30	\| `$tls_mark` \| string \| Cookie name for TLS session marking \|	30
31	\| `$page` \| string \| Current page name being processed \|	31	%%php
32	\| `$hash` \| string \| SHA1 hash of the page name \|
33	\| `$query` \| string \| Encoded query string \|
34	\| `$lang` \| string \| Current language code \|
35	\| `$file` \| string \| Cache file path \|
36	\| `$caching` \| int \| Flag indicating if page should be cached (0 or 1) \|
37
38	---
39
40	## Constructor
41
42	```php
43	public function __construct(&$db)	32	public function __construct(&$db)
44	~~```~~	33	%%
45		34
46	Purpose: Initializes the Http object and sets up HTTP session handling.	35	Purpose: Initializes the Http object and sets up HTTP session handling.
47		36
48	Parameters:	37	Parameters:
49	~~- `$db`~~ - Database object reference	38	- ##$db## - Database object reference
50		39
51	Initialization Steps:	40	Initialization Steps:
52	1. Stores database reference	41	1. Stores database reference
53	2. Extracts and normalizes REQUEST_URI	42	2. Extracts and normalizes REQUEST_URI
54	3. Detects TLS/HTTPS session status	43	3. Detects TLS/HTTPS session status
55	4. Determines client's real IP address	44	4. Determines client's real IP address
56	5. Sets up TLS mark cookie name	45	5. Sets up TLS mark cookie name
57	6. Enforces TLS session upgrade if needed	46	6. Enforces TLS session upgrade if needed
58		47
59	Example:	48	Example:
60	~~```~~php	49	%%php
61	$http = new Http($db);	50	$http = new Http($db);
62	~~```~~	51	%%
63		52
64	---	53	----
65		54
66	~~## Core Methods~~	55	=== Core Methods ===
67		56
68	~~### Session Management~~	57	==== Session Management ====
69		58
70	~~#### `session($route): void`~~	59	===== ##session($route): void## =====
71	Initializes the session handler (file-based or database-based).	60	Initializes the session handler (file-based or database-based).
72		61
73	Parameters:	62	Parameters:
74	~~- `$route`~~ (int) - Routing flag:	63	- ##$route## (int) - Routing flag:
75	- Bit 2 (~~`$route & 2`~~): Enable static mode for files/freecap (disables replay prevention and ID regeneration)	64	- Bit 2 (##$route & 2##): Enable static mode for files/freecap (disables replay prevention and ID regeneration)
76		65
77	Features:	66	Features:
78	- Selects storage backend (file or database)	67	- Selects storage backend (file or database)
79	- Configures cookie settings (security, path, httponly)	68	- Configures cookie settings (security, path, httponly)
80	- Binds IP and TLS validation	69	- Binds IP and TLS validation
81	- Recovers diagnostic logs from previous session	70	- Recovers diagnostic logs from previous session
82		71
83	Example:	72	Example:
84	~~```~~php	73	%%php
85	$http->session(0); // Normal session	74	$http->session(0); // Normal session
86	$http->session(2); // Static file serving mode	75	$http->session(2); // Static file serving mode
87	~~```~~	76	%%
88		77
89	---	78	----
90		79
91	~~### Caching System~~	80	==== Caching System ====
92		81
93	~~#### `check_cache($page, $method): void`~~	82	===== ##check_cache($page, $method): void## =====
94	Determines if a page can be cached and prepares the cache check.	83	Determines if a page can be cached and prepares the cache check.
95		84
96	Parameters:	85	Parameters:
97	~~- `$page`~~ (string) - Page name to cache	86	- ##$page## (string) - Page name to cache
98	~~- `$method`~~ (string) - Request method/action (e.g., 'show', 'edit')	87	- ##$method## (string) - Request method/action (e.g., 'show', 'edit')
99		88
100	Caching Rules:	89	Caching Rules:
101	- ✅ Enabled for GET requests only	90	- ✅ Enabled for GET requests only
102	- ✅ Disabled for POST requests	91	- ✅ Disabled for POST requests
103	- ❌ Never cached for 'edit' or 'watch' methods	92	- ❌ Never cached for 'edit' or 'watch' methods
104	- ✅ Only cached for anonymous users (no logged-in users)	93	- ✅ Only cached for anonymous users (no logged-in users)
105		94
106	Example:	95	Example:
107	~~```~~php	96	%%php
108	$http->check_cache('HomePage', 'show');	97	$http->check_cache('HomePage', 'show');
109	~~```~~	98	%%
110		99
111	---	100	----
112		101
113	~~#### `store_cache(): void`~~	102	===== ##store_cache(): void## =====
114	Saves the generated page content to cache file.	103	Saves the generated page content to cache file.
115		104
116	Features:	105	Features:
117	- Retrieves output buffer content	106	- Retrieves output buffer content
118	- Saves to cache file with proper permissions	107	- Saves to cache file with proper permissions
119	- Records cache metadata in database	108	- Records cache metadata in database
120	- Only executes if caching flag is set and user is anonymous	109	- Only executes if caching flag is set and user is anonymous
121		110
122	Example:	111	Example:
123	~~```~~php	112	%%php
124	// Called at end of page rendering	113	// Called at end of page rendering
125	$http->store_cache();	114	$http->store_cache();
126	~~```~~	115	%%
127		116
128	---	117	----
129		118
130	~~#### `invalidate_page($page): int`~~	119	===== ##invalidate_page($page): int## =====
131	Invalidates all cached versions of a page.	120	Invalidates all cached versions of a page.
132		121
133	Parameters:	122	Parameters:
134	~~- `$page`~~ (string) - Page name to invalidate	123	- ##$page## (string) - Page name to invalidate
135		124
136	Returns:	125	Returns:
137	- Number of cache entries invalidated	126	- Number of cache entries invalidated
138		127
139	Process:	128	Process:
140	1. Finds all cached versions (different methods/languages)	129	1. Finds all cached versions (different methods/languages)
141	2. Touches files to past timestamp (faster than deletion)	130	2. Touches files to past timestamp (faster than deletion)
142	3. Removes entries from cache metadata table	131	3. Removes entries from cache metadata table
143	4. Returns count of invalidated caches	132	4. Returns count of invalidated caches
144		133
145	Example:	134	Example:
146	~~```~~php	135	%%php
147	$count = $http->invalidate_page('HomePage');	136	$count = $http->invalidate_page('HomePage');
148	echo "Invalidated $count cache entries";	137	echo "Invalidated $count cache entries";
149	~~```~~	138	%%
150		139
151	---	140	----
152		141
153	~~### TLS/HTTPS Security~~	142	==== TLS/HTTPS Security ====
154		143
155	~~#### `secure_base_url(): void`~~	144	===== ##secure_base_url(): void## =====
156	Switches base URL from HTTP to HTTPS.	145	Switches base URL from HTTP to HTTPS.
157		146
158	Purpose:	147	Purpose:
159	- Ensures all subsequent URLs use HTTPS	148	- Ensures all subsequent URLs use HTTPS
160	- Stores original HTTP URL for fallback	149	- Stores original HTTP URL for fallback
161	- Called when TLS session is detected	150	- Called when TLS session is detected
162		151
163	Example:	152	Example:
164	~~```~~php	153	%%php
165	$http->secure_base_url();	154	$http->secure_base_url();
166	// $db->base_url now uses https://	155	// $db->base_url now uses https://
167	~~```~~	156	%%
168		157
169	---	158	----
170		159
171	~~#### `ensure_tls($url): void`~~	160	===== ##ensure_tls($url): void## =====
172	Enforces HTTPS for a specific URL and redirects if necessary.	161	Enforces HTTPS for a specific URL and redirects if necessary.
173		162
174	Parameters:	163	Parameters:
175	~~- `$url`~~ (string) - URL to secure	164	- ##$url## (string) - URL to secure
176		165
177	Behavior:	166	Behavior:
178	- If not already HTTPS and TLS is enabled, forces HTTPS redirect	167	- If not already HTTPS and TLS is enabled, forces HTTPS redirect
179	- Handles both relative and absolute URLs	168	- Handles both relative and absolute URLs
180	- Converts relative URLs using current server name	169	- Converts relative URLs using current server name
181		170
182	Example:	171	Example:
183	~~```~~php	172	%%php
184	$http->ensure_tls('/secure/payment');	173	$http->ensure_tls('/secure/payment');
185	~~```~~	174	%%
186		175
187	---	176	----
188		177
189	~~### IP Address Detection~~	178	==== IP Address Detection ====
190		179
191	~~#### `real_ip(): string` (Private)~~	180	===== ##real_ip(): string## (Private) =====
192	Detects client's real IP address accounting for proxies.	181	Detects client's real IP address accounting for proxies.
193		182
194	Proxy Headers Checked (in order):	183	Proxy Headers Checked (in order):
195	~~1. `HTTP_X_CLUSTER_CLIENT_IP`~~	184	1. ##HTTP_X_CLUSTER_CLIENT_IP##
196	~~2. `HTTP_X_FORWARDED_FOR`~~ (or custom header)	185	2. ##HTTP_X_FORWARDED_FOR## (or custom header)
197	~~3. `HTTP_CLIENT_IP`~~	186	3. ##HTTP_CLIENT_IP##
198	~~4. `HTTP_X_REMOTE_ADDR`~~	187	4. ##HTTP_X_REMOTE_ADDR##
199	~~5. `REMOTE_ADDR`~~ (fallback)	188	5. ##REMOTE_ADDR## (fallback)
200		189
201	Features:	190	Features:
202	- Filters out private/reserved IP ranges	191	- Filters out private/reserved IP ranges
203	- Respects configured reverse proxy addresses	192	- Respects configured reverse proxy addresses
204	~~- Returns `'0.0.0.0'`~~ as fallback	193	- Returns ##'0.0.0.0'## as fallback
205		194
206	Configuration in Database:	195	Configuration in Database:
207	~~- `reverse_proxy_addresses`~~ - Comma/space-separated proxy IPs	196	- ##reverse_proxy_addresses## - Comma/space-separated proxy IPs
208	~~- `reverse_proxy_header` - Custom header name (default: `X-Forwarded-For`~~)	197	- ##reverse_proxy_header## - Custom header name (default: ##X-Forwarded-For##)
209		198
210	Example:	199	Example:
211	~~```~~php	200	%%php
212	$client_ip = $http->ip; // e.g., "203.0.113.42"	201	$client_ip = $http->ip; // e.g., "203.0.113.42"
213	~~```~~	202	%%
214		203
215	---	204	----
216		205
217	~~### HTTPS Detection~~	206	==== HTTPS Detection ====
218		207
219	~~#### `tls_session(): bool` (Private)~~	208	===== ##tls_session(): bool## (Private) =====
220	Detects if current connection uses HTTPS/TLS.	209	Detects if current connection uses HTTPS/TLS.
221		210
222	Checks (any being true = HTTPS):	211	Checks (any being true = HTTPS):
223	- `$_SERVER['HTTPS']` is 'on'	212	- ##$_SERVER['HTTPS']## is 'on'
224	- `$_SERVER['SERVER_PORT']` is 443	213	- ##$_SERVER['SERVER_PORT']## is 443
225	- `$_SERVER['HTTP_X_FORWARDED_PROTO']` is 'https'	214	- ##$_SERVER['HTTP_X_FORWARDED_PROTO']## is 'https'
226	- `$_SERVER['HTTP_X_FORWARDED_SSL']` is 'on'	215	- ##$_SERVER['HTTP_X_FORWARDED_SSL']## is 'on'
227	- `$_SERVER['HTTP_X_FORWARDED_PORT']` is 443	216	- ##$_SERVER['HTTP_X_FORWARDED_PORT']## is 443
228		217
229	---	218	----
230		219
231	### Security Headers	220	==== Security Headers ====
232		221
233	#### `http_security_headers(): void`	222	===== ##http_security_headers(): void## =====
234	Sets security-related HTTP headers.	223
235		224
236	Headers Set:	225	==== HTTP Methods ====
237		226
238	\| Header \| Purpose \| Config Key \|	227	===== ##redirect($url, $permanent = false): void## =====
239	\|--------\|---------\|------------\|
240	\| Content-Security-Policy \| XSS/injection protection \| `csp` \|
241	\| Permissions-Policy \| Control browser features \| `permissions_policy` \|
242	\| Referrer-Policy \| Control referrer information \| `referrer_policy` \|
243	\| Strict-Transport-Security \| Force HTTPS \| Auto (TLS only) \|
244	\| X-Frame-Options \| Clickjacking protection \| Hardcoded: `SAMEORIGIN` \|
245	\| X-Content-Type-Options \| MIME sniffing prevention \| Hardcoded: `nosniff` \|
246
247	CSP Configuration Options:
248	- `0` - Disabled
249	- `1` - Default policy (from `csp.conf`)
250	- `2` - Custom policy (from `csp_custom.conf`)
251
252	Example:
253	```php
254	$http->http_security_headers();
255	```
256
257	---
258
259	### HTTP Methods
260
261	#### `redirect($url, $permanent = false): void`
262	Performs an HTTP redirect.	228	Performs an HTTP redirect.
263		229
264	Parameters:	230	Parameters:
265	~~- `$url`~~ (string) - Target URL	231	- ##$url## (string) - Target URL
266	~~- `$permanent`~~ (bool) - Use 301 (permanent) vs 302 (temporary)	232	- ##$permanent## (bool) - Use 301 (permanent) vs 302 (temporary)
267		233
268	Features:	234	Features:
269	~~- Decodes `&`~~ entities to prevent broken redirects	235	- Decodes ##&## entities to prevent broken redirects
270	- Only works if headers not yet sent	236	- Only works if headers not yet sent
271	- Uses output buffering to work anywhere in page processing	237	- Uses output buffering to work anywhere in page processing
272		238
273	Example:	239	Example:
274	~~```~~php	240	%%php
275	$http->redirect('http://example.com/new-page', true); // 301	241	$http->redirect('http://example.com/new-page', true); // 301
276	$http->redirect('/wiki/HomePage'); // 302	242	$http->redirect('/wiki/HomePage'); // 302
277	~~```~~	243	%%
278		244
279	---	245	----
280		246
281	~~#### `terminate(): void`~~	247	===== ##terminate(): void## =====
282	Safe exit/die with cleanup.	248	Safe exit/die with cleanup.
283		249
284	Cleanup Operations:	250	Cleanup Operations:
285	- Saves diagnostic logs to session flash data	251	- Saves diagnostic logs to session flash data
286	- Ends script execution	252	- Ends script execution
287		253
288	Example:	254	Example:
289	~~```~~php	255	%%php
290	$http->terminate();	256	$http->terminate();
291	~~```~~	257	%%
292		258
293	---	259	----
294		260
295	~~#### `status($code): void`~~	261	===== ##status($code): void## =====
296	Sets HTTP response status code.	262	Sets HTTP response status code.
297		263
298	Supported Status Codes:	264	Supported Status Codes:
299	~~```~~php	265	%%php
300	200 => 'OK'	266	200 => 'OK'
301	206 => 'Partial Content'	267	206 => 'Partial Content'
302	301 => 'Moved Permanently'	268	301 => 'Moved Permanently'
…	…	…	…
313	500 => 'Internal Server Error'	279	500 => 'Internal Server Error'
314	501 => 'Not Implemented'	280	501 => 'Not Implemented'
315	503 => 'Service Unavailable'	281	503 => 'Service Unavailable'
316	~~```~~	282	%%
317		283
318	Example:	284	Example:
319	~~```~~php	285	%%php
320	$http->status(404); // Send 404 Not Found	286	$http->status(404); // Send 404 Not Found
321	~~```~~	287	%%
322		288
323	---	289	----
324		290
325	~~### Caching Control~~	291	==== Caching Control ====
326		292
327	~~#### `no_cache($client_only = true): void`~~	293	===== ##no_cache($client_only = true): void## =====
328	Disables caching of the current page.	294	Disables caching of the current page.
329		295
330	Parameters:	296	Parameters:
331	~~- `$client_only`~~ (bool, default: TRUE)	297	- ##$client_only## (bool, default: TRUE)
332	- ~~`TRUE`~~: Disable browser cache only	298	- ##TRUE##: Disable browser cache only
333	- ~~`FALSE`~~: Disable both browser and server cache	299	- ##FALSE##: Disable both browser and server cache
334		300
335	Headers Set:	301	Headers Set:
336	~~- `Last-Modified: <current-time>`~~ (always fresh)	302	- ##Last-Modified: <current-time>## (always fresh)
337	~~- `Cache-Control: no-store`~~	303	- ##Cache-Control: no-store##
338		304
339	Example:	305	Example:
340	~~```~~php	306	%%php
341	$http->no_cache(); // Client-side only	307	$http->no_cache(); // Client-side only
342	$http->no_cache(false); // Both client & server	308	$http->no_cache(false); // Both client & server
343	~~```~~	309	%%
344		310
345	---	311	----
346		312
347	~~#### `cache_promisc(): void`~~	313	===== ##cache_promisc(): void## =====
348	Marks page as publicly cacheable.	314	Marks page as publicly cacheable.
349		315
350	Headers Set:	316	Headers Set:
351	~~- `Cache-Control: public`~~	317	- ##Cache-Control: public##
352		318
353	Example:	319	Example:
354	~~```~~php	320	%%php
355	$http->cache_promisc();	321	$http->cache_promisc();
356	~~```~~	322	%%
357		323
358	---	324	----
359		325
360	~~### Language Negotiation~~	326	==== Language Negotiation ====
361		327
362	~~#### `user_agent_language(): string`~~	328	===== ##user_agent_language(): string## =====
363	Determines best language based on browser preferences.	329	Determines best language based on browser preferences.
364		330
365	Features:	331	Features:
366	- Follows RFC 9110 section 12.5.4 (HTTP Accept-Language)	332	- Follows RFC 9110 section 12.5.4 (HTTP Accept-Language)
367	~~- Parses `Accept-Language`~~ header with quality factors	333	- Parses ##Accept-Language## header with quality factors
368	- Attempts exact match first, then language fallback	334	- Attempts exact match first, then language fallback
369	- Falls back to default system language	335	- Falls back to default system language
370		336
371	Example Header:	337	Example Header:
372	~~```~~	338	%%
373	Accept-Language: en-US,en;q=0.9,de;q=0.8	339	Accept-Language: en-US,en;q=0.9,de;q=0.8
374	~~```~~	340	%%
375		341
376	Returns:	342	Returns:
377	- Language code (e.g., 'en', 'en-US', 'de')	343	- Language code (e.g., 'en', 'en-US', 'de')
378		344
379	---	345	----
380		346
381	~~#### `available_languages($subset = true): array`~~	347	===== ##available_languages($subset = true): array## =====
382	Returns list of available language translations.	348	Returns list of available language translations.
383		349
384	Parameters:	350	Parameters:
385	~~- `$subset`~~ (bool, default: TRUE)	351	- ##$subset## (bool, default: TRUE)
386	- ~~`TRUE`~~: Only allowed languages	352	- ##TRUE##: Only allowed languages
387	- ~~`FALSE`~~: All available languages	353	- ##FALSE##: All available languages
388		354
389	Features:	355	Features:
390	~~- Scans `LANG_DIR`~~ for language files	356	- Scans ##LANG_DIR## for language files
391	~~- Filters by `allowed_languages`~~ config if set	357	- Filters by ##allowed_languages## config if set
392	- Caches result in session	358	- Caches result in session
393	- System language always included	359	- System language always included
394		360
395	Returns:	361	Returns:
396	~~- Associative array: `['en' => 'en', 'de' => 'de', ...]`~~	362	- Associative array: ##['en' => 'en', 'de' => 'de', ...]##
397		363
398	Example:	364	Example:
399	~~```~~php	365	%%php
400	$all_langs = $http->available_languages(false);	366	$all_langs = $http->available_languages(false);
401	$allowed = $http->available_languages(true);	367	$allowed = $http->available_languages(true);
402	~~```~~	368	%%
403		369
404	---	370	----
405		371
406	~~### File Serving~~	372	==== File Serving ====
407		373
408	~~#### `sendfile($path, $filename = null, $age = null): void`~~	374	===== ##sendfile($path, $filename = null, $age = null): void## =====
409	Serves files with proper HTTP headers and caching.	375	Serves files with proper HTTP headers and caching.
410		376
411	Parameters:	377	Parameters:
412	~~- `$path`~~ (string) - File path (or HTTP_XXX constant for error pages)	378	- ##$path## (string) - File path (or HTTP_XXX constant for error pages)
413	~~- `$filename`~~ (string, optional) - Custom download filename	379	- ##$filename## (string, optional) - Custom download filename
414	~~- `$age`~~ (int, optional) - Cache age in days	380	- ##$age## (int, optional) - Cache age in days
415		381
416	Features:	382	Features:
417	- HTTP range request support (partial file downloads)	383	- HTTP range request support (partial file downloads)
418	- ETag and Last-Modified conditional requests	384	- ETag and Last-Modified conditional requests
419	- Proper MIME type detection	385	- Proper MIME type detection
420	- Content-Security-Policy for special file types	386	- Content-Security-Policy for special file types
421	- Streaming for large files	387	- Streaming for large files
422	- GZip compression for text files	388	- GZip compression for text files
423		389
424	Special Paths:	390	Special Paths:
425	~~```~~php	391	%%php
426	$http->sendfile(404); // Serves file defined by HTTP_404 constant	392	$http->sendfile(404); // Serves file defined by HTTP_404 constant
427	$http->sendfile(403); // Serves file defined by HTTP_403 constant	393	$http->sendfile(403); // Serves file defined by HTTP_403 constant
428	~~```~~	394	%%
429		395
430	Example:	396	Example:
431	~~```~~php	397	%%php
432	$http->sendfile('uploads/document.pdf', 'my-document.pdf', 30);	398	$http->sendfile('uploads/document.pdf', 'my-document.pdf', 30);
433	~~```~~	399	%%
434		400
435	---	401	----
436		402
437	~~#### `mime_type($path): string`~~	403	===== ##mime_type($path): string## =====
438	Returns MIME type for a file.	404	Returns MIME type for a file.
439		405
440	Returns:	406	Returns:
441	- MIME type string (e.g., 'application/pdf')	407	- MIME type string (e.g., 'application/pdf')
442	~~- Default: `'application/octet-stream'`~~	408	- Default: ##'application/octet-stream'##
443		409
444	Example:	410	Example:
445	~~```~~php	411	%%php
446	$mime = $http->mime_type('file.pdf'); // 'application/pdf'	412	$mime = $http->mime_type('file.pdf'); // 'application/pdf'
447	~~```~~	413	%%
448		414
449	---	415	----
450		416
451	~~#### `mime_types(): array` (Private)~~	417	===== ##mime_types(): array## (Private) =====
452	Loads and caches MIME types from configuration.	418	Loads and caches MIME types from configuration.
453		419
454	Features:	420	Features:
455	~~- Reads from `config/mime.types`~~	421	- Reads from ##config/mime.types##
456	~~- Caches to `cache/config/mime.types`~~	422	- Caches to ##cache/config/mime.types##
457	- Reloads if config is updated	423	- Reloads if config is updated
458		424
459	---	425	----
460		426
461	~~### Compression~~	427	==== Compression ====
462		428
463	~~#### `gzip(): void`~~	429	===== ##gzip(): void## =====
464	Compresses HTTP response with gzip/x-gzip.	430	Compresses HTTP response with gzip/x-gzip.
465		431
466	Features:	432	Features:
467	- Manually implements gzip (not relying on zlib.output_compression)	433	- Manually implements gzip (not relying on zlib.output_compression)
468	~~- Produces correct `Content-Length`~~ header	434	- Produces correct ##Content-Length## header
469	- Only compresses if:	435	- Only compresses if:
470	- 860 bytes < content < 1 MB	436	- 860 bytes < content < 1 MB
471	- Client accepts compression	437	- Client accepts compression
472	- Headers not already sent	438	- Headers not already sent
473		439
474	Example:	440	Example:
475	~~```~~php	441	%%php
476	$http->gzip();	442	$http->gzip();
477	~~```~~	443	%%
478		444
479	---	445	----
480		446
481	~~### Utility Methods~~	447	==== Utility Methods ====
482		448
483	~~#### `parse_str($str): array` (Private)~~	449	===== ##parse_str($str): array## (Private) =====
484	Parses URL-encoded strings with special character handling.	450	Parses URL-encoded strings with special character handling.
485		451
486	Purpose:	452	Purpose:
487	- Safely handles special characters in query/form data	453	- Safely handles special characters in query/form data
488	- Converts encoding properly	454	- Converts encoding properly
489		455
490	Example:	456	Example:
491	~~```~~php	457	%%php
492	$data = $http->parse_str('name=John&age=30');	458	$data = $http->parse_str('name=John&age=30');
493	~~```~~	459	%%
494		460
495	---	461	----
496		462
497	~~#### `request_uri(): string` (Private)~~	463	===== ##request_uri(): string## (Private) =====
498	Extracts and normalizes REQUEST_URI from server.	464	Extracts and normalizes REQUEST_URI from server.
499		465
500	Normalization:	466	Normalization:
501	- Removes base URL prefix	467	- Removes base URL prefix
502	- Removes spaces	468	- Removes spaces
503	- Collapses multiple slashes	469	- Collapses multiple slashes
504	~~- Removes `..`~~ path traversal attempts	470	- Removes ##..## path traversal attempts
505	- Removes leading/trailing slashes	471	- Removes leading/trailing slashes
506		472
507	---	473	----
508		474
509	~~#### `cut_prefix($prefix, $path): string` (Private)~~	475	===== ##cut_prefix($prefix, $path): string## (Private) =====
510	Removes prefix from path (case-insensitive).	476	Removes prefix from path (case-insensitive).
511		477
512	---	478	----
513		479
514	~~#### `get_header_conf($file_name): string` (Private)~~	480	===== ##get_header_conf($file_name): string## (Private) =====
515	Loads security header configuration from files.	481	Loads security header configuration from files.
516		482
517	Files Supported:	483	Files Supported:
518	- `csp.conf` / `csp_custom.conf`	484	- ##csp.conf## / ##csp_custom.conf##
519	- `permissions_policy.conf` / `permissions_policy_custom.conf`	485	- ##permissions_policy.conf## / ##permissions_policy_custom.conf##
520		486
521	---	487	----
522		488
523	## Configuration Dependencies	489	=== Configuration Dependencies ===
524		490
525	The class relies on these database configuration settings:	491
526		492
527	\| Setting \| Type \| Purpose \|	493	=== Constants Used ===
528	\|---------\|------\|---------\|	494
529	\| `base_url` \| string \| Wiki's base URL \|	495
530	\| `tls` \| bool \| Enable HTTPS enforcement \|	496
531	\| `cache` \| bool \| Enable page caching \|	497	=== Workflow Examples ===
532	\| `cache_ttl` \| int \| Cache lifetime in seconds \|	498
533	\| `session_store` \| int \| 1=File, 0=Database \|	499	==== Example 1: Handling a GET Request ====
534	\| `system_seed_hash` \| string \| Session encryption seed \|	500
535	\| `cookie_prefix` \| string \| Session cookie prefix \|	501	%%php
536	\| `cookie_path` \| string \| Cookie path \|
537	\| `allow_persistent_cookie` \| bool \| Allow persistent login \|
538	\| `session_length` \| int \| Session lifetime in seconds \|
539	\| `reverse_proxy_addresses` \| string \| Comma/space-separated proxy IPs \|
540	\| `reverse_proxy_header` \| string \| Custom X-Forwarded header \|
541	\| `language` \| string \| Default language code \|
542	\| `multilanguage` \| bool \| Enable language negotiation \|
543	\| `allowed_languages` \| string \| Comma/space-separated allowed langs \|
544	\| `enable_security_headers` \| bool \| Send security headers \|
545	\| `csp` \| int \| CSP setting (0/1/2) \|
546	\| `permissions_policy` \| int \| Permissions-Policy setting (0/1/2) \|
547	\| `referrer_policy` \| int \| Referrer-Policy setting (0-8) \|
548
549	---
550
551	## Constants Used
552
553	\| Constant \| Type \| Purpose \|
554	\|----------\|------\|---------\|
555	\| `IN_WACKO` \| bool \| Security check (exit if not defined) \|
556	\| `CHMOD_SAFE` \| int \| File permissions for cache files \|
557	\| `CHMOD_FILE` \| int \| File permissions for config cache \|
558	\| `CACHE_PAGE_DIR` \| string \| Page cache directory \|
559	\| `CACHE_SESSION_DIR` \| string \| Session cache directory \|
560	\| `CACHE_CONFIG_DIR` \| string \| Config cache directory \|
561	\| `CONFIG_DIR` \| string \| Configuration directory \|
562	\| `LANG_DIR` \| string \| Language files directory \|
563	\| `DAYSECS` \| int \| Seconds in a day (86400) \|
564	\| `HTTP_404` \| string \| Path to 404 error page \|
565	\| `HTTP_403` \| string \| Path to 403 error page \|
566
567	---
568
569	## Workflow Examples
570
571	### Example 1: Handling a GET Request
572
573	```php
574	// In main wiki entry point	502	// In main wiki entry point
575	$http = new Http($db);	503	$http = new Http($db);
576	$http->session(0); // Start session	504	$http->session(0); // Start session
…	…	…	…
588		516
589	// Possibly compress output	517	// Possibly compress output
590	$http->gzip();	518	$http->gzip();
591	~~```~~	519	%%
592		520
593	~~### Example 2: Handling TLS/HTTPS Upgrade~~	521	==== Example 2: Handling TLS/HTTPS Upgrade ====
594		522
595	~~```~~php	523	%%php
596	$http = new Http($db); // Constructor detects TLS requirement	524	$http = new Http($db); // Constructor detects TLS requirement
597	// If TLS is enabled and user wasn't in TLS before:	525	// If TLS is enabled and user wasn't in TLS before:
598	// - Sets TLS session flag	526	// - Sets TLS session flag
599	// - Marks session with TLS cookie	527	// - Marks session with TLS cookie
600	// - Redirects to HTTPS version	528	// - Redirects to HTTPS version
601	~~```~~	529	%%
602		530
603	~~### Example 3: Invalidating Cache After Page Edit~~	531	==== Example 3: Invalidating Cache After Page Edit ====
604		532
605	~~```~~php	533	%%php
606	// User edits a page	534	// User edits a page
607	$http = new Http($db);	535	$http = new Http($db);
608	$count = $http->invalidate_page('HomePage');	536	$count = $http->invalidate_page('HomePage');
609	// All cached versions (different languages, methods) are invalidated	537	// All cached versions (different languages, methods) are invalidated
610	~~```~~	538	%%
611		539
612	~~### Example 4: Serving a File~~	540	==== Example 4: Serving a File ====
613		541
614	~~```~~php	542	%%php
615	$http = new Http($db);	543	$http = new Http($db);
616	$http->session(2); // Static file mode - no session replay prevention	544	$http->session(2); // Static file mode - no session replay prevention
617		545
618	// Serve with 30-day cache	546	// Serve with 30-day cache
619	$http->sendfile('uploads/manual.pdf', 'user-manual.pdf', 30);	547	$http->sendfile('uploads/manual.pdf', 'user-manual.pdf', 30);
620	~~```~~	548	%%
621		549
622	---	550	----
623		551
624	~~## Security Considerations~~	552	=== Security Considerations ===
625		553
626	### 1. IP Address Spoofing	554	==== 1. IP Address Spoofing ====
627	- Validates IPs against private ranges	555	- Validates IPs against private ranges
628	- Filters proxy-provided IPs appropriately	556	- Filters proxy-provided IPs appropriately
629	- Configurable reverse proxy trust	557	- Configurable reverse proxy trust
630		558
631	### 2. Session Security	559	==== 2. Session Security ====
632	- Binds sessions to IP address	560	- Binds sessions to IP address
633	- Binds sessions to TLS status	561	- Binds sessions to TLS status
634	- Supports both file and database storage	562	- Supports both file and database storage
635	- HttpOnly cookies by default	563	- HttpOnly cookies by default
636		564
637	### 3. TLS Enforcement	565	==== 3. TLS Enforcement ====
638	- Automatic HTTPS upgrade when configured	566	- Automatic HTTPS upgrade when configured
639	- Marks TLS sessions to prevent downgrade attacks	567	- Marks TLS sessions to prevent downgrade attacks
640	- HSTS header support	568	- HSTS header support
641		569
642	### 4. Content Security	570	==== 4. Content Security ====
643	- CSP headers to prevent XSS	571	- CSP headers to prevent XSS
644	- X-Frame-Options to prevent clickjacking	572	- X-Frame-Options to prevent clickjacking
645	- X-Content-Type-Options to prevent MIME sniffing	573	- X-Content-Type-Options to prevent MIME sniffing
646	- Referrer-Policy control	574	- Referrer-Policy control
647	- Permissions-Policy for browser features	575	- Permissions-Policy for browser features
648		576
649	### 5. File Serving	577	==== 5. File Serving ====
650	- Validates file existence and readability	578	- Validates file existence and readability
651	~~- Prevents directory traversal via `realpath()`~~	579	- Prevents directory traversal via ##realpath()##
652	- Rejects symbolic links	580	- Rejects symbolic links
653	- Special CSP for SVG and PDF files	581	- Special CSP for SVG and PDF files
654		582
655	### 6. Cache Security	583	==== 6. Cache Security ====
656	- Cached only for anonymous users	584	- Cached only for anonymous users
657	- Disabled for sensitive operations (edit, watch)	585	- Disabled for sensitive operations (edit, watch)
658	- Only GET requests cached	586	- Only GET requests cached
659		587
660	---	588	----
661		589
662	~~## Performance Optimization~~	590	=== Performance Optimization ===
663		591
664	### 1. Page Caching	592	==== 1. Page Caching ====
665	- Stores full HTML output	593	- Stores full HTML output
666	- TTL-based expiration	594	- TTL-based expiration
667	- Language and method-aware caching	595	- Language and method-aware caching
668	- Conditional request support (304 Not Modified)	596	- Conditional request support (304 Not Modified)
669		597
670	### 2. MIME Type Caching	598	==== 2. MIME Type Caching ====
671	- Loads MIME types once and caches	599	- Loads MIME types once and caches
672	- Regenerates only when config changes	600	- Regenerates only when config changes
673		601
674	### 3. Session Options	602	==== 3. Session Options ====
675	- File-based sessions for simple deployments	603	- File-based sessions for simple deployments
676	- Database sessions for distributed systems	604	- Database sessions for distributed systems
677		605
678	### 4. Compression	606	==== 4. Compression ====
679	- Manual gzip implementation	607	- Manual gzip implementation
680	- Proper Content-Length generation	608	- Proper Content-Length generation
681	- Only compresses appropriate sizes	609	- Only compresses appropriate sizes
682		610
683	---	611	----
684		612
685	~~## Debugging~~	613	=== Debugging ===
686		614
687	The class integrates with WackoWiki's diagnostic system:	615	The class integrates with WackoWiki's diagnostic system:
688		616
689	~~```~~php	617	%%php
690	// Diagnostic messages are preserved across redirects	618	// Diagnostic messages are preserved across redirects
691	// via session flash data	619	// via session flash data
692		620
693	// Check cached pages (debug comments in output):	621	// Check cached pages (debug comments in output):
694	// <!-- WackoWiki Caching Engine: page cached at 2024-01-15 12:30:45 GMT -->	622	// <!-- WackoWiki Caching Engine: page cached at 2024-01-15 12:30:45 GMT -->
695	```	623	%%
696		624
697	---	625	----
698		626
699	## Related Classes	627	=== Related Classes ===
700		628	- Session Classes (##SessionFileStore##, ##SessionDbalStore##) - Session management backends
701	- Session Classes (`SessionFileStore`, `SessionDbalStore`) - Session management backends	629	- Database Class - Configuration and cache metadata storage
702	- Database Class - Configuration and cache metadata storage	630	- Ut Utility Class - String/path utilities
703	- Ut Utility Class - String/path utilities	631	- Diag Class - Diagnostic logging
704	- Diag Class - Diagnostic logging	632
705		633	----
706	---	634
707		635	=== Version History ===
708	## Version History	636	- Supports PHP 8.0+ (uses match expressions, union types)
709		637	- Follows RFC 9110 for HTTP header handling
710	- Supports PHP 8.0+ (uses match expressions, union types)	638	- Modern cookie security practices
711	- Follows RFC 9110 for HTTP header handling	639
712	- Modern cookie security practices	640	----
713		641
714	---	642	=== Conclusion ===
715		643
716	## Conclusion	644	The ##Http## class is the central request/response handler in WackoWiki, managing everything from session initialization to security headers to file serving. Understanding this class is essential for:
717		645	- Extending WackoWiki with custom request handlers
718	The `Http` class is the central request/response handler in WackoWiki, managing everything from session initialization to security headers to file serving. Understanding this class is essential for:	646	- Implementing custom session logic
719		647	- Adding new security policies
720	- Extending WackoWiki with custom request handlers	648	- Optimizing cache strategies
721	- Implementing custom session logic	649	- Debugging HTTP-related issues
722	- Adding new security policies
723	- Optimizing cache strategies
724	- Debugging HTTP-related issues