add php extension with pecl packaging support

[MuriloChianfa]

Description

This PR adds comprehensive PHP bindings for liblpm, providing native PHP extension support for high-performance Longest Prefix Match (LPM) operations. The implementation includes both object-oriented and procedural APIs, full IPv4/IPv6 support, batch operations, and PECL packaging for easy distribution.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Performance improvement
• Code refactoring
• Test addition/improvement
• Build/CI configuration

Related Issues

Related to language bindings expansion

Motivation and Context

PHP is widely used in web applications and network infrastructure tools. Adding native PHP bindings enables PHP developers to:

• Perform high-performance IP routing table lookups directly in PHP applications
• Leverage liblpm's optimized algorithms (DIR-24-8 for IPv4, Wide-16 for IPv6) with zero-copy performance
• Build network tools, firewalls, and routing systems using PHP
• Access batch lookup operations for processing multiple IPs efficiently

The native C extension approach provides significantly better performance compared to FFI or subprocess alternatives.

Changes Made

Core Implementation

• Native PHP extension using PHP Extension API (Zend Engine)
• Object-oriented API with LpmTable class for IPv4 and IPv6
• Procedural API for functional programming style
• Full type safety with proper error handling and exceptions
• Memory management with automatic cleanup via PHP's garbage collector

Features

• Algorithm selection support (DIR-24-8, stride8 for IPv4; wide16, stride8 for IPv6)
• Batch lookup operations for processing arrays of IP addresses
• Support for default routes (0.0.0.0/0, ::/0)
• Prefix insertion, lookup, and deletion operations
• Iterator support for traversing routing tables

Build System

• Autoconf/automake configuration (config.m4, configure.ac)
• CMake integration for unified build system
• PECL packaging support (package.xml)
• Docker container for testing and development
• CI/CD integration with GitHub Actions

Documentation

• Comprehensive README with installation and usage examples
• API documentation covering all classes and functions
• Code examples for common use cases (basic, batch, procedural)
• PECL package metadata

Testing

• 12 comprehensive test suites using PHP's .phpt format
• Tests cover: IPv4/IPv6 operations, batch lookups, error handling, memory management
• All tests validate against expected output

Infrastructure

• .gitignore for build artifacts and generated files
• Dockerfile.php for containerized testing
• CI workflow job for automated testing across PHP versions
• Integration with project's CMake build system

Testing

Test Environment

• OS: Ubuntu 25.10 (in Docker)
• Compiler: GCC 15.2.0
• PHP Version: 8.3
• CPU: x86_64 with SSE2/AVX2 support

Tests Performed

• Unit tests pass (12 .phpt tests in tests/ directory)
• New tests added for this change
• Existing tests updated (not applicable - new feature)
• Memory leak check with Valgrind (TODO: recommended before merge)
• Static analysis with cppcheck (core library already checked)
• Fuzz testing (not applicable for bindings)
• Docker container builds and tests successfully
• CI integration tested

Test Output

# Tests can be run via Docker:
docker run --rm liblpm-php

# Or manually after building:
cd bindings/php
php run-tests.php -q tests/

# Expected: All 12 tests pass

Performance Impact

• No performance impact (on core library)
• Performance improvement (provides zero-copy PHP access to optimized C library)
• Potential performance regression
• Not applicable

Performance Notes

The PHP extension provides near-native C performance for PHP applications:

• Direct memory access to liblpm data structures
• Batch operations process multiple lookups with minimal overhead
• Zero-copy string handling for IP address parameters
• Efficient nexthop value marshaling between C and PHP

Documentation

• Updated code comments (inline documentation in liblpm.c)
• Updated README.md (comprehensive PHP bindings README)
• Updated API documentation (docs/API.md)
• Updated language bindings (PHP bindings added)
• Updated project documentation (docker/README.md, CI workflow)
• Added usage examples (4 example scripts)

Code Quality

• My code follows the project's coding standards
• I have performed a self-review of my code
• I have commented complex algorithms and non-obvious code
• My changes generate no new warnings
• I have added tests that prove my fix/feature works
• New and existing unit tests pass locally

Breaking Changes

• This PR introduces breaking changes
• Migration guide provided

This is a new feature addition with no breaking changes to existing functionality.

Additional Notes

Installation Methods

Via PECL (when published):

pecl install liblpm

Manual Installation:

cd bindings/php
phpize
./configure --with-liblpm=/path/to/liblpm
make
sudo make install

Enable Extension:
Add to php.ini:

extension=liblpm.so

Example Usage

Object-Oriented API:

$lpm = new LpmTable(LpmTable::AF_INET);
$lpm->insert("192.168.1.0/24", 1);
$nexthop = $lpm->lookup("192.168.1.100"); // Returns 1

Procedural API:

$lpm = liblpm_create(LpmTable::AF_INET);
liblpm_insert($lpm, "192.168.1.0/24", 1);
$nexthop = liblpm_lookup($lpm, "192.168.1.100"); // Returns 1

Package Distribution

The extension is ready for PECL publication with:

• Complete package.xml metadata
• Proper versioning and dependencies
• License information (BSD-2-Clause)
• Maintainer information

Checklist

• I have read the CONTRIBUTING guidelines
• My branch is up-to-date with the main branch
• I have squashed/organized commits logically (single feature commit)
• All CI checks pass (or will pass after PR creation)
• I have tested on multiple compilers (GCC in Docker environment)
• I have tested on different CPU architectures (x86_64 tested, ARM recommended)

Reviewer Notes

Areas for Review

1. Memory Management: Please verify that all PHP object lifecycle management is correct, especially:

   • Resource cleanup in LpmTable::__destruct()
   • Exception handling doesn't leak memory
   • Batch operation memory allocations are properly freed

2. PHP API Design: Feedback welcome on:

   • Method naming conventions
   • Parameter type hints and return types
   • Exception hierarchy (currently using generic Exception)

3. Build System: The extension integrates with both:

   • Native PHP build system (phpize/configure)
   • Project's CMake system
   • Please verify both work correctly

4. PECL Packaging: Review package.xml for:

   • Correct dependencies
   • Proper version numbering
   • Complete metadata

5. Testing: Additional test scenarios welcome, especially:

   • Edge cases for malformed IP addresses
   • Large routing table performance
   • Concurrent access patterns (if applicable)

Known Limitations

• Extension requires PHP 8.0+ (uses modern PHP API)
• Currently only tested on Linux (Windows support in config.w32 but untested)
• No thread-safety guarantees (PHP generally not used in multi-threaded contexts)

Future Enhancements

• Consider adding iterator interface for routing table traversal
• Add support for PHP 7.4 if there's demand
• Performance benchmarks comparing to pure PHP implementations
• Windows build testing and validation