README

English | 中文

Symfony bundle for detecting and enforcing SSL/HTTPS requests based on various headers and environment variables.

Description

This bundle provides automatic SSL/HTTPS detection for Symfony applications running behind proxies, load balancers, or in containerized environments. It analyzes request headers and environment variables to determine if the original request was made over HTTPS, and sets the appropriate server variables accordingly.

Features

• 🔒 Automatic HTTPS Detection - Detects SSL/HTTPS requests from various sources
• 🌐 Proxy Support - Works with reverse proxies and load balancers
• 🐳 Container Ready - Kubernetes and Docker support
• ⚡ High Priority - Runs early in the request lifecycle (priority 9999)
• 🔧 Zero Configuration - Works out of the box with sensible defaults
• 📋 Multiple Headers - Supports various forwarding headers

Installation

Install via Composer:

composer require tourze/symfony-ssl-request-detect-bundle

If you're using Symfony Flex, the bundle will be automatically registered. Otherwise, add it manually to config/bundles.php:

<?php

return [
    // ...
    Tourze\SSLRequestDetectBundle\SSLRequestDetectBundle::class => ['all' => true],
];

Quick Start

Once installed, the bundle works automatically. It will detect HTTPS requests based on:

Environment Variables

# Force all requests to be treated as HTTPS
FORCE_HTTPS=1

# Kubernetes HTTPS port detection
KUBERNETES_PORT_443_TCP_PORT=443

HTTP Headers

The bundle automatically checks these headers:

• X-Forwarded-Port: 443
• X-Forwarded-Proto: https
• X-Forwarded-Scheme: https

Basic Usage Example

// In your controller or service
public function someAction(Request $request): Response
{
    // The bundle automatically sets HTTPS detection
    if ($request->isSecure()) {
        // Request is detected as HTTPS
        return new Response('Secure connection detected!');
    }
    
    return new Response('HTTP connection');
}

Usage

Automatic Detection

The bundle runs automatically on every request with the highest priority (9999) to ensure HTTPS detection happens before other security checks.

Environment Configuration

# Docker/Container environments
FORCE_HTTPS=1

# Kubernetes environments
KUBERNETES_PORT_443_TCP_PORT=443

Proxy Headers

Common proxy configurations that work automatically:

# Nginx proxy configuration
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Port $server_port;

# Apache proxy configuration
ProxyPreserveHost On
ProxyPass / http://backend/
ProxyPassReverse / http://backend/
ProxyAddHeaders On

Load Balancer Support

Works with common load balancers:

• AWS Application Load Balancer (ALB)
• Google Cloud Load Balancer
• Azure Application Gateway
• HAProxy
• Nginx
• Traefik

Advanced Usage

Custom Header Detection

If you need to detect HTTPS from custom headers, you can extend the bundle:

use Tourze\SSLRequestDetectBundle\EventSubscriber\SSLDetectSubscriber;
use Symfony\Component\HttpKernel\Event\RequestEvent;

class CustomSSLDetectSubscriber extends SSLDetectSubscriber
{
    public function onRequest(RequestEvent $event): void
    {
        parent::onRequest($event);
        
        $request = $event->getRequest();
        
        // Custom header detection
        if ($request->headers->get('X-Custom-HTTPS') === 'on') {
            $request->server->set('HTTPS', 'on');
        }
    }
}

Testing HTTPS Detection

use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;

class SSLDetectionTest extends WebTestCase
{
    public function testHttpsDetection(): void
    {
        $client = static::createClient();
        
        // Simulate HTTPS request via X-Forwarded-Proto
        $client->request('GET', '/', [], [], [
            'HTTP_X_FORWARDED_PROTO' => 'https',
        ]);
        
        $request = $client->getRequest();
        $this->assertTrue($request->isSecure());
    }
}

Configuration

The bundle requires no configuration and works with default settings. All detection is automatic based on:

1. Environment Variables: FORCE_HTTPS, KUBERNETES_PORT_443_TCP_PORT
2. Request Headers: X-Forwarded-Proto, X-Forwarded-Scheme, X-Forwarded-Port

Dependencies

This bundle requires:

• PHP 8.1+
• Symfony 7.3+
• symfony/http-foundation
• symfony/http-kernel
• symfony/event-dispatcher

License

This bundle is licensed under the MIT License. See the LICENSE file for details.