README

A modern, secure PHP request handler for WordPress installations. Provides intelligent request routing, static file serving, and comprehensive security features. Optimized for traditional hosting, AWS Lambda, and containerized environments.

Features

• Simple API: Just three lines of code to get started
• Intelligent Routing: Automatic handling of WordPress requests, static files, and directories
• Security First: Built-in protection against common attacks
• Multisite Support: Full support for WordPress Multisite installations
• AWS Lambda Ready: Automatic environment detection and optimization
• Extensible: Easy to add custom processing logic
• Modern PHP: PHP 8.0+ with strict typing and Symfony HttpFoundation

Requirements

• PHP 8.0 or higher
• WordPress 5.0 or higher (recommended)

Installation

Install via Composer:

composer require wpnx/handler

Quick Start

Minimal Setup

<?php
require_once __DIR__ . '/vendor/autoload.php';

use WpNx\Handler\Handler;

// Create handler and run
$result = (new Handler())->run();

// If a file path is returned, require it
if ($result) {
    require $result;
}

With Configuration

<?php
require_once __DIR__ . '/vendor/autoload.php';

use WpNx\Handler\Handler;
use WpNx\Handler\Configuration;

$config = new Configuration([
    'web_root' => __DIR__,
    'multisite' => true,    // Enable multisite with defaults
    'lambda' => true,       // Force Lambda mode
]);

$result = (new Handler($config))->run();

if ($result) {
    require $result;
}

Configuration

Simple Configuration

$config = new Configuration([
    'multisite' => true,    // Use default multisite settings
    'lambda' => false,      // Disable Lambda mode even if detected
]);

Detailed Configuration

Default blocked patterns:

• /\.git/
• /\.env/
• /\.htaccess/
• /composer\.(json|lock)/
• /wp-config\.php/
• /readme\.(txt|html|md)/i

WordPress Multisite

Simple Mode

$config = new Configuration([
    'multisite' => true  // Use default settings
]);

Custom Pattern

$config = new Configuration([
    'multisite' => [
        'enabled' => true,
        'pattern' => '#^/sites/([^/]+)(/wp-.*)#',
        'replacement' => '/wp$2'
    ]
]);

AWS Lambda Support

Auto-Detection

The handler automatically detects Lambda environments and:

• Creates necessary temp directories
• Configures PHP settings for Lambda
• Optimizes for Lambda constraints

Manual Control

// Force Lambda mode on (useful for testing)
$config = new Configuration(['lambda' => true]);

// Force Lambda mode off
$config = new Configuration(['lambda' => false]);

// Custom Lambda directories
$config = new Configuration([
    'lambda' => [
        'directories' => [
            '/tmp/uploads',
            '/tmp/my-app-cache',
        ]
    ]
]);

Extending the Handler

Custom Processors

Add custom request processing logic:

use WpNx\Handler\Processors\ProcessorInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

class MaintenanceModeProcessor implements ProcessorInterface
{
    public function process(Request $request, Configuration $config): Request|Response|null
    {
        if ($this->isMaintenanceMode()) {
            return new Response('Site under maintenance', 503);
        }
        return null; // Continue to next processor
    }
}

// Add to handler
$handler = new Handler($config);
$handler->addProcessor(new MaintenanceModeProcessor(), priority: 1);
$result = $handler->run();

if ($result) {
    require $result;
}

Built-in Processors

The handler uses a chain of processors in this order:

1. SecurityProcessor - Validates requests and blocks attacks
2. TrailingSlashProcessor - Ensures directories have trailing slashes
3. StaticFileProcessor - Serves static files with proper MIME types
4. PhpFileProcessor - Handles direct PHP file requests
5. DirectoryProcessor - Looks for index files in directories
6. MultisiteProcessor - Handles multisite URL rewriting
7. WordPressProcessor - Falls back to WordPress index.php

Examples

Basic WordPress Site

$result = (new Handler())->run();

if ($result) {
    require $result;
}

Multisite Network

$config = new Configuration([
    'multisite' => true,
    'web_root' => '/var/www/html'
]);

$result = (new Handler($config))->run();

if ($result) {
    require $result;
}

High-Security Setup

$config = new Configuration([
    'security' => [
        'blocked_patterns' => [
            '/\.git/',
            '/\.env/',
            '/vendor/',
            '/node_modules/',
            '/\.DS_Store$/',
            '/Thumbs\.db$/i',
        ]
    ]
]);

$result = (new Handler($config))->run();

if ($result) {
    require $result;
}

Lambda Deployment

$config = new Configuration([
    'lambda' => true,
    'multisite' => true
]);

$result = (new Handler($config))->run();

if ($result) {
    require $result;
}

Testing

# Run tests
vendor/bin/phpunit

# Run specific test
vendor/bin/phpunit tests/HandlerTest.php

# Check code style
vendor/bin/phpcs

# Fix code style
vendor/bin/phpcbf

Security

The handler includes comprehensive security measures:

• Path Traversal Protection: Prevents ../ attacks
• Symlink Validation: Ensures symlinks stay within web root
• Blocked Patterns: Protects sensitive files
• Null Byte Protection: Prevents null byte injection
• URL Encoding Protection: Detects encoded attacks

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.