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

forge-templates / php-openswoole-kit

Maintainers

Package info

Statistics

Security