Difference between revisions for Users / Eo Ny / dev

• Detailed
• Simple
• Source
• Side by side
• Inline
• Merged

HTTP Class Technical Documentation

Overview

Class Properties

Private Properties

php <!--markup:1:begin-->||
||<!--markup:1:end-->
public function __construct(&$db)	

• ** || || $db - Database object reference

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

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

• ** || || $route (int) - Routing flag:
• || || Bit 2 ($route & 2): Enable static mode for files/freecap (disables replay prevention and ID regeneration)

• ** || || Selects storage backend (file or database)
• || || Configures cookie settings (security, path, httponly)
• || || Binds IP and TLS validation
• || || Recovers diagnostic logs from previous session

php** <!--markup:1:begin-->||
||<!--markup:1:end-->
$http->session(0);  // Normal session
$http->session(2);  // Static file serving mode	

• ** || || $page (string) - Page name to cache
• || || $method (string) - Request method/action (e.g., 'show', 'edit')

• ** || || ✅ 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)

php** <!--markup:1:begin-->||
||<!--markup:1:end-->
$http->check_cache('HomePage', 'show');	

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

php** <!--markup:1:begin-->||
||<!--markup:1:end-->
// Called at end of page rendering
$http->store_cache();	

• ** || || $page (string) - Page name to invalidate

• ** || || Number of cache entries invalidated

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

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

• ** || || Ensures all subsequent URLs use HTTPS
• || || Stores original HTTP URL for fallback
• || || Called when TLS session is detected

php** <!--markup:1:begin-->||
||<!--markup:1:end-->
$http->secure_base_url();
// $db->base_url now uses https://	

• ** || || $url (string) - URL to secure

• ** || || If not already HTTPS and TLS is enabled, forces HTTPS redirect
• || || Handles both relative and absolute URLs
• || || Converts relative URLs using current server name

php** <!--markup:1:begin-->||
||<!--markup:1:end-->
$http->ensure_tls('/secure/payment');	

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)

• ** || || Filters out private/reserved IP ranges
• || || Respects configured reverse proxy addresses
• || || Returns '0.0.0.0' as fallback

• ** || || reverse_proxy_addresses - Comma/space-separated proxy IPs
• || || reverse_proxy_header - Custom header name (default: X-Forwarded-For)

php** <!--markup:1:begin-->||
||<!--markup:1:end-->
$client_ip = $http->ip;  // e.g., "203.0.113.42"	

• ** || || $_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

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

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

• ** || || $url (string) - Target URL
• || || $permanent (bool) - Use 301 (permanent) vs 302 (temporary)

• ** || || Decodes & entities to prevent broken redirects
• || || Only works if headers not yet sent
• || || Uses output buffering to work anywhere in page processing

php** <!--markup:1:begin-->||
||<!--markup:1:end-->
$http->redirect('http://example.com/new-page', true);  // 301
$http->redirect('/wiki/HomePage');                       // 302	

• ** || || Saves diagnostic logs to session flash data
• || || Ends script execution

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

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'	

php** <!--markup:1:begin-->||
||<!--markup:1:end-->
$http->status(404);  // Send 404 Not Found	

• ** || || $client_only (bool, default: TRUE)
• || || TRUE: Disable browser cache only
• || || FALSE: Disable both browser and server cache

• ** || || Last-Modified: <current-time> (always fresh)
• || || Cache-Control: no-store

php** <!--markup:1:begin-->||
||<!--markup:1:end-->
$http->no_cache();        // Client-side only
$http->no_cache(false);   // Both client & server	

• ** || || Cache-Control: public

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

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

** <!--markup:1:begin-->||
||<!--markup:1:end-->
Accept-Language: en-US,en;q=0.9,de;q=0.8	

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

• ** || || $subset (bool, default: TRUE)
• || || TRUE: Only allowed languages
• || || FALSE: All available languages

• ** || || Scans LANG_DIR for language files
• || || Filters by allowed_languages config if set
• || || Caches result in session
• || || System language always included

• ** || || Associative array: ['en' => 'en', 'de' => 'de', ...]

php** <!--markup:1:begin-->||
||<!--markup:1:end-->
$all_langs = $http->available_languages(false);
$allowed = $http->available_languages(true);	

• ** || || $path (string) - File path (or HTTP_XXX constant for error pages)
• || || $filename (string, optional) - Custom download filename
• || || $age (int, optional) - Cache age in days

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

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	

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

• ** || || MIME type string (e.g., 'application/pdf')
• || || Default: 'application/octet-stream'

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

• ** || || Reads from config/mime.types
• || || Caches to cache/config/mime.types
• || || Reloads if config is updated

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

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

• ** || || Safely handles special characters in query/form data
• || || Converts encoding properly

php** <!--markup:1:begin-->||
||<!--markup:1:end-->
$data = $http->parse_str('name=John&age=30');	

• ** || || Removes base URL prefix
• || || Removes spaces
• || || Collapses multiple slashes
• || || Removes .. path traversal attempts
• || || Removes leading/trailing slashes

• ** || || csp.conf / csp_custom.conf
• || || permissions_policy.conf / permissions_policy_custom.conf

php<!--markup:1:end--> <!--markup:2:begin-->Request====	

==== Example 2: Handling TLS/HTTPS Upgrade ====	

==== Example 3: Invalidating Cache After Page Edit ====	

==== Example 4: Serving a File ====	

----

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