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, Amp\Loop::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, Amp\delay().
• 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), INLINECODE38
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 | File\read/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, League\Uri\Http::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	INLINECODE96 — 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 |