PHPackages                             matheushasm/swoole-micro - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. matheushasm/swoole-micro

ActiveLibrary[Framework](/categories/framework)

matheushasm/swoole-micro
========================

Lightweight toolkit to build PHP microservices and workers using Swoole processes + coroutines.

v0.1.0(4mo ago)00MITPHPPHP ^8.2

Since Dec 31Pushed 4mo agoCompare

[ Source](https://github.com/matheushasm/swoole-micro)[ Packagist](https://packagist.org/packages/matheushasm/swoole-micro)[ RSS](/packages/matheushasm-swoole-micro/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (1)Versions (2)Used By (0)

Swoole Micro (MVP – Phase 1)
============================

[](#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
-----------------

[](#table-of-contents)

- [Why](#why)
- [Architecture](#architecture)
- [Folder structure](#folder-structure)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick start](#quick-start)
- [CLI](#cli)
- [Core concepts](#core-concepts)
- [Examples](#examples)
- [Configuration](#configuration)
- [Lifecycle and safety](#lifecycle-and-safety)
- [Roadmap](#roadmap)
- [License](#license)

Why
---

[](#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
------------

[](#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
----------------

[](#folder-structure)

Recommended structure for the repository:

```
swoole-micro/
├── bin/
│   └── swoole-micro
├── config/
│   └── workers.php
├── src/
│   ├── Core/
│   │   ├── ProcessorInterface.php
│   │   ├── Worker.php
│   │   ├── WorkerOptions.php
│   │   ├── CoroutinePool.php
│   │   ├── Exceptions/
│   │   │   ├── ProcessorFailed.php
│   │   │   └── WorkerCrashed.php
│   ├── Queue/
│   │   ├── QueueDriverInterface.php
│   │   └── InMemoryQueueDriver.php
│   ├── Supervisor/
│   │   ├── SupervisorInterface.php
│   │   └── RedisSupervisor.php
│   └── Support/
│       ├── Env.php
│       └── Json.php
├── examples/
│   ├── processors/
│   │   ├── SendEmailProcessor.php
│   │   └── FetchUrlsProcessor.php
│   └── run_examples.php
├── tests/
├── composer.json
├── README.md
└── LICENSE

```

Requirements
------------

[](#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
------------

[](#installation)

Using Composer (as a package)

```
composer require matheushasm/swoole-micro

```

Local development (path repository)

In your app composer.json:

```
{
  "repositories": [
    {
      "type": "path",
      "url": "../swoole-micro",
      "options": { "symlink": true }
    }
  ],
  "require": {
    "matheushasm/swoole-micro": "*"
  }
}

```

Then:

```
composer update matheushasm/swoole-micro

```

Platform setup

Windows (requires WSL2 for Swoole):

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

```
sudo apt update
sudo apt install -y php-cli php-dev php-pear php-curl php-mbstring php-xml pkg-config redis-server
sudo pecl install swoole redis
echo "extension=swoole" | sudo tee /etc/php/8.2/cli/conf.d/20-swoole.ini
echo "extension=redis" | sudo tee /etc/php/8.2/cli/conf.d/20-redis.ini

```

Mac (Homebrew):

```
brew install php@8.4 pkg-config pcre2
brew install redis
pecl install swoole redis
echo "extension=swoole" > /opt/homebrew/etc/php/8.4/conf.d/ext-swoole.ini
echo "extension=redis" > /opt/homebrew/etc/php/8.4/conf.d/ext-redis.ini
brew services restart php

```

Linux (Ubuntu/Debian):

```
sudo apt update
sudo apt install -y php-cli php-dev php-pear php-curl php-mbstring php-xml pkg-config redis-server
sudo pecl install swoole redis
echo "extension=swoole" | sudo tee /etc/php/8.2/cli/conf.d/20-swoole.ini
echo "extension=redis" | sudo tee /etc/php/8.2/cli/conf.d/20-redis.ini

```

Docker (example):

```
FROM php:8.2-cli

RUN apt-get update && apt-get install -y \\
    git unzip pkg-config libssl-dev libcurl4-openssl-dev \\
    libbrotli-dev libzstd-dev libpcre2-dev \\
    && pecl install swoole redis \\
    && docker-php-ext-enable swoole redis

WORKDIR /app
COPY . /app
RUN composer install

CMD [\"php\", \"bin/swoole-micro\", \"worker:run\", \"default\"]
```

Quick start
-----------

[](#quick-start)

Create config/workers.php:

```