AMPHP v3 Skill

Version

This skill covers AMPHP v3 only — amphp/amp ^3, revolt/event-loop ^1, PHP 8.1+.

If you see v2 patterns (yield $promise, AmpLoop::run(), Promise, Coroutine), treat them as wrong and rewrite using v3 equivalents. See docs/v2-v3.md for the full migration table.

Non-Negotiable Rules

These apply to every file you write or modify in an AMPHP project:

Always add declare(strict_types=1) at the top of every PHP file.
Always pass JSON_THROW_ON_ERROR to every json_encode / json_decode call.
Never use blocking I/O (file_get_contents, PDO, curl_exec, sleep) inside the event loop — use async equivalents from amphp/file, amphp/mysql, amphp/http-client, Ampdelay().
Always release mutex/semaphore locks in a finally block — exceptions skip cleanup otherwise.
Always buffer() or fully iterate HTTP response bodies — unread bodies block connection reuse.

For the full list of 19+ documented gotchas (buffer deadlocks, channel EOF, arrow function capture, Redis factory vs constructor, etc.), read docs/common-mistakes.md before writing async code.

Reference Files

Load only the file(s) relevant to the task. Do not load all files at once.

Docs

File	When to load
`docs/constructors.md`	Instantiating any AMPHP class — verified constructor signatures, param names, defaults, and factory methods
`docs/namespaces.md`	Writing `use` imports — complete namespace paths for every class, function, and enum
`docs/packages.md`	Starting a new project or adding a dependency — `composer require` commands and package overview
`docs/common-mistakes.md`	Before writing any async code — 19+ real bugs with wrong/correct examples
`docs/v2-v3.md`	Migrating from AMPHP v2 or encountering `yield`/`Promise`/`Coroutine` patterns

Examples

File	When to load
`examples/core-async.md`	EventLoop bootstrap, `async()`, `delay()`, Future combinators (`await`, `awaitAll`, `awaitAny`), `DeferredFuture`
`examples/cancellation.md`	`TimeoutCancellation`, `DeferredCancellation`, `CompositeCancellation`, propagating cancellation
`examples/sync.md`	`LocalMutex`, `LocalSemaphore`, `LocalParcel`, `Barrier`, `LocalKeyedMutex`, `RateLimitingSemaphore`, `synchronized()`
`examples/http-server.md`	Minimal server, Router with route params, Middleware stack, TLS, Sessions, Static files, proxy setup
`examples/http-client.md`	GET/POST, parallel requests, `ConnectionLimitingPool`, interceptors, proxy, streaming response body
`examples/websocket.md`	Echo server, push-only with drain pattern, broadcast gateway, WS client, streaming binary messages
`examples/byte-stream.md`	`ReadableBuffer`, `pipe()`, GZIP compress/decompress, Base64 encode/decode, `splitLines()`
`examples/pipelines.md`	`Queue` back-pressure, `Pipeline` operators (`map`, `filter`, `tap`), `concurrent()`, `merge()`, `concat()`
`examples/parallel.md`	`Task` interface, fan-out with worker pool, IPC Channel progress reporting, `ChannelException` handling
`examples/database.md`	MySQL connection pool, transactions, prepared statements; Redis get/set/hash/pubsub/cache
`examples/file-io.md`	`Fileread/write/exists/getSize/openFile/listFiles/deleteDirectory/createDirectoryRecursively`
`examples/cache.md`	`LocalCache` (LRU + TTL), `AtomicCache` (compute-if-absent), `PrefixCache`, `NullCache`
`examples/interval.md`	`Interval` repeating timer, `enable/disable`, `weakClosure()` to prevent GC cycles, `EventLoop::delay/repeat/cancel`
`examples/testing.md`	`AsyncTestCase`, constructing mock `Request` objects, `LeagueUriHttp::new()`, phpunit CLI flags

Workflows

File	When to load
`workflows/http-server-full.md`	Building a complete HTTP server from scratch: Router + Middleware + Static files + WebSocket + graceful shutdown
`workflows/parallel-fan-out.md`	CPU-bound workload split across multiple worker processes with IPC progress reporting
`workflows/tcp-server.md`	Raw TCP server: echo, custom binary protocol, TLS mutual auth, graceful shutdown

Templates

File	When to load
`templates/http-server.php`	Copy-paste boilerplate for a full HTTP server (Router + Middleware + Static files + graceful shutdown)
`templates/websocket-handler.php`	Copy-paste boilerplate for WebSocket handlers: echo, push-only, broadcast gateway
`templates/parallel-task.php`	Copy-paste boilerplate for a worker `Task` class with IPC progress + fan-out orchestration

Scripts

File	Usage
`scripts/server-demo.php`	`php scripts/server-demo.php [--port=N]` — run a minimal HTTP server to verify setup
`scripts/http-client-demo.php`	`php scripts/http-client-demo.php [url]` — demo GET, parallel requests, ConnectionLimitingPool

Resources

File	When to load
`resources/blocking-vs-async.md`	Quick lookup: mapping every common blocking PHP function to its AMPHP v3 async replacement

Legacy

File	Contents
`references/advanced-patterns.md`	Deep dives: fiber model internals, all Future combinators, Queue back-pressure mechanics, Pipeline concurrency, Cancellation semantics, EventLoop timer details
`references/class-examples.md`	One minimal usage example per key AMPHP class, organized by package