Difference between revisions for Users / Eo Ny / dev




← Previous edit
Revision 3 as of 05/05/2026 19:10 ▼
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 14 as of 05/17/2026 21:10 ▼
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 5 05/05/2026 19:11 EoNy 4 05/05/2026 19:10 EoNy

(18.3 KiB) +931
WikiAdmin

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