Difference between revisions for Users / Eo Ny / dev




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

(19.7 KiB) +2,418
EoNy

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