Download the PHP package matheushasm/swoole-micro without Composer

Swoole Micro (MVP – Phase 1)

Swoole Micro is a lightweight toolkit to build PHP microservices and workers using Swoole processes + coroutines, with a clean architecture and pluggable components.

Phase 1 focuses on:

• Processors (job handlers)
• Workers (separate OS processes)
• CoroutinePool (parallel processing with max concurrency)
• Supervisor (Redis) (heartbeat + basic liveness monitoring)
• QueueDriver (InMemory) (for local/dev + tests)
• Minimal CLI runner

Design goals: simple, predictable, testable, framework-agnostic (Laravel support can be a separate bridge later).

Table of contents

• Why
• Architecture
• Folder structure
• Requirements
• Installation
• Quick start
• CLI
• Core concepts
• Examples
• Configuration
• Lifecycle and safety
• Roadmap
• License

Why

PHP + Swoole is powerful, but building robust microservice workers usually means:

• manual Swoole\Process handling
• coroutine orchestration by hand
• no standard monitoring/heartbeat
• lots of repeated boilerplate across services

This project provides a clean, consistent foundation to:

• run multiple independent workers (separate processes)
• run parallel tasks safely with a concurrency limit
• monitor worker health with Redis-based heartbeats
• keep the code base framework-agnostic

Architecture

High-level modules:

Core

• ProcessorInterface: your business logic handler
• Worker: process runner that pulls jobs and executes them
• CoroutinePool: concurrency limiter for coroutine-based parallel work
• Clock, Logger (optional adapters)

Queue

• QueueDriverInterface: push/pop/ack
• InMemoryQueueDriver: phase-1 driver for dev/tests

Supervisor

• SupervisorInterface: heartbeat + liveness
• RedisSupervisor: stores heartbeats and reads them back

CLI

Minimal command runner:

• worker:run (run a named worker)
• supervisor:watch (watch all heartbeats)

Rule: the core never depends on Laravel/Eloquent. Adapters/bridges come later.

Folder structure

Recommended structure for the repository:

Requirements

• PHP 8.2+
• Swoole 5+ (required for workers, coroutines, and InMemoryQueueDriver)
• Redis (required for RedisSupervisor and RedisQueueDriver)
• Composer (dependency manager)

Extensions:

• ext-swoole
• ext-redis (optional if you only use in-memory queue and skip supervisor)

Dependencies overview:

• Swoole: coroutine runtime, channels, and process lifecycle.
• Redis: supervisor heartbeats and Redis queue driver (production).

Installation

Using Composer (as a package)

Local development (path repository)

In your app composer.json:

Then:

Platform setup

Windows (requires WSL2 for Swoole):

1) Install WSL2 + Ubuntu 2) Install PHP 8.2+ and Composer 3) Install Swoole + Redis extensions:

Mac (Homebrew):

Linux (Ubuntu/Debian):

Docker (example):

Quick start

Create config/workers.php:

Run a worker:

Run multiple worker instances:

Watch heartbeats:

CLI

The CLI includes an interactive mode and basic operational commands.

Interactive mode (menu-driven):

Commands:

• interactive: starts the interactive menu (default when no command is provided)
• workers:list: list configured workers with processor and queue
• worker:run <name> [count|--instances=<count>]: run one or more worker processes by name
• worker:spawn <name> <count>: spawn multiple worker processes
• queue:push <queue> <json>: push a job into a Redis queue (requires RedisQueueDriver)
• supervisor:watch: watch Redis heartbeats and report dead workers

Examples:

Core concepts

Processor

A Processor is the unit of work. It receives a payload and performs a task.

Contract:

Best practices:

• Keep it stateless
• Inject dependencies via constructor
• Throw exceptions when failed (later phases can add retries)

BatchProcessor (easy mode)

If you want simple batch processing without dealing with coroutines directly, extend BatchProcessor. It runs one item at a time by default and can process items in parallel when you override maxConcurrency().

Contract:

• processItem($item, $payload) handles a single item
• itemsFromPayload($payload) extracts the list (defaults to items key or a list payload)
• maxConcurrency($payload) controls parallelism (default 1)

Worker

A Worker is a long-running OS process (Swoole Process recommended) that:

• continuously pops jobs from a queue
• runs them using a Processor
• uses CoroutinePool to process multiple jobs in parallel
• sends heartbeats via Supervisor

CoroutinePool

A small utility that limits parallelism:

maxConcurrency(20) means at most 20 concurrent coroutines.

Perfect for:

• multiple HTTP calls
• batch DB operations
• CPU-light tasks in parallel

QueueDriver

Queue is an interface. In phase 1 we ship an InMemory driver (dev/tests).

Contract:

• push(queue, payload)
• pop(queue)
• ack(job)

Later you plug RabbitMQ / Redis.

Supervisor (Redis)

Supervisor stores worker heartbeats in Redis:

• key: prefix + workerName + instanceId
• value: last heartbeat timestamp

watch command checks dead workers by time threshold.

Examples

Example 1: A simple processor

examples/processors/SendEmailProcessor.php

Example 2: Worker consuming jobs from queue

Pseudo-usage (your Worker will do the loop):

Example 2.1: Running workers with Redis queue via CLI

Example 2.2: Spawning multiple instances

Example 2.3: Full Redis worker setup (Processor + CLI)

Example 3: Parallel processing with CoroutinePool

When you need to process a batch in parallel:

Use cases:

• fetching many URLs concurrently
• sending batches of notifications
• reading/writing multiple small files

Example 3.1: Work inside a worker with extra coroutines

Example 3.2: BatchProcessor for simple parallelism

Fluent override:

Example 4: Supervisor heartbeat monitoring

Worker side:

Watcher side:

Configuration

Suggested env vars:

Worker-level config (phase 1):

• concurrency: number of parallel jobs
• timeoutSeconds: max execution time per job (soft limit)
• memoryLimitMb: triggers graceful exit when exceeded
• heartbeatSeconds: heartbeat interval

Lifecycle and safety

Long-lived PHP processes require discipline.

Recommended lifecycle hooks (phase 1 can start minimal, but keep a place for them):

• onWorkerStart()
• beforeJob()
• afterJob()
• onWorkerStop()

Safety rules (important):

• Do not use hidden global state
• Be careful with static caches
• Reset per-job state if needed
• Always catch top-level exceptions and keep the worker alive (or exit gracefully)

Memory limits approach:

If memory grows beyond memoryLimitMb, worker should:

• stop consuming new jobs
• finish running jobs
• exit with code 0 (so external supervisor restarts it)

Roadmap

Phase 1 (this README)

• Processor contract
• Worker runner
• CoroutinePool
• Redis heartbeats
• InMemory queue
• Minimal CLI

Phase 2

• RabbitMQ driver
• Redis queue driver
• Retry strategy (exponential backoff)
• Dead-letter queue
• Metrics (Prometheus)

Phase 3

• Laravel bridge package
• Dashboard (optional)
• Distributed locks for singleton workers

License

MIT

Git Hooks

Run unit tests on every git push:

This enables .githooks/pre-push, which runs vendor/bin/phpunit.