SQLite Testing

|| ---- ||
|| === Constructor === ||
|| %%php
public function __construct(&$db)
%% ||
|| **Purpose:** Initializes the Http object and sets up HTTP session
handling. ||
|| **Parameters:** ||
|| - ##$db## - Database object reference ||
|| **Initialization Steps:** ||
|| 1. Stores database reference ||
|| 2. Extracts and normalizes REQUEST_URI ||
|| 3. Detects TLS/HTTPS session status ||
|| 4. Determines client's real IP address ||
|| 5. Sets up TLS mark cookie name ||
|| 6. Enforces TLS session upgrade if needed ||
|| **Example:** ||
|| %%php
$http = new Http($db);
%% ||
|| ---- ||
|| === Core Methods === ||
|| ==== Session Management ==== ||
|| ===== ##session($route): void## ===== ||
|| Initializes the session handler (file-based or database-based). ||
|| **Parameters:** ||
|| - ##$route## (int) - Routing flag: ||
|| - Bit 2 (##$route & 2##): Enable static mode for files/freecap
(disables replay prevention and ID regeneration) ||
|| **Features:** ||
|| - Selects storage backend (file or database) ||
|| - Configures cookie settings (security, path, httponly) ||
|| - Binds IP and TLS validation ||
|| - Recovers diagnostic logs from previous session ||
|| **Example:** ||
|| %%php
$http->session(0);  // Normal session
$http->session(2);  // Static file serving mode
%% ||
|| ---- ||
|| ==== Caching System ==== ||
|| ===== ##check_cache($page, $method): void## ===== ||
|| Determines if a page can be cached and prepares the cache check. ||
|| **Parameters:** ||
|| - ##$page## (string) - Page name to cache ||
|| - ##$method## (string) - Request method/action (e.g.,
'show', 'edit') ||
|| **Caching Rules:** ||
|| - ✅ Enabled for GET requests only ||
|| - ✅ Disabled for POST requests ||
|| - ❌ Never cached for 'edit' or 'watch' methods
||
|| - ✅ Only cached for anonymous users (no logged-in users) ||
|| **Example:** ||
|| %%php
$http->check_cache('HomePage', 'show');
%% ||
|| ---- ||
|| ===== ##store_cache(): void## ===== ||
|| Saves the generated page content to cache file. ||
|| **Features:** ||
|| - Retrieves output buffer content ||
|| - Saves to cache file with proper permissions ||
|| - Records cache metadata in database ||
|| - Only executes if caching flag is set and user is anonymous ||
|| **Example:** ||
|| %%php
// Called at end of page rendering
$http->store_cache();
%% ||
|| ---- ||
|| ===== ##invalidate_page($page): int## ===== ||
|| Invalidates all cached versions of a page. ||
|| **Parameters:** ||
|| - ##$page## (string) - Page name to invalidate ||
|| **Returns:** ||
|| - Number of cache entries invalidated ||
|| **Process:** ||
|| 1. Finds all cached versions (different methods/languages) ||
|| 2. Touches files to past timestamp (faster than deletion) ||
|| 3. Removes entries from cache metadata table ||
|| 4. Returns count of invalidated caches ||
|| **Example:** ||
|| %%php
$count = $http->invalidate_page('HomePage');
echo "Invalidated $count cache entries";
%% ||
|| ---- ||
|| ==== TLS/HTTPS Security ==== ||
|| ===== ##secure_base_url(): void## ===== ||
|| Switches base URL from HTTP to HTTPS. ||
|| **Purpose:** ||
|| - Ensures all subsequent URLs use HTTPS ||
|| - Stores original HTTP URL for fallback ||
|| - Called when TLS session is detected ||
|| **Example:** ||
|| %%php
$http->secure_base_url();
// $db->base_url now uses https://
%% ||
|| ---- ||
|| ===== ##ensure_tls($url): void## ===== ||
|| Enforces HTTPS for a specific URL and redirects if necessary. ||
|| **Parameters:** ||
|| - ##$url## (string) - URL to secure ||
|| **Behavior:** ||
|| - If not already HTTPS and TLS is enabled, forces HTTPS redirect ||
|| - Handles both relative and absolute URLs ||
|| - Converts relative URLs using current server name ||
|| **Example:** ||
|| %%php
$http->ensure_tls('/secure/payment');
%% ||
|| ---- ||
|| ==== IP Address Detection ==== ||
|| ===== ##real_ip(): string## (Private) ===== ||
|| Detects client's real IP address accounting for proxies. ||
|| **Proxy Headers Checked (in order):** ||
|| 1. ##HTTP_X_CLUSTER_CLIENT_IP## ||
|| 2. ##HTTP_X_FORWARDED_FOR## (or custom header) ||
|| 3. ##HTTP_CLIENT_IP## ||
|| 4. ##HTTP_X_REMOTE_ADDR## ||
|| 5. ##REMOTE_ADDR## (fallback) ||
|| **Features:** ||
|| - Filters out private/reserved IP ranges ||
|| - Respects configured reverse proxy addresses ||
|| - Returns ##'0.0.0.0'## as fallback ||
|| **Configuration in Database:** ||
|| - ##reverse_proxy_addresses## - Comma/space-separated proxy IPs ||
|| - ##reverse_proxy_header## - Custom header name (default:
##X-Forwarded-For##) ||
|| **Example:** ||
|| %%php
$client_ip = $http->ip;  // e.g., "203.0.113.42"
%% ||
|| ---- ||
|| ==== HTTPS Detection ==== ||
|| ===== ##tls_session(): bool## (Private) ===== ||
|| Detects if current connection uses HTTPS/TLS. ||
|| **Checks (any being true = HTTPS):** ||
|| - ##$_SERVER['HTTPS']## is 'on' ||
|| - ##$_SERVER['SERVER_PORT']## is 443 ||
|| - ##$_SERVER['HTTP_X_FORWARDED_PROTO']## is
'https' ||
|| - ##$_SERVER['HTTP_X_FORWARDED_SSL']## is 'on'
||
|| - ##$_SERVER['HTTP_X_FORWARDED_PORT']## is 443 ||
|| ---- ||
|| ==== Security Headers ==== ||
|| ===== ##http_security_headers(): void## ===== ||
|| Sets security-related HTTP headers. ||
|| **Headers Set:** ||
|| Header | Purpose | Config Key ||
|| -------- | --------- | ------------ ||
|| Content-Security-Policy | XSS/injection protection | ##csp## ||
|| Permissions-Policy | Control browser features |
##permissions_policy## ||
|| Referrer-Policy | Control referrer information |
##referrer_policy## ||
|| Strict-Transport-Security | Force HTTPS | Auto (TLS only) ||
|| X-Frame-Options | Clickjacking protection | Hardcoded:
##SAMEORIGIN## ||
|| X-Content-Type-Options | MIME sniffing prevention | Hardcoded:
##nosniff## ||
|| **CSP Configuration Options:** ||
|| - ##0## - Disabled ||
|| - ##1## - Default policy (from ##csp.conf##) ||
|| - ##2## - Custom policy (from ##csp_custom.conf##) ||
|| **Example:** ||
|| %%php
$http->http_security_headers();
%% ||
|| ---- ||
|| ==== HTTP Methods ==== ||
|| ===== ##redirect($url, $permanent = false): void## ===== ||
|| Performs an HTTP redirect. ||
|| **Parameters:** ||
|| - ##$url## (string) - Target URL ||
|| - ##$permanent## (bool) - Use 301 (permanent) vs 302 (temporary) ||
|| **Features:** ||
|| - Decodes ##&## entities to prevent broken redirects ||
|| - Only works if headers not yet sent ||
|| - Uses output buffering to work anywhere in page processing ||
|| **Example:** ||
|| %%php
$http->redirect('http://example.com/new-page', true);  //
301
$http->redirect('/wiki/HomePage');                      
// 302
%% ||
|| ---- ||
|| ===== ##terminate(): void## ===== ||
|| Safe exit/die with cleanup. ||
|| **Cleanup Operations:** ||
|| - Saves diagnostic logs to session flash data ||
|| - Ends script execution ||
|| **Example:** ||
|| %%php
$http->terminate();
%% ||
|| ---- ||
|| ===== ##status($code): void## ===== ||
|| Sets HTTP response status code. ||
|| **Supported Status Codes:** ||
|| %%php
200 => 'OK'
206 => 'Partial Content'
301 => 'Moved Permanently'
302 => 'Moved Temporarily'
304 => 'Not Modified'
400 => 'Bad Request'
401 => 'Unauthorized'
403 => 'Forbidden'
404 => 'Not Found'
405 => 'Method Not Allowed'
409 => 'Conflict'
410 => 'Gone'
416 => 'Requested Range Not Satisfiable'
500 => 'Internal Server Error'
501 => 'Not Implemented'
503 => 'Service Unavailable'
%% ||
|| **Example:** ||
|| %%php
$http->status(404);  // Send 404 Not Found
%% ||
|| ---- ||
|| ==== Caching Control ==== ||
|| ===== ##no_cache($client_only = true): void## ===== ||
|| Disables caching of the current page. ||
|| **Parameters:** ||
|| - ##$client_only## (bool, default: TRUE) ||
|| - ##TRUE##: Disable browser cache only ||
|| - ##FALSE##: Disable both browser and server cache ||
|| **Headers Set:** ||
|| - ##Last-Modified: <current-time>## (always fresh) ||
|| - ##Cache-Control: no-store## ||
|| **Example:** ||
|| %%php
$http->no_cache();        // Client-side only
$http->no_cache(false);   // Both client & server
%% ||
|| ---- ||
|| ===== ##cache_promisc(): void## ===== ||
|| Marks page as publicly cacheable. ||
|| **Headers Set:** ||
|| - ##Cache-Control: public## ||
|| **Example:** ||
|| %%php
$http->cache_promisc();
%% ||
|| ---- ||
|| ==== Language Negotiation ==== ||
|| ===== ##user_agent_language(): string## ===== ||
|| Determines best language based on browser preferences. ||
|| **Features:** ||
|| - Follows RFC 9110 section 12.5.4 (HTTP Accept-Language) ||
|| - Parses ##Accept-Language## header with quality factors ||
|| - Attempts exact match first, then language fallback ||
|| - Falls back to default system language ||
|| **Example Header:** ||
|| %%
Accept-Language: en-US,en;q=0.9,de;q=0.8
%% ||
|| **Returns:** ||
|| - Language code (e.g., 'en', 'en-US',
'de') ||
|| ---- ||
|| ===== ##available_languages($subset = true): array## ===== ||
|| Returns list of available language translations. ||
|| **Parameters:** ||
|| - ##$subset## (bool, default: TRUE) ||
|| - ##TRUE##: Only allowed languages ||
|| - ##FALSE##: All available languages ||
|| **Features:** ||
|| - Scans ##LANG_DIR## for language files ||
|| - Filters by ##allowed_languages## config if set ||
|| - Caches result in session ||
|| - System language always included ||
|| **Returns:** ||
|| - Associative array: ##['en' => 'en',
'de' => 'de', ...]## ||
|| **Example:** ||
|| %%php
$all_langs = $http->available_languages(false);
$allowed = $http->available_languages(true);
%% ||
|| ---- ||
|| ==== File Serving ==== ||
|| ===== ##sendfile($path, $filename = null, $age = null): void##
===== ||
|| Serves files with proper HTTP headers and caching. ||
|| **Parameters:** ||
|| - ##$path## (string) - File path (or HTTP_XXX constant for error
pages) ||
|| - ##$filename## (string, optional) - Custom download filename ||
|| - ##$age## (int, optional) - Cache age in days ||
|| **Features:** ||
|| - HTTP range request support (partial file downloads) ||
|| - ETag and Last-Modified conditional requests ||
|| - Proper MIME type detection ||
|| - Content-Security-Policy for special file types ||
|| - Streaming for large files ||
|| - GZip compression for text files ||
|| **Special Paths:** ||
|| %%php
$http->sendfile(404);  // Serves file defined by HTTP_404 constant
$http->sendfile(403);  // Serves file defined by HTTP_403 constant
%% ||
|| **Example:** ||
|| %%php
$http->sendfile('uploads/document.pdf',
'my-document.pdf', 30);
%% ||
|| ---- ||
|| ===== ##mime_type($path): string## ===== ||
|| Returns MIME type for a file. ||
|| **Returns:** ||
|| - MIME type string (e.g., 'application/pdf') ||
|| - Default: ##'application/octet-stream'## ||
|| **Example:** ||
|| %%php
$mime = $http->mime_type('file.pdf');  //
'application/pdf'
%% ||
|| ---- ||
|| ===== ##mime_types(): array## (Private) ===== ||
|| Loads and caches MIME types from configuration. ||
|| **Features:** ||
|| - Reads from ##config/mime.types## ||
|| - Caches to ##cache/config/mime.types## ||
|| - Reloads if config is updated ||
|| ---- ||
|| ==== Compression ==== ||
|| ===== ##gzip(): void## ===== ||
|| Compresses HTTP response with gzip/x-gzip. ||
|| **Features:** ||
|| - Manually implements gzip (not relying on zlib.output_compression)
||
|| - Produces correct ##Content-Length## header ||
|| - Only compresses if: ||
|| - 860 bytes < content < 1 MB ||
|| - Client accepts compression ||
|| - Headers not already sent ||
|| **Example:** ||
|| %%php
$http->gzip();
%% ||
|| ---- ||
|| ==== Utility Methods ==== ||
|| ===== ##parse_str($str): array## (Private) ===== ||
|| Parses URL-encoded strings with special character handling. ||
|| **Purpose:** ||
|| - Safely handles special characters in query/form data ||
|| - Converts encoding properly ||
|| **Example:** ||
|| %%php
$data = $http->parse_str('name=John&age=30');
%% ||
|| ---- ||
|| ===== ##request_uri(): string## (Private) ===== ||
|| Extracts and normalizes REQUEST_URI from server. ||
|| **Normalization:** ||
|| - Removes base URL prefix ||
|| - Removes spaces ||
|| - Collapses multiple slashes ||
|| - Removes ##..## path traversal attempts ||
|| - Removes leading/trailing slashes ||
|| ---- ||
|| ===== ##cut_prefix($prefix, $path): string## (Private) ===== ||
|| Removes prefix from path (case-insensitive). ||
|| ---- ||
|| ===== ##get_header_conf($file_name): string## (Private) ===== ||
|| Loads security header configuration from files. ||
|| **Files Supported:** ||
|| - ##csp.conf## / ##csp_custom.conf## ||
|| - ##permissions_policy.conf## / ##permissions_policy_custom.conf##
||
|| ---- ||
|| === Configuration Dependencies === ||
|| The class relies on these database configuration settings: ||
|| Setting | Type | Purpose ||
|| --------- | ------ | --------- ||
|| ##base_url## | string | Wiki's base URL ||
|| ##tls## | bool | Enable HTTPS enforcement ||
|| ##cache## | bool | Enable page caching ||
|| ##cache_ttl## | int | Cache lifetime in seconds ||
|| ##session_store## | int | 1=File, 0=Database ||
|| ##system_seed_hash## | string | Session encryption seed ||
|| ##cookie_prefix## | string | Session cookie prefix ||
|| ##cookie_path## | string | Cookie path ||
|| ##allow_persistent_cookie## | bool | Allow persistent login ||
|| ##session_length## | int | Session lifetime in seconds ||
|| ##reverse_proxy_addresses## | string | Comma/space-separated proxy
IPs ||
|| ##reverse_proxy_header## | string | Custom X-Forwarded header ||
|| ##language## | string | Default language code ||
|| ##multilanguage## | bool | Enable language negotiation ||
|| ##allowed_languages## | string | Comma/space-separated allowed
langs ||
|| ##enable_security_headers## | bool | Send security headers ||
|| ##csp## | int | CSP setting (0/1/2) ||
|| ##permissions_policy## | int | Permissions-Policy setting (0/1/2)
||
|| ##referrer_policy## | int | Referrer-Policy setting (0-8) ||
|| ---- ||
|| === Constants Used === ||
|| Constant | Type | Purpose ||
|| ---------- | ------ | --------- ||
|| ##IN_WACKO## | bool | Security check (exit if not defined) ||
|| ##CHMOD_SAFE## | int | File permissions for cache files ||
|| ##CHMOD_FILE## | int | File permissions for config cache ||
|| ##CACHE_PAGE_DIR## | string | Page cache directory ||
|| ##CACHE_SESSION_DIR## | string | Session cache directory ||
|| ##CACHE_CONFIG_DIR## | string | Config cache directory ||
|| ##CONFIG_DIR## | string | Configuration directory ||
|| ##LANG_DIR## | string | Language files directory ||
|| ##DAYSECS## | int | Seconds in a day (86400) ||
|| ##HTTP_404## | string | Path to 404 error page ||
|| ##HTTP_403## | string | Path to 403 error page ||
|#
=== Workflow Examples ===
==== Example 1: Handling a GET Request ====
// In main wiki entry point
$http = new Http($db);
$http->session(0);  // Start session
// Check if page can be served from cache
$http->check_cache('HomePage', 'show');
// ... render page content ...
// Store rendered page in cache if applicable
$http->store_cache();
// Send security headers
$http->http_security_headers();
// Possibly compress output
$http->gzip();
==== Example 2: Handling TLS/HTTPS Upgrade ====
$http = new Http($db);  // Constructor detects TLS requirement
// If TLS is enabled and user wasn't in TLS before:
// - Sets TLS session flag
// - Marks session with TLS cookie
// - Redirects to HTTPS version
==== Example 3: Invalidating Cache After Page Edit ====
// User edits a page
$http = new Http($db);
$count = $http->invalidate_page('HomePage');
// All cached versions (different languages, methods) are invalidated
==== Example 4: Serving a File ====
$http = new Http($db);
$http->session(2);  // Static file mode - no session replay
prevention
// Serve with 30-day cache
$http->sendfile('uploads/manual.pdf',
'user-manual.pdf', 30);