Difference between revisions for Users / Eo Ny / dev




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

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

(16.4 KiB) -3,400
WikiAdmin

HTTP Class Technical Documentation

Overview


The Http class (src/class/http.php) is a core component of the WackoWiki system responsible for handling HTTP request/response processing, session management, caching, and security features. This class acts as a bridge between the web server and the wiki engine.

File Location: src/class/http.php
Language: PHP
Dependencies: Database class, Session classes, Utility classes (Ut), Diagnostics class (Diag)

Class Properties


==== Public Properties ====
====Public Properties====
||
Property Type Description
$tls_session bool Indicates if the current session uses HTTPS/TLS encryption
$request_uri string Normalized REQUEST_URI (e.g., 'PageOfNoReturn/show?a=1')
$ip string Client's real IP address (accounts for proxies)
$sess Session Reference to the Session object
$method string Current HTTP method/request type

Private Properties

Private Properties


*| Property | Type | Description |
* <!markup:1:end> $db | object | Database connection reference $tls_mark | string | Cookie name for TLS session marking $page | string | Current page name being processed $hash | string | SHA1 hash of the page name $query | string | Encoded query string $lang | string | Current language code $file | string | Cache file path $caching | int | Flag indicating if page should be cached (0 or 1) <!markup:1:end>
<!markup:1:begin>
<!markup:1:begin>

=== <!--markup:1:begin-->|| ||<!--markup:1:end--> Constructor === 
php <!--markup:1:begin-->||
||<!--markup:1:end-->
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** <!--markup:1:begin-->||
||<!--markup:1:end-->
$http = new Http($db);


|| || === <!--markup:1:begin-->|| ||<!--markup:1:end--> Core Methods ===
==== <!--markup:1:begin-->|| ||<!--markup:1:end--> Session Management ====
===== <!--markup:1:begin-->|| ||<!--markup:1:end--> ##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** <!--markup:1:begin-->||
||<!--markup:1:end-->
$http->session(0);  // Normal session
$http->session(2);  // Static file serving mode


|| || ==== <!--markup:1:begin-->|| ||<!--markup:1:end--> Caching System ====
===== <!--markup:1:begin-->|| ||<!--markup:1:end--> ##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** <!--markup:1:begin-->||
||<!--markup:1:end-->
$http->check_cache('HomePage', 'show');


|| || ===== <!--markup:1:begin-->|| ||<!--markup:1:end--> ##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** <!--markup:1:begin-->||
||<!--markup:1:end-->
// Called at end of page rendering
$http->store_cache();


|| || ===== <!--markup:1:begin-->|| ||<!--markup:1:end--> ##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** <!--markup:1:begin-->||
||<!--markup:1:end-->
$count = $http->invalidate_page('HomePage');
echo "Invalidated $count cache entries";


|| || ==== <!--markup:1:begin-->|| ||<!--markup:1:end--> TLS/HTTPS Security ====
===== <!--markup:1:begin-->|| ||<!--markup:1:end--> ##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** <!--markup:1:begin-->||
||<!--markup:1:end-->
$http->secure_base_url();
// $db->base_url now uses https://


|| || ===== <!--markup:1:begin-->|| ||<!--markup:1:end--> ##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** <!--markup:1:begin-->||
||<!--markup:1:end-->
$http->ensure_tls('/secure/payment');


|| || ==== <!--markup:1:begin-->|| ||<!--markup:1:end--> IP Address Detection ====
===== <!--markup:1:begin-->|| ||<!--markup:1:end--> ##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** <!--markup:1:begin-->||
||<!--markup:1:end-->
$client_ip = $http->ip;  // e.g., "203.0.113.42"


|| || ==== <!--markup:1:begin-->|| ||<!--markup:1:end--> HTTPS Detection ====
===== <!--markup:1:begin-->|| ||<!--markup:1:end--> ##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

|| || ==== <!--markup:1:begin-->|| ||<!--markup:1:end--> Security Headers ==== || || ===== http_security_headers(): void ===== || ||
=====http_security_headers(): void=====
Sets security-related HTTP headers.

**Headers || || Set:** || ||**
*| Header | Purpose | Config Key |
* <!markup:1:end> 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<!markup:1:end>
<!markup:1:begin>
<!markup:1:begin>

CSP Configuration Options:
  • ** || || 0 - Disabled
  • || || 1 - Default policy (from csp.conf)
  • || || 2 - Custom policy (from csp_custom.conf)

**Example: || ||** 
php** <!--markup:1:begin-->||
||<!--markup:1:end-->
$http->http_security_headers();


|| || ==== <!--markup:1:begin-->|| ||<!--markup:1:end--> HTTP Methods ==== ===== <!--markup:1:begin-->|| ||<!--markup:1:end--> ##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** <!--markup:1:begin-->||
||<!--markup:1:end-->
$http->redirect('http://example.com/new-page', true);  // 301
$http->redirect('/wiki/HomePage');                       // 302


|| || ===== <!--markup:1:begin-->|| ||<!--markup:1:end--> ##terminate(): void## =====
Safe || || exit/die with cleanup.
**Cleanup || || Operations:**
  • ** || || Saves diagnostic logs to session flash data
  • || || Ends script execution

**Example: || ||** 
php** <!--markup:1:begin-->||
||<!--markup:1:end-->
$http->terminate();


|| || ===== <!--markup:1:begin-->|| ||<!--markup:1:end--> ##status($code): void## =====
Sets || || HTTP response status code.
**Supported || || Status Codes:** 
php** <!--markup:1:begin-->||
||<!--markup:1:end-->
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** <!--markup:1:begin-->||
||<!--markup:1:end-->
$http->status(404);  // Send 404 Not Found


|| || ==== <!--markup:1:begin-->|| ||<!--markup:1:end--> Caching Control ====
===== <!--markup:1:begin-->|| ||<!--markup:1:end--> ##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** <!--markup:1:begin-->||
||<!--markup:1:end-->
$http->no_cache();        // Client-side only
$http->no_cache(false);   // Both client & server


|| || ===== <!--markup:1:begin-->|| ||<!--markup:1:end--> ##cache_promisc(): void## =====
Marks || || page as publicly cacheable.
**Headers || || Set:**
  • ** || || Cache-Control: public

**Example: || ||** 
php** <!--markup:1:begin-->||
||<!--markup:1:end-->
$http->cache_promisc();


|| || ==== <!--markup:1:begin-->|| ||<!--markup:1:end--> Language Negotiation ====
===== <!--markup:1:begin-->|| ||<!--markup:1:end--> ##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:** 
** <!--markup:1:begin-->||
||<!--markup:1:end-->
Accept-Language: en-US,en;q=0.9,de;q=0.8


**Returns: || ||**
  • ** || || Language code (e.g., 'en', 'en-US', 'de')

|| || ===== <!--markup:1:begin-->|| ||<!--markup:1:end--> ##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** <!--markup:1:begin-->||
||<!--markup:1:end-->
$all_langs = $http->available_languages(false);
$allowed = $http->available_languages(true);


|| || ==== <!--markup:1:begin-->|| ||<!--markup:1:end--> File Serving ====
===== <!--markup:1:begin-->|| ||<!--markup:1:end--> ##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** <!--markup:1:begin-->||
||<!--markup:1:end-->
$http->sendfile(404);  // Serves file defined by HTTP_404 constant
$http->sendfile(403);  // Serves file defined by HTTP_403 constant


**Example: || ||** 
php** <!--markup:1:begin-->||
||<!--markup:1:end-->
$http->sendfile('uploads/document.pdf', 'my-document.pdf', 30);


|| || ===== <!--markup:1:begin-->|| ||<!--markup:1:end--> ##mime_type($path): string## =====
Returns || || MIME type for a file.
**Returns: || ||**
  • ** || || MIME type string (e.g., 'application/pdf')
  • || || Default: 'application/octet-stream'

**Example: || ||** 
php** <!--markup:1:begin-->||
||<!--markup:1:end-->
$mime = $http->mime_type('file.pdf');  // 'application/pdf'


|| || ===== <!--markup:1:begin-->|| ||<!--markup:1:end--> ##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

|| || ==== <!--markup:1:begin-->|| ||<!--markup:1:end--> Compression ====
===== <!--markup:1:begin-->|| ||<!--markup:1:end--> ##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** <!--markup:1:begin-->||
||<!--markup:1:end-->
$http->gzip();


|| || ==== <!--markup:1:begin-->|| ||<!--markup:1:end--> Utility Methods ====
===== <!--markup:1:begin-->|| ||<!--markup:1:end--> ##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** <!--markup:1:begin-->||
||<!--markup:1:end-->
$data = $http->parse_str('name=John&age=30');


|| || ===== <!--markup:1:begin-->|| ||<!--markup:1:end--> ##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

|| || ===== <!--markup:1:begin-->|| ||<!--markup:1:end--> ##cut_prefix($prefix, $path): string## (Private) =====
Removes || || prefix from path (case-insensitive).
|| || ===== <!--markup:1:begin-->|| ||<!--markup:1:end--> ##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

|| || === <!--markup:1:begin-->|| ||<!--markup:1:end--> Configuration Dependencies ===


=== <!--markup:1:begin-->|| || 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) || || ---- || ||<!--markup:1:end--> Constants Used ===


=== <!--markup:1:begin-->|| || 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 || |# ----<!--markup:1:end--> Workflow Examples ===

Example 1: Handling a GET Request 


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


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


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


php
$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);


Security Considerations

1. IP Address Spoofing

  • Validates IPs against private ranges
  • Filters proxy-provided IPs appropriately
  • Configurable reverse proxy trust

2. Session Security

  • Binds sessions to IP address
  • Binds sessions to TLS status
  • Supports both file and database storage
  • HttpOnly cookies by default

3. TLS Enforcement

  • Automatic HTTPS upgrade when configured
  • Marks TLS sessions to prevent downgrade attacks
  • HSTS header support

4. Content Security

  • CSP headers to prevent XSS
  • X-Frame-Options to prevent clickjacking
  • X-Content-Type-Options to prevent MIME sniffing
  • Referrer-Policy control
  • Permissions-Policy for browser features

5. File Serving

  • Validates file existence and readability
  • Prevents directory traversal via realpath()
  • Rejects symbolic links
  • Special CSP for SVG and PDF files

6. Cache Security

  • Cached only for anonymous users
  • Disabled for sensitive operations (edit, watch)
  • Only GET requests cached

Performance Optimization

1. Page Caching

  • Stores full HTML output
  • TTL-based expiration
  • Language and method-aware caching
  • Conditional request support (304 Not Modified)

2. MIME Type Caching

  • Loads MIME types once and caches
  • Regenerates only when config changes

3. Session Options

  • File-based sessions for simple deployments
  • Database sessions for distributed systems

4. Compression

  • Manual gzip implementation
  • Proper Content-Length generation
  • Only compresses appropriate sizes

Debugging


The class integrates with WackoWiki's diagnostic system:

php
// Diagnostic messages are preserved across redirects
// via session flash data

// Check cached pages (debug comments in output):
// <!-- WackoWiki Caching Engine: page cached at 2024-01-15 12:30:45 GMT -->


Related Classes

  • Session Classes (SessionFileStore, SessionDbalStore) - Session management backends
  • Database Class - Configuration and cache metadata storage
  • Ut Utility Class - String/path utilities
  • Diag Class - Diagnostic logging

Version History

  • Supports PHP 8.0+ (uses match expressions, union types)
  • Follows RFC 9110 for HTTP header handling
  • Modern cookie security practices

Conclusion


The Http class is the central request/response handler in WackoWiki, managing everything from session initialization to security headers to file serving. Understanding this class is essential for:
  • Extending WackoWiki with custom request handlers
  • Implementing custom session logic
  • Adding new security policies
  • Optimizing cache strategies
  • Debugging HTTP-related issues