Difference between revisions for Users / Eo Ny / dev




← Previous edit
Revision 4 as of 05/05/2026 19:10 ▼
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

(19.7 KiB)
EoNy
 Next edit →
Revision 10 as of 05/05/2026 19:27 ▼
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

(16.4 KiB) -3,400
WikiAdmin

Merge of Version1 & Version2
12
13 === Class Properties ===
14
15 ==== Public Properties Public Properties====
16
17 #|
18 *| Property | Type | Description |*
… …
21 || ##$ip## | string | Client's real IP address (accounts for proxies) ||
22 || ##$sess## | Session | Reference to the Session object ||
23 || ##$method## | string | Current HTTP method/request type ||
24 |#
25
26 ====Private Properties====
27
28 #|
29 *| Property | Type | Description |*
30 || ##$db## | object | Database connection reference ||
31 || ##$tls_mark## | string | Cookie name for TLS session marking ||
32 || ##$page## | string | Current page name being processed ||
… …
35 || ##$lang## | string | Current language code ||
36 || ##$file## | string | Cache file path ||
37 || ##$caching## | int | Flag indicating if page should be cached (0 or 1) ||
38 |#
39
40 ----
41 === Constructor ===
42
43 %%php
44 public function __construct(&$db)
45 %%
46
47 **Purpose:** Initializes the Http object and sets up HTTP session handling.
48
49 **Parameters:**
50   - ##$db## - Database object reference
51
52 **Initialization Steps:**
53   1. Stores database reference
54   2. Extracts and normalizes REQUEST_URI
55   3. Detects TLS/HTTPS session status
56   4. Determines client's real IP address
57   5. Sets up TLS mark cookie name
58   6. Enforces TLS session upgrade if needed
59
60 **Example:**
61 %%php
62 $http = new Http($db);
63 %%
64
65 ----
66
67 === Core Methods ===
68
69 ==== Session Management ====
70
71 ===== ##session($route): void## =====
72 Initializes the session handler (file-based or database-based).
73
74 **Parameters:**
75   - ##$route## (int) - Routing flag:
76   - Bit 2 (##$route & 2##): Enable static mode for files/freecap (disables replay prevention and ID regeneration)
77
78 **Features:**
79   - Selects storage backend (file or database)
80   - Configures cookie settings (security, path, httponly)
81   - Binds IP and TLS validation
82   - Recovers diagnostic logs from previous session
83
84 **Example:**
85 %%php
86 $http->session(0); // Normal session
87 $http->session(2); // Static file serving mode
88 %%
89
90 ----
91
92 ==== Caching System ====
93
94 ===== ##check_cache($page, $method): void## =====
95 Determines if a page can be cached and prepares the cache check.
96
97 **Parameters:**
98   - ##$page## (string) - Page name to cache
99   - ##$method## (string) - Request method/action (e.g., 'show', 'edit')
100
101 **Caching Rules:**
102   - ✅ Enabled for GET requests only
103   - ✅ Disabled for POST requests
104   - ❌ Never cached for 'edit' or 'watch' methods
105   - ✅ Only cached for anonymous users (no logged-in users)
106
107 **Example:**
108 %%php
109 $http->check_cache('HomePage', 'show');
110 %%
111
112 ----
113
114 ===== ##store_cache(): void## =====
115 Saves the generated page content to cache file.
116
117 **Features:**
118   - Retrieves output buffer content
119   - Saves to cache file with proper permissions
120   - Records cache metadata in database
121   - Only executes if caching flag is set and user is anonymous
122
123 **Example:**
124 %%php
125 // Called at end of page rendering
126 $http->store_cache();
127 %%
128
129 ----
130
131 ===== ##invalidate_page($page): int## =====
132 Invalidates all cached versions of a page.
133
134 **Parameters:**
135   - ##$page## (string) - Page name to invalidate
136
137 **Returns:**
138   - Number of cache entries invalidated
139
140 **Process:**
141   1. Finds all cached versions (different methods/languages)
142   2. Touches files to past timestamp (faster than deletion)
143   3. Removes entries from cache metadata table
144   4. Returns count of invalidated caches
145
146 **Example:**
147 %%php
148 $count = $http->invalidate_page('HomePage');
149 echo "Invalidated $count cache entries";
150 %%
151
152 ----
153
154 ==== TLS/HTTPS Security ====
155
156 ===== ##secure_base_url(): void## =====
157 Switches base URL from HTTP to HTTPS.
158
159 **Purpose:**
160   - Ensures all subsequent URLs use HTTPS
161   - Stores original HTTP URL for fallback
162   - Called when TLS session is detected
163
164 **Example:**
165 %%php
166 $http->secure_base_url();
167 // $db->base_url now uses https://
168 %%
169
170 ----
171
172 ===== ##ensure_tls($url): void## =====
173 Enforces HTTPS for a specific URL and redirects if necessary.
174
175 **Parameters:**
176   - ##$url## (string) - URL to secure
177
178 **Behavior:**
179   - If not already HTTPS and TLS is enabled, forces HTTPS redirect
180   - Handles both relative and absolute URLs
181   - Converts relative URLs using current server name
182
183 **Example:**
184 %%php
185 $http->ensure_tls('/secure/payment');
186 %%
187
188 ----
189
190 ==== IP Address Detection ====
191
192 ===== ##real_ip(): string## (Private) =====
193 Detects client's real IP address accounting for proxies.
194
195 **Proxy Headers Checked (in order):**
196   1. ##HTTP_X_CLUSTER_CLIENT_IP##
197   2. ##HTTP_X_FORWARDED_FOR## (or custom header)
198   3. ##HTTP_CLIENT_IP##
199   4. ##HTTP_X_REMOTE_ADDR##
200   5. ##REMOTE_ADDR## (fallback)
201
202 **Features:**
203   - Filters out private/reserved IP ranges
204   - Respects configured reverse proxy addresses
205   - Returns ##'0.0.0.0'## as fallback
206
207 **Configuration in Database:**
208   - ##reverse_proxy_addresses## - Comma/space-separated proxy IPs
209   - ##reverse_proxy_header## - Custom header name (default: ##X-Forwarded-For##)
210
211 **Example:**
212 %%php
213 $client_ip = $http->ip; // e.g., "203.0.113.42"
214 %%
215
216 ----
217
218 ==== HTTPS Detection ====
219
220 ===== ##tls_session(): bool## (Private) =====
221 Detects if current connection uses HTTPS/TLS.
222
223 **Checks (any being true = HTTPS):**
224   - ##$_SERVER['HTTPS']## is 'on'
225   - ##$_SERVER['SERVER_PORT']## is 443
226   - ##$_SERVER['HTTP_X_FORWARDED_PROTO']## is 'https'
227   - ##$_SERVER['HTTP_X_FORWARDED_SSL']## is 'on'
228   - ##$_SERVER['HTTP_X_FORWARDED_PORT']## is 443
229
230 ----
231
232 ==== Security Headers ====
233
234 =====##http_security_headers(): void##=====
235
236 Sets security-related HTTP headers.
237
238 **Headers Set:**
239
240 #|
241 *| Header | Purpose | Config Key |*
242 || Content-Security-Policy | XSS/injection protection | ##csp## ||
243 || Permissions-Policy | Control browser features | ##permissions_policy## ||
244 || Referrer-Policy | Control referrer information | ##referrer_policy## ||
245 || Strict-Transport-Security | Force HTTPS | Auto (TLS only) ||
246 || X-Frame-Options | Clickjacking protection | Hardcoded: ##SAMEORIGIN## ||
247 || X-Content-Type-Options | MIME sniffing prevention | Hardcoded: ##nosniff## ||
248 |#
249
250 **CSP Configuration Options:**
251   - ##0## - Disabled
252   - ##1## - Default policy (from ##csp.conf##)
253   - ##2## - Custom policy (from ##csp_custom.conf##)
254
255 **Example:**
256 %%php
257 $http->http_security_headers();
258 %%
259
260 ----
261 ==== HTTP Methods ====
262
263 ===== ##redirect($url, $permanent = false): void## =====
264 Performs an HTTP redirect.
265
266 **Parameters:**
267   - ##$url## (string) - Target URL
268   - ##$permanent## (bool) - Use 301 (permanent) vs 302 (temporary)
269
270 **Features:**
271   - Decodes ##&## entities to prevent broken redirects
272   - Only works if headers not yet sent
273   - Uses output buffering to work anywhere in page processing
274
275 **Example:**
276 %%php
277 $http->redirect('http://example.com/new-page', true); // 301
278 $http->redirect('/wiki/HomePage'); // 302
279 %%
280
281 ----
282
283 ===== ##terminate(): void## =====
284 Safe exit/die with cleanup.
285
286 **Cleanup Operations:**
287   - Saves diagnostic logs to session flash data
288   - Ends script execution
289
290 **Example:**
291 %%php
292 $http->terminate();
293 %%
294
295 ----
296
297 ===== ##status($code): void## =====
298 Sets HTTP response status code.
299
300 **Supported Status Codes:**
301 %%php
302 200 => 'OK'
303 206 => 'Partial Content'
304 301 => 'Moved Permanently'
… …
315 500 => 'Internal Server Error'
316 501 => 'Not Implemented'
317 503 => 'Service Unavailable'
318 %%
319
320 **Example:**
321 %%php
322 $http->status(404); // Send 404 Not Found
323 %%
324
325 ----
326
327 ==== Caching Control ====
328
329 ===== ##no_cache($client_only = true): void## =====
330 Disables caching of the current page.
331
332 **Parameters:**
333   - ##$client_only## (bool, default: TRUE)
334   - ##TRUE##: Disable browser cache only
335   - ##FALSE##: Disable both browser and server cache
336
337 **Headers Set:**
338   - ##Last-Modified: <current-time>## (always fresh)
339   - ##Cache-Control: no-store##
340
341 **Example:**
342 %%php
343 $http->no_cache(); // Client-side only
344 $http->no_cache(false); // Both client & server
345 %%
346
347 ----
348
349 ===== ##cache_promisc(): void## =====
350 Marks page as publicly cacheable.
351
352 **Headers Set:**
353   - ##Cache-Control: public##
354
355 **Example:**
356 %%php
357 $http->cache_promisc();
358 %%
359
360 ----
361
362 ==== Language Negotiation ====
363
364 ===== ##user_agent_language(): string## =====
365 Determines best language based on browser preferences.
366
367 **Features:**
368   - Follows RFC 9110 section 12.5.4 (HTTP Accept-Language)
369   - Parses ##Accept-Language## header with quality factors
370   - Attempts exact match first, then language fallback
371   - Falls back to default system language
372
373 **Example Header:**
374 %%
375 Accept-Language: en-US,en;q=0.9,de;q=0.8
376 %%
377
378 **Returns:**
379   - Language code (e.g., 'en', 'en-US', 'de')
380
381 ----
382
383 ===== ##available_languages($subset = true): array## =====
384 Returns list of available language translations.
385
386 **Parameters:**
387   - ##$subset## (bool, default: TRUE)
388   - ##TRUE##: Only allowed languages
389   - ##FALSE##: All available languages
390
391 **Features:**
392   - Scans ##LANG_DIR## for language files
393   - Filters by ##allowed_languages## config if set
394   - Caches result in session
395   - System language always included
396
397 **Returns:**
398   - Associative array: ##['en' => 'en', 'de' => 'de', ...]##
399
400 **Example:**
401 %%php
402 $all_langs = $http->available_languages(false);
403 $allowed = $http->available_languages(true);
404 %%
405
406 ----
407
408 ==== File Serving ====
409
410 ===== ##sendfile($path, $filename = null, $age = null): void## =====
411 Serves files with proper HTTP headers and caching.
412
413 **Parameters:**
414   - ##$path## (string) - File path (or HTTP_XXX constant for error pages)
415   - ##$filename## (string, optional) - Custom download filename
416   - ##$age## (int, optional) - Cache age in days
417
418 **Features:**
419   - HTTP range request support (partial file downloads)
420   - ETag and Last-Modified conditional requests
421   - Proper MIME type detection
422   - Content-Security-Policy for special file types
423   - Streaming for large files
424   - GZip compression for text files
425
426 **Special Paths:**
427 %%php
428 $http->sendfile(404); // Serves file defined by HTTP_404 constant
429 $http->sendfile(403); // Serves file defined by HTTP_403 constant
430 %%
431
432 **Example:**
433 %%php
434 $http->sendfile('uploads/document.pdf', 'my-document.pdf', 30);
435 %%
436
437 ----
438
439 ===== ##mime_type($path): string## =====
440 Returns MIME type for a file.
441
442 **Returns:**
443   - MIME type string (e.g., 'application/pdf')
444   - Default: ##'application/octet-stream'##
445
446 **Example:**
447 %%php
448 $mime = $http->mime_type('file.pdf'); // 'application/pdf'
449 %%
450
451 ----
452
453 ===== ##mime_types(): array## (Private) =====
454 Loads and caches MIME types from configuration.
455
456 **Features:**
457   - Reads from ##config/mime.types##
458   - Caches to ##cache/config/mime.types##
459   - Reloads if config is updated
460
461 ----
462
463 ==== Compression ====
464
465 ===== ##gzip(): void## =====
466 Compresses HTTP response with gzip/x-gzip.
467
468 **Features:**
469   - Manually implements gzip (not relying on zlib.output_compression)
470   - Produces correct ##Content-Length## header
471   - Only compresses if:
472   - 860 bytes < content < 1 MB
473   - Client accepts compression
474   - Headers not already sent
475
476 **Example:**
477 %%php
478 $http->gzip();
479 %%
480
481 ----
482
483 ==== Utility Methods ====
484
485 ===== ##parse_str($str): array## (Private) =====
486 Parses URL-encoded strings with special character handling.
487
488 **Purpose:**
489   - Safely handles special characters in query/form data
490   - Converts encoding properly
491
492 **Example:**
493 %%php
494 $data = $http->parse_str('name=John&age=30');
495 %%
496
497 ----
498
499 ===== ##request_uri(): string## (Private) =====
500 Extracts and normalizes REQUEST_URI from server.
501
502 **Normalization:**
503   - Removes base URL prefix
504   - Removes spaces
505   - Collapses multiple slashes
506   - Removes ##..## path traversal attempts
507   - Removes leading/trailing slashes
508
509 ----
510
511 ===== ##cut_prefix($prefix, $path): string## (Private) =====
512 Removes prefix from path (case-insensitive).
513
514 ----
515
516 ===== ##get_header_conf($file_name): string## (Private) =====
517 Loads security header configuration from files.
518
519 **Files Supported:**
520   - ##csp.conf## / ##csp_custom.conf##
521   - ##permissions_policy.conf## / ##permissions_policy_custom.conf##
522
523 ----
524
525 === Configuration Dependencies ===
526
527
528
529 === Constants Used ===
530
531
532
533 === Workflow Examples ===
534