README

A high-performance C++ PHP extension providing a compact HTTP/HTTPS server with routing and middleware for building lightweight microservices and APIs. Built on embedded HTTP server with full PHP compatibility and enterprise-grade performance.

⚡ Key Features

🚀 High Performance: 63K requests/second at 200 concurrency with 0.25ms P95 latency
🔒 Secure: Built-in HTTPS/SSL support with TLS encryption
🛠️ Full PHP Compatibility: Complete PHP processing without fast-path bypass
🏗️ Microservices Ready: Lightweight server for containerized deployments
🔧 Configurable: Environment-based configuration and INI settings
📊 Production Ready: Comprehensive logging and monitoring support
🔄 PHP Ecosystem: Seamless integration with PHP frameworks
🌐 Distributed: Designed for microservices architecture

📦 Installation

Via PIE (Recommended)

pie install kislayphp/core

Add to your php.ini:

extension=kislayphp_extension.so

Manual Build

git clone https://github.com/KislayPHP/core.git
cd core
phpize
./configure --enable-kislayphp_extension
make
sudo make install

container

FROM php:8.2-cli

🚀 Quick Start

<?php

// Create server instance
$app = new Kislay\Core\App();

// Configure server
$app->setOption('num_threads', 4);
$app->setOption('document_root', '/var/www');

// Add middleware
$app->use(function ($req, $res, $next) {
    $next();
});

// Path-scoped middleware (Kislay)
$app->use('/api', function ($req, $res, $next) {
    $res->set('X-Powered-By', 'Kislay');
    $next();
});

// Define routes
$app->get('/api/users', function ($req, $res) {
    $users = [
        ['id' => 1, 'name' => 'John Doe'],
        ['id' => 2, 'name' => 'Jane Smith']
    ];
    $res->json($users);
});

$app->post('/api/users', function ($req, $res) {
    $data = $req->getJson();
    $res->json(['status' => 'created', 'id' => 123]);
});

// Start server
$app->listen('0.0.0.0', 8080);

num_threads note:

On non-thread-safe PHP builds (Thread Safety => disabled), values above 1 are automatically clamped to 1 to prevent middleware/route instability.
Invalid option values now fall back to safe defaults with runtime warnings instead of hard failures.
On non-thread-safe PHP builds, listen()/listenAsync() enable NTS compatibility mode (disables Zend stack guard) to prevent request-time internal recursion errors.

Cross-origin note:

Browser strict-origin-when-cross-origin behavior is now handled with an explicit Referrer-Policy response header (default: strict-origin-when-cross-origin).
Override with $app->setOption('referrer_policy', 'origin-when-cross-origin') or disable with $app->setOption('referrer_policy', 'off').
If CORS is disabled, browser preflight requests receive 403 with a hint: CORS disabled. Enable with $app->setOption('cors', true).

Request log format (enable via $app->setOption('log', true)):

[kislay] time="YYYY-MM-DD HH:MM:SS.mmm" request="METHOD /path" response="STATUS BYTES" duration_ms=NN error="..."

Kislay routing helpers:

// Match all HTTP methods on one path
$app->all('/health', function ($req, $res) {
    $res->sendStatus(204); // sets code + standard status text body
});

Non-blocking lifecycle:

$app->listenAsync('0.0.0.0', 8080);

// do startup tasks, health checks, etc.
if ($app->isRunning()) {
    $app->wait(); // block until stopped (or use $app->wait(5000) timeout)
}

🧩 Service Communication Quickstart

This repo includes a one-command starter for service communication using discovery + gateway.

cd examples/microservice-stack
cp .env.example .env
./start.sh
./status.sh

Stop it with:

./stop.sh

☁️ AWS Validation

Run full extension build/load/API/communication validation on your EC2 host:

./scripts/aws_validate_extensions.sh \
  /Users/dhruvraj/Downloads/firstkis.pem \
  ec2-54-242-252-137.compute-1.amazonaws.com \
  ubuntu

Latest report: docs/AWS_VALIDATION_2026-02-21.md Checklist: docs/PRODUCTION_READINESS_CHECKLIST.md

🏗️ Architecture

Kislay Core implements a hybrid threading model combining PHP execution with asynchronous I/O:

┌─────────────────┐    ┌─────────────────┐
│   PHP Worker    │    │   PHP Worker    │
│   Thread 1      │    │   Thread N      │
│                 │    │                 │
│ ┌─────────────┐ │    │ ┌─────────────┐ │
│ │ embedded HTTP server    │ │    │ │ embedded HTTP server    │ │
│ │ Server      │ │    │ │ Server      │ │
│ │ Socket      │ │    │ │ Socket      │ │
│ │ Multiplex   │ │    │ │ Multiplex   │ │
│ └─────────────┘ │    │ └─────────────┘ │
└─────────────────┘    └─────────────────┘
         │                       │
         └───────────────────────┘
              Shared Memory

📊 Performance

Benchmark Results (200 concurrent connections):

Throughput: 63K requests/second
P95 Latency: 0.25ms
P99 Latency: 0.45ms
CPU Usage: 11.4%
Memory: 6.0MB (stable)

🔧 Configuration

php.ini Settings

kislayphp.http.threads = 4
kislayphp.http.document_root = "/var/www"
kislayphp.http.read_timeout_ms = 10000
kislayphp.http.max_body = 1048576
kislayphp.http.cors = 0
kislayphp.http.log = 1
kislayphp.http.referrer_policy = "strict-origin-when-cross-origin"
kislayphp.http.tls_cert = "/path/to/cert.pem"
kislayphp.http.tls_key = "/path/to/key.pem"

Environment Variables

export KISLAYPHP_HTTP_THREADS=4
export KISLAYPHP_HTTP_DOCUMENT_ROOT=/var/www
export KISLAYPHP_HTTP_READ_TIMEOUT_MS=10000
export KISLAYPHP_HTTP_MAX_BODY=1048576
export KISLAYPHP_HTTP_LOG=1
export KISLAYPHP_HTTP_REFERRER_POLICY=strict-origin-when-cross-origin
export KISLAYPHP_HTTP_TLS_CERT=/path/to/cert.pem
export KISLAYPHP_HTTP_TLS_KEY=/path/to/key.pem

🧪 Testing

# Run tests
php run-tests.php

# Run benchmarks
cd tests/
php benchmark.php --duration=60 --concurrency=100

⚡ Local Benchmark Harness

Use the built-in benchmark harness to measure throughput and latency after each runtime change.

cd https
make
./bench/run_benchmark.sh

Environment overrides:

BENCH_TARGET_PATH=/json BENCH_DURATION=30 BENCH_CONCURRENCY=300 ./bench/run_benchmark.sh

Notes:

The runner auto-detects wrk first, then falls back to ab.
Install wrk on macOS with brew install wrk.
Reports are saved under bench/results/.

Run endpoint comparison (/plaintext, /json, /file) with one command:

./bench/run_benchmark_matrix.sh

Or via Makefile shortcuts:

make bench
make bench-matrix
make bench-delta
make bench-stable
make bench-stable-delta
make perf-gate
make perf-gate-quick
make perf-gate-release

Lifecycle validation tasks:

make test-lifecycle
make task-updation
make task-dev
make task-ci
make task-updation-release

Workflow guidance:

make task-updation: build + lifecycle regression suite (fastest quality check)
make task-dev: build + lifecycle regression + advisory quick perf gate
make task-ci: build + lifecycle regression + strict perf gate
make task-updation-release: build + lifecycle regression + release perf gate profile

CI Jobs

build job: runs extension build and standard test flow across PHP version matrix.
ecosystem job: runs strict ecosystem validation (make task-ci) with lifecycle checks and strict performance gate.
CI workflow file: .github/workflows/ci.yml.

Update checklist:

cat UPDATION_LIST.md

Quick example:

BENCH_CONCURRENCY=200 BENCH_DURATION=15 ./bench/run_benchmark_matrix.sh

Generate before/after delta from the latest two matrix runs:

./bench/compare_benchmarks.sh

Run deterministic stable profiling with warmup + repeats + median aggregation:

BENCH_PROFILE=release BENCH_DURATION=20 BENCH_CONCURRENCY=100 BENCH_THREADS=4 BENCH_REPEATS=3 BENCH_WARMUP_SECONDS=5 ./bench/run_benchmark_stable.sh

Optional endpoints override:

BENCH_ENDPOINTS="/plaintext /json /file" ./bench/run_benchmark_stable.sh

Generate delta from latest two stable median reports for a profile:

PERF_PROFILE=release ./bench/compare_stable_benchmarks.sh

Run a performance gate (stable benchmark + stable delta + threshold checks):

make perf-gate
make perf-gate-quick
make perf-gate-release

Notes:

perf-gate-quick is advisory (soft-fail) for fast local feedback.
perf-gate and perf-gate-release are strict and fail on threshold breaches.
Gate targets auto-run stable benchmark twice (baseline + candidate) before diffing.

Tune gate thresholds (defaults shown):

PERF_GATE_MAX_REQ_REGRESSION_PCT=5 \
PERF_GATE_MAX_P95_REGRESSION_PCT=20 \
PERF_GATE_MAX_P99_REGRESSION_PCT=30 \
make perf-gate

Exclude noisy endpoints when needed (space-separated):

PERF_GATE_EXCLUDE_ENDPOINTS="/file" make perf-gate-quick

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

📄 License

Licensed under the Apache License 2.0.

🆘 Support

📖 Documentation
🌐 Full detailed docs: Skelves Documentation Site
🧪 Local docs view: http://localhost:5180/docs
🐛 Issues
💬 Discussions

🙏 Acknowledgments

embedded HTTP server: Embedded HTTP server library
PHP: Zend API for extension development
TLS library: SSL/TLS encryption support

Built with ❤️ for the PHP community

kislayphp / core

Maintainers

Details