Difference between revisions for Users / Eo Ny / dev




← Previous edit
Revision 2 as of 05/05/2026 19:08 ▼
3 05/05/2026 19:10 EoNy 2 05/05/2026 19:08 EoNy 1 05/05/2026 19:06 EoNy

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

(19.7 KiB) +15,742
EoNy

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