Difference between revisions for Users / Eo Ny / dev




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

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

(18.4 KiB) -1,359
WikiAdmin

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