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
public function __construct(&$db)	

php
$http = new Http($db);	

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

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

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

php
$count = $http->invalidate_page('HomePage');
echo "Invalidated $count cache entries";	

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

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

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

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

php
$http->http_security_headers();	

HTTP Methods

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

• $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
$http->redirect('http://example.com/new-page', true);  // 301
$http->redirect('/wiki/HomePage');                       // 302	

terminate(): void

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

php
$http->terminate();	

status($code): void

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'	

php
$http->status(404);  // Send 404 Not Found	

Caching Control

no_cache($client_only = true): void

• $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
$http->no_cache();        // Client-side only
$http->no_cache(false);   // Both client & server	

cache_promisc(): void

• Cache-Control: public

php
$http->cache_promisc();	

Language Negotiation

user_agent_language(): string

• 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

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

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

available_languages($subset = true): array

• $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
$all_langs = $http->available_languages(false);
$allowed = $http->available_languages(true);	

File Serving

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

• $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
$http->sendfile(404);  // Serves file defined by HTTP_404 constant
$http->sendfile(403);  // Serves file defined by HTTP_403 constant	

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

mime_type($path): string

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

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

mime_types(): array (Private)

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

Compression

gzip(): void

• 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
$http->gzip();	

Utility Methods

parse_str($str): array (Private)

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

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

request_uri(): string (Private)

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

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

get_header_conf($file_name): string (Private)

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

Configuration Dependencies

Constants Used

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

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

• Extending WackoWiki with custom request handlers
• Implementing custom session logic
• Adding new security policies
• Optimizing cache strategies
• Debugging HTTP-related issues