Download the PHP package cesurapp/swoole-bundle without Composer

Symfony Swoole Bundle

Built-in Swoole http server, background jobs (Task), scheduled task (Cron) worker are available. Failed jobs are saved in the database to be retried. Each server has built-in background task worker. Scheduled tasks run simultaneously on all servers. It is not possible for tasks to run at the same time as locking is used.

Install

Required Symfony 8

Edit: public/index.php

Configuration:

Server Environment: .env

Server Commands

The running server keeps its master process id in var/swoole.pid. server:stop sends it SIGTERM and waits while the running requests end (up to max_wait_time), then kills a server still up.

Create Cron Job

You can use cron expression for scheduled tasks, or you can use predefined expressions.

Notes:

• One scheduler process starts the jobs on time and gives every run a process of its own: a slow or blocking job (a long query, say) holds up only its own run, never the other jobs
• A run's process lives as long as the run and opens its own connections; the job runs in a coroutine, like in any worker
• A job whose previous run is still going is not started again; that run is skipped
• TIMEOUT (default 1200 seconds) stops a run that takes longer; raise it for a longer job. The run's lock lasts TIMEOUT plus a minute, so no other server starts the job while it runs
• Stopping the server stops the runs in progress
• The job's constructor runs in the scheduler: open connections in __invoke(), never earlier

Create Task (Background Job or Queue)

Data passed to tasks must be serializable (string, int, bool, array). Objects cannot be serialized directly.

Create Task:

Dispatch Task:

Durable Task:

Swoole keeps its task queue in memory, so a task still queued or running when the server stops is lost. Pass durable: true for work that must survive a deploy or a crash. The task is written to the failed_task store before it is queued, and its row is deleted only once the task succeeds. FailedTaskCron runs it again after a failure (on the task_retry schedule) and after task_redeliver_timeout if its worker died.

• A durable task runs at least once, so make it idempotent.
• A durable task never runs inline in the caller. When it can't be queued right away it waits for FailedTaskCron. That happens when Swoole refuses it, when there is no server (a console command), or when the dispatch is inside an open database transaction, where a worker could not yet see its row.
• In sync mode (task_sync_mode, tests) it runs inline like any other task and writes no row.

Create Process Worker

Process Worker allows you to create continuously running tasks in a separate process when the server starts. It's ideal for Redis LISTEN, Postgres LISTEN, or similar continuous listening commands.

Features:

• Each process runs as a separate, server-managed Swoole Process (Server::addProcess)
• Automatic restart support when the process completes
• Configurable restart delay
• Enable/Disable support
• One running copy across instances (lock), with the other instances on standby as failover
• Can dispatch tasks like any worker

Configuration:

Or via environment variable:

Create Process Job:

Use ProcessInterface or extend AbstractProcessJob:

Postgres LISTEN Example:

One-Time Process (Without Restart):

Notes:

• Each process runs as a separate Swoole Process, isolated from each other
• Processes are registered with Server::addProcess: they start with the server, the server restarts one that exits or crashes, and TaskHandler::dispatch() works inside them
• One copy runs per job across all instances (the process_server_<FQCN> lock). The other instances' copies wait on standby and take over when that lock is released
• Use a PostgreSQL advisory lock for it: LOCK_DSN=postgresql+advisory://..., connected directly (PgBouncer's transaction pooling hands the lock's session to other clients, so two copies could run). It never expires, however long the job holds up its process, and drops with the process. With a store whose locks expire (Redis, a plain postgresql:// table) the lock lasts 60 seconds past its last refresh, so a job that blocks its process longer lets a standby copy start
• A stop releases the lock at once. Each copy checks its lock every 10 seconds; one that lost it (e.g. its database session dropped) stops and the server restarts it
• A copy that takes the lock over from another waits 15 seconds before starting the job, so the other has noticed a lost lock and stopped
• When RESTART=true, the job runs again after RESTART_DELAY seconds upon completion (an exception or error counts as completion)
• When RESTART=false, the finished process stays parked while the server runs: exiting would only have the server restart it and run the job again
• The job's constructor runs in the master process (to read ENABLE): open connections in __invoke(), never earlier
• Processes must implement ProcessInterface (or extend AbstractProcessJob)
• Automatically registered in Symfony DI container with lazy loading support

Requirements

• PHP >= 8.4
• Symfony 8+
• Swoole Extension
• POSIX Extension
• PCNTL Extension

License

MIT