WackoWiki: HTTP Class - Technical Documentation

https://wackowiki.org/doc     Version: 5 (05/05/2026 21:05)

HTTP Class - Technical Documentation

1. 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)

2. Class Properties

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

2.2. Private Properties


Property Type Description
$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)

3. Constructor 


public function __construct(&$db)


Purpose: Initializes the Http object and sets up HTTP session handling.

Parameters:

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:
$http = new Http($db);

4. Core Methods

4.1. Session Management

4.1.1. session($route): void

Initializes the session handler (file-based or database-based).

Parameters:

Features:

Example:
$http->session(0);  // Normal session
$http->session(2);  // Static file serving mode

4.2. Caching System

4.2.1. check_cache($page, $method): void

Determines if a page can be cached and prepares the cache check.

Parameters:

Caching Rules:

Example:
$http->check_cache('HomePage', 'show');

4.2.2. store_cache(): void

Saves the generated page content to cache file.

Features:

Example:
// Called at end of page rendering
$http->store_cache();

4.2.3. invalidate_page($page): int

Invalidates all cached versions of a page.

Parameters:

Returns:

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:
$count = $http->invalidate_page('HomePage');
echo "Invalidated $count cache entries";

4.3. TLS/HTTPS Security

4.3.1. secure_base_url(): void

Switches base URL from HTTP to HTTPS.

Purpose:

Example:
$http->secure_base_url();
// $db->base_url now uses https://

4.3.2. ensure_tls($url): void

Enforces HTTPS for a specific URL and redirects if necessary.

Parameters:

Behavior:

Example:
$http->ensure_tls('/secure/payment');

4.4. IP Address Detection

4.4.1. 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:

Configuration in Database:

Example:
$client_ip = $http->ip;  // e.g., "203.0.113.42"

4.5. HTTPS Detection

4.5.1. tls_session(): bool (Private)

Detects if current connection uses HTTPS/TLS.

Checks (any being true = HTTPS):

4.6. Security Headers

4.6.1. 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:

Example:
$http->http_security_headers();

4.7. HTTP Methods

4.7.1. redirect($url, $permanent = false): void

Performs an HTTP redirect.

Parameters:

Features:

Example:
$http->redirect('http://example.com/new-page', true);  // 301
$http->redirect('/wiki/HomePage');                       // 302

4.7.2. terminate(): void

Safe exit/die with cleanup.

Cleanup Operations:

Example:
$http->terminate();

4.7.3. status($code): void

Sets HTTP response status code.

Supported Status Codes:
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:
$http->status(404);  // Send 404 Not Found

4.8. Caching Control

4.8.1. no_cache($client_only = true): void

Disables caching of the current page.

Parameters:

Headers Set:

Example:
$http->no_cache();        // Client-side only
$http->no_cache(false);   // Both client & server

4.8.2. cache_promisc(): void

Marks page as publicly cacheable.

Headers Set:

Example:
$http->cache_promisc();

4.9. Language Negotiation

4.9.1. user_agent_language(): string

Determines best language based on browser preferences.

Features:

Example Header:
Accept-Language: en-US,en;q=0.9,de;q=0.8


Returns:

4.9.2. available_languages($subset = true): array

Returns list of available language translations.

Parameters:

Features:

Returns:

Example:
$all_langs = $http->available_languages(false);
$allowed = $http->available_languages(true);

4.10. File Serving

4.10.1. sendfile($path, $filename = null, $age = null): void

Serves files with proper HTTP headers and caching.

Parameters:

Features:

Special Paths:
$http->sendfile(404);  // Serves file defined by HTTP_404 constant
$http->sendfile(403);  // Serves file defined by HTTP_403 constant


Example:
$http->sendfile('uploads/document.pdf', 'my-document.pdf', 30);

4.10.2. mime_type($path): string

Returns MIME type for a file.

Returns:

Example:
$mime = $http->mime_type('file.pdf');  // 'application/pdf'

4.10.3. mime_types(): array (Private)

Loads and caches MIME types from configuration.

Features:

4.11. Compression

4.11.1. gzip(): void

Compresses HTTP response with gzip/x-gzip.

Features:

Example:
$http->gzip();

4.12. Utility Methods

4.12.1. parse_str($str): array (Private)

Parses URL-encoded strings with special character handling.

Purpose:

Example:
$data = $http->parse_str('name=John&age=30');

4.12.2. request_uri(): string (Private)

Extracts and normalizes REQUEST_URI from server.

Normalization:

4.12.3. cut_prefix($prefix, $path): string (Private)

Removes prefix from path (case-insensitive).

4.12.4. get_header_conf($file_name): string (Private)

Loads security header configuration from files.

Files Supported:

5. 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)

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

7. Workflow Examples

7.1. 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();

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

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

7.4. 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);

8. Security Considerations

8.1. 1. IP Address Spoofing

8.2. 2. Session Security

8.3. 3. TLS Enforcement

8.4. 4. Content Security

8.5. 5. File Serving

8.6. 6. Cache Security

9. Performance Optimization

9.1. 1. Page Caching

9.2. 2. MIME Type Caching

9.3. 3. Session Options

9.4. 4. Compression

10. Debugging


The class integrates with WackoWiki's diagnostic system:

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

11. Related Classes

12. Version History

13. 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: