Difference between revisions for Users / Eo Ny / dev




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

(4.4 KiB)
EoNy
 Next edit →
Revision 7 as of 05/05/2026 19:23 ▼
18 05/21/2026 16:12 WikiAdmin 17 05/18/2026 15:15 WikiAdmin 16 05/18/2026 05:05 WikiAdmin 15 05/18/2026 05:04 WikiAdmin 14 05/17/2026 21:10 WikiAdmin 13 05/05/2026 19:29 EoNy 12 05/05/2026 19:28 WikiAdmin 11 05/05/2026 19:28 WikiAdmin 10 05/05/2026 19:27 WikiAdmin 9 05/05/2026 19:25 WikiAdmin 8 05/05/2026 19:24 WikiAdmin 7 05/05/2026 19:23 WikiAdmin 6 05/05/2026 19:21 EoNy 5 05/05/2026 19:11 EoNy 4 05/05/2026 19:10 EoNy 3 05/05/2026 19:10 EoNy

(14.8 KiB) +10,678
WikiAdmin

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