Difference between revisions for Users / Eo Ny / dev




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

(14.8 KiB) +11,713
WikiAdmin

Version1 Version2
10 10
11 ---- 11 ----
12 12
13 13 === Class Properties ===
14 14
15 15 ==== Public Properties ====
16 16
17 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 ----
18 544
19 === Security Considerations === 545 === Security Considerations ===
20 546