Difference between revisions for Users / Eo Ny / dev




← Previous edit
Revision 6 as of 05/05/2026 19:21 ▼
7 05/05/2026 19:23 WikiAdmin 6 05/05/2026 19:21 EoNy 5 05/05/2026 19:11 EoNy 4 05/05/2026 19:10 EoNy 3 05/05/2026 19:10 EoNy 2 05/05/2026 19:08 EoNy 1 05/05/2026 19:06 EoNy

(3.4 KiB)
EoNy
 Next edit →
Revision 8 as of 05/05/2026 19:24 ▼
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

(15.2 KiB) +12,129
WikiAdmin

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