Difference between revisions for Users / Eo Ny / dev




← Previous edit
Revision 5 as of 05/05/2026 19:11 ▼
16 05/18/2026 05:05 WikiAdmin 15 05/18/2026 05:04 WikiAdmin 14 05/17/2026 21:10 WikiAdmin 13 05/05/2026 19:29 EoNy 12 05/05/2026 19:28 WikiAdmin 11 05/05/2026 19:28 WikiAdmin 10 05/05/2026 19:27 WikiAdmin 9 05/05/2026 19:25 WikiAdmin 8 05/05/2026 19:24 WikiAdmin 7 05/05/2026 19:23 WikiAdmin 6 05/05/2026 19:21 EoNy 5 05/05/2026 19:11 EoNy 4 05/05/2026 19:10 EoNy 3 05/05/2026 19:10 EoNy 2 05/05/2026 19:08 EoNy 1 05/05/2026 19:06 EoNy

(17.4 KiB)
EoNy
 Next edit →
Revision 17 as of 05/18/2026 15:15 ▼
18 05/21/2026 16:12 WikiAdmin 17 05/18/2026 15:15 WikiAdmin 16 05/18/2026 05:05 WikiAdmin 15 05/18/2026 05:04 WikiAdmin 14 05/17/2026 21:10 WikiAdmin 13 05/05/2026 19:29 EoNy 12 05/05/2026 19:28 WikiAdmin 11 05/05/2026 19:28 WikiAdmin 10 05/05/2026 19:27 WikiAdmin 9 05/05/2026 19:25 WikiAdmin 8 05/05/2026 19:24 WikiAdmin 7 05/05/2026 19:23 WikiAdmin 6 05/05/2026 19:21 EoNy

(18.4 KiB) +1,018
WikiAdmin

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