|
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 ||