home / skills / hoangnguyen0403 / agent-skills-standard / concurrency

concurrency skill

safe

/skills/php/concurrency

This skill helps you implement PHP concurrency using fibers and async libraries to improve I/O responsiveness.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill concurrency

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.1 KB

---
name: PHP Concurrency
description: Handling concurrency and non-blocking I/O in modern PHP.
metadata:
  labels: [php, concurrency, fibers, async]
  triggers:
    files: ['**/*.php']
    keywords: [Fiber, suspend, resume, non-blocking, async]
---

# PHP Concurrency

## **Priority: P2 (MEDIUM)**

## Structure

```text
src/
└── Async/
    ├── Schedulers/
    └── Clients/
```

## Implementation Guidelines

- **Fibers**: Use `Fiber` for low-level cooperative multitasking (8.1+).
- **Yield Control**: Apply `Fiber::suspend()` to yield within Fibers.
- **I/O Bound**: Target I/O tasks only; avoid for CPU intensive work.
- **Frameworks**: Prefer **Amp** or **ReactPHP** for complex events.
- **Self-Contained**: Ensure Fibers manage their own state/exceptions.
- **Incremental**: Refactor single bottlenecks before full async.

## Anti-Patterns

- **Implicit Flows**: **No Deep Suspend**: Keep Fiber logic traceable.
- **Internal Blocking**: **No Blocking I/O**: Don't block inside Fibers.
- **Custom Schedulers**: **No DIY Schedulers**: Use proven async libs.

## References

- [Fiber Implementation Guide](references/implementation.md)

Overview

This skill provides practical guidance for handling concurrency and non-blocking I/O in modern PHP. It focuses on using Fibers for cooperative multitasking and recommends established async libraries for complex event-driven work. The goal is safe, incremental adoption that targets I/O-bound bottlenecks without introducing hidden blocking or custom scheduler complexity.

How this skill works

The skill inspects code structure and offers patterns for organizing async components under an Async/ directory with Schedulers and Clients. It advocates using PHP Fibers (8.1+) for low-level cooperative multitasking and shows when to yield control with Fiber::suspend(). For more advanced or production-grade event loops, it recommends integrating Amp or ReactPHP rather than building custom schedulers.

When to use it

When you have I/O-bound tasks that block request latency (HTTP calls, DB access, network I/O).
When upgrading a synchronous PHP process incrementally to improve throughput.
When you need cooperative multitasking within a single thread without spawning OS threads.
When you must avoid full event-loop complexity for small, traceable async flows.
When debugging or refactoring bottlenecks before committing to a full async architecture.

Best practices

Use Fibers for cooperative control flow, but keep logic focused on I/O-bound operations, not CPU-heavy work.
Yield explicitly with Fiber::suspend() so control flow remains traceable and debuggable.
Keep Fibers self-contained: manage state and exceptions inside the Fiber to avoid cross-cutting side effects.
Prefer well-tested libraries like Amp or ReactPHP for scheduling, timers, and complex concurrency patterns.
Refactor incrementally: target one bottleneck at a time instead of rewriting the entire codebase.
Avoid implementing custom schedulers or mixing blocking calls inside Fibers; that creates subtle deadlocks.

Example use cases

Converting a blocking HTTP client to a non-blocking client using Fibers and an async runtime.
Running multiple parallel API queries and aggregating results without spawning worker processes.
Improving latency of background jobs that perform many remote calls by refactoring hot paths to async I/O.
Integrating ReactPHP or Amp to manage timers, streams, and event-driven socket I/O in a web service.

FAQ

Can I use Fibers for CPU-bound tasks?

No. Fibers provide cooperative multitasking but do not parallelize CPU work. Use process or thread-based approaches for CPU-heavy workloads.

Should I write my own scheduler?

Avoid DIY schedulers. Use proven libraries like Amp or ReactPHP to handle scheduling, backpressure, and event-loop correctness.

How do I prevent blocking inside a Fiber?

Replace blocking calls with non-blocking equivalents offered by your async library, and never call blocking I/O directly from within a Fiber.