README

A high-performance, production-ready OpenSwoole HTTP server skeleton built with modern PHP architecture principles.

This project follows a clean architecture approach, using PSR-4 autoloading, strict separation of concerns, structured logging, and a lightweight routing system optimized for high concurrency workloads.

Features

• High-performance OpenSwoole HTTP server
• PSR-4 autoloading (no manual require in app layer)
• Clean architecture (Http / Routing / Support / Controllers)
• Centralized configuration system
• .env support via phpdotenv
• Production-grade logging (Monolog with rotating files)
• Global error & exception handling (Laravel-like behavior)
• Lightweight router with dynamic routes (/users/{id})
• JSON-first API response layer
• Stateless request lifecycle (optimized for workers)
• Ready for horizontal scaling

📁 Project Structure

project/
├─ bootstrap/
│  └─ app.php              # App bootstrap (env + config loader)
├─ public/
│  └─ server.php          # Entry point (OpenSwoole server)
├─ config/
│  └─ config.php          # Central configuration
├─ app/
│  ├─ Http/
│  │  ├─ Controllers/     # Application controllers
│  │  ├─ Request.php      # Request abstraction
│  │  └─ Response.php     # Response abstraction
│  ├─ Routing/            # Core routing engine
│  ├─ Routes/             # Route registration layer
│  └─ Support/            # Env, Logger, Error handling
├─ storage/
│  └─ logs/              # Application logs
├─ .env
└─ composer.json

Requirements

• PHP 8.2+
• OpenSwoole extension
• Composer

Installation

composer create-project forge-templates/php-openswoole-kit

Environment Setup

Run :

cp .env.example .env

Or create .env file in the project root:

APP_NAME="My OpenSwoole Service"
APP_ENV=production
APP_DEBUG=false
APP_TIMEZONE=Asia/Aden

HOST=0.0.0.0
PORT=8077

MAX_REQUEST=10000
REQUEST_TIMEOUT_MS=30000
REQUEST_BODY_SIZE_LIMIT=2097152

RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX=60

LOG_LEVEL=info
LOG_DAYS=14

Running the Server

php public/server.php

You should see:

[PRODUCTION] My OpenSwoole Service started on 0.0.0.0:8077

🧠 Architecture Overview

1. Bootstrap Layer

• Loads Composer autoload
• Loads .env
• Builds configuration array

2. Configuration Layer

• Centralized config via config/config.php
• Environment values injected through Env helper
• No direct getenv() usage in business logic

3. HTTP Layer

• Request wraps OpenSwoole request
• Response handles output (JSON / Text / HTML)
• Stateless per request lifecycle

4. Routing Layer

• Static + dynamic routes supported

• Supports:

  • /users/{id}
  • /api/*

• Clean controller binding

5. Support Layer

• Global error handler (exceptions, fatal errors)
• Structured logging (Monolog)
• Central environment helper

Routing Example

$router->get('/health', HealthController::class);
$router->get('/users/{id}', UserShowController::class);

Controller example:

final class HealthController
{
    public function __invoke(Request $req, Response $res): void
    {
        $res->json([
            'status' => 'ok',
        ]);
    }
}

Logging

Logs are stored in:

storage/logs/app.log

Features:

• Rotating logs
• Structured output
• Error + exception capture
• Production-safe format

Error Handling

• Global exception handler
• Fatal error capture
• Debug mode support
• Production-safe JSON error responses

Performance Notes

Designed for:

• Long-running OpenSwoole workers
• High concurrency traffic
• Minimal per-request overhead
• No repeated bootstrapping per request

🔐 Security Notes

• Sensitive values stored in .env
• Config layer isolates environment access
• Body size limits enforced
• Safe JSON decoding
• Controlled error output in production

📄 License

MIT