Difference between revisions for Users / Eo Ny / dev




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

(17.4 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   #|
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
  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
38 43 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
  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
52 61 $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
  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
69 85 $http->session(0); // Normal session
70 86 $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
  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
86 108 $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
  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
98 124 // Called at end of page rendering
99 125 $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
  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
115 147 $count = $http->invalidate_page('HomePage');
116 148 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
  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
128 165 $http->secure_base_url();
129 166 // $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
  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
142 184 $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
  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
163 212 $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
  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
194 254 $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
  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
209 275 $http->redirect('http://example.com/new-page', true); // 301
210 276 $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
  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
220 290 $http->terminate();
221   %% ||
222   || ---- ||
223   || ===== ##status($code): void## ===== ||
224   || Sets HTTP response status code. ||
225   || **Supported Status Codes:** ||
226   || %%php
  291 ```
  292
  293 ---
  294
  295 #### `status($code): void`
  296 Sets HTTP response status code.
  297
  298 **Supported Status Codes:**
  299 ```php
227 300 200 => 'OK'
228 301 206 => 'Partial Content'
229 302 301 => 'Moved Permanently'
… … …
240 313 500 => 'Internal Server Error'
241 314 501 => 'Not Implemented'
242 315 503 => 'Service Unavailable'
243   %% ||
244   || **Example:** ||
245   || %%php
  316 ```
  317
  318 **Example:**
  319 ```php
246 320 $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
  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
261 341 $http->no_cache(); // Client-side only
262 342 $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
  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
271 355 $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   || %%
  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 ```
284 373 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
  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
304 400 $all_langs = $http->available_languages(false);
305 401 $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
  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
324 426 $http->sendfile(404); // Serves file defined by HTTP_404 constant
325 427 $http->sendfile(403); // Serves file defined by HTTP_403 constant
326   %% ||
327   || **Example:** ||
328   || %%php
  428 ```
  429
  430 **Example:**
  431 ```php
329 432 $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
  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
339 446 $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
  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
361 476 $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
  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
372 492 $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
  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
440 574 // In main wiki entry point
441 575 $http = new Http($db);
442 576 $http->session(0); // Start session
… … …
454 588
455 589 // Possibly compress output
456 590 $http->gzip();
457   %%
458  
459   ==== Example 2: Handling TLS/HTTPS Upgrade ====
460  
461   %%php
  591 ```
  592
  593 ### Example 2: Handling TLS/HTTPS Upgrade
  594
  595 ```php
462 596 $http = new Http($db); // Constructor detects TLS requirement
463 597 // If TLS is enabled and user wasn't in TLS before:
464 598 // - Sets TLS session flag
465 599 // - Marks session with TLS cookie
466 600 // - Redirects to HTTPS version
467   %%
468  
469   ==== Example 3: Invalidating Cache After Page Edit ====
470  
471   %%php
  601 ```
  602
  603 ### Example 3: Invalidating Cache After Page Edit
  604
  605 ```php
472 606 // User edits a page
473 607 $http = new Http($db);
474 608 $count = $http->invalidate_page('HomePage');
475 609 // All cached versions (different languages, methods) are invalidated
476   %%
477  
478   ==== Example 4: Serving a File ====
479  
480   %%php
  610 ```
  611
  612 ### Example 4: Serving a File
  613
  614 ```php
481 615 $http = new Http($db);
482 616 $http->session(2); // Static file mode - no session replay prevention
483 617
484 618 // Serve with 30-day cache
485 619 $http->sendfile('uploads/manual.pdf', 'user-manual.pdf', 30);
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 ===
  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
552 686
553 687 The class integrates with WackoWiki's diagnostic system:
554 688
555   %%php
  689 ```php
556 690 // Diagnostic messages are preserved across redirects
557 691 // via session flash data
558 692
559 693 // Check cached pages (debug comments in output):
560 694 // <!-- WackoWiki Caching Engine: page cached at 2024-01-15 12:30:45 GMT -->
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
  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