README

English | 中文

A PHP core library for parsing and generating Proxy Protocol. Supports both V1 (text format) and V2 (binary format) versions of the protocol with comprehensive data structures and parsing capabilities.

Features

Full Protocol Support: Complete implementation of Proxy Protocol V1 (text format) and V2 (binary format)
Type Safety: Extensive use of PHP 8.1+ enums and type hints for safer protocol constant usage
Exception Handling: Dedicated exception classes for protocol parsing errors
Interface-Driven Design: Common interface for all protocol versions ensuring consistency
Comprehensive Address Support: Support for IPv4, IPv6, and Unix socket addresses
PSR Compliance: Follows PSR-4 autoloading and PSR-12 coding standards

Requirements

PHP 8.1 or higher
tourze/enum-extra package for enhanced enum functionality

Installation

composer require tourze/proxy-protocol-core

Quick Start

Proxy Protocol V1 (Text Format)

<?php

use Tourze\ProxyProtocol\Enum\Version;
use Tourze\ProxyProtocol\Model\Address;
use Tourze\ProxyProtocol\Model\V1Header;

// Create a V1 header
$header = new V1Header();
$header->setVersion(Version::V1);
$header->setProtocol('TCP4');
$header->setSourceAddress(new Address('192.168.1.1', 12345));
$header->setTargetAddress(new Address('192.168.1.2', 80));

// Generate protocol string
$protocolString = $header->toProtocolString();
echo $protocolString; // PROXY TCP4 192.168.1.1 192.168.1.2 12345 80\r\n

Proxy Protocol V2 (Binary Format)

<?php

use Tourze\ProxyProtocol\Enum\AddressFamily;
use Tourze\ProxyProtocol\Enum\Command;
use Tourze\ProxyProtocol\Enum\Version;
use Tourze\ProxyProtocol\Model\V2Header;

// Create a V2 header
$header = new V2Header();
$header->setVersion(Version::V2);
$header->setCommand(Command::PROXY);
$header->setAddressFamily(AddressFamily::TCP4);
$header->setSourceAddress('192.168.1.1');
$header->setSourcePort(12345);
$header->setTargetAddress('192.168.1.2');
$header->setTargetPort(80);

// Generate binary protocol data
$binaryData = $header->constructProxyHeader();

// Parse a V2 header from binary data
$parsedHeader = V2Header::parseHeader($binaryData);

Exception Handling

<?php

use Tourze\ProxyProtocol\Exception\InvalidProtocolException;
use Tourze\ProxyProtocol\Exception\UnsupportedProtocolException;
use Tourze\ProxyProtocol\Model\V2Header;

try {
    $header = V2Header::parseHeader($invalidData);
} catch (InvalidProtocolException $e) {
    echo "Invalid protocol data: " . $e->getMessage();
} catch (UnsupportedProtocolException $e) {
    echo "Unsupported protocol version: " . $e->getMessage();
}

API Documentation

Enumerations

Version: Protocol version (V1, V2)
Command: V2 protocol command (PROXY, LOCAL)
AddressFamily: Address family and transport protocol combinations
- TCP4: IPv4 over TCP
- UDP4: IPv4 over UDP
- TCP6: IPv6 over TCP
- UDP6: IPv6 over UDP
- UNIX_STREAM: Unix socket with stream
- UNIX_DGRAM: Unix socket with datagram
- UNSPECIFIED: Unspecified protocol

Models

HeaderInterface: Common interface for all protocol headers
V1Header: Proxy Protocol V1 implementation
V2Header: Proxy Protocol V2 implementation
Address: Address/port pair representation

Exceptions

InvalidProtocolException: Thrown when protocol data is malformed
UnsupportedProtocolException: Thrown when protocol version is not supported

Contributing

Please see CONTRIBUTING.md for details on how to contribute to this project.

License

The MIT License (MIT). Please see License File for more information.

tourze / proxy-protocol-core

Maintainers

Details