Description

Writing non-blocking, async PHP code using the AMPHP framework — revolt/event-loop, amphp/amp ^3, and the full amphp/* ecosystem (http-server, http-client, w...

README (SKILL.md)

AMPHP v3 Skill

Name: amphp
Author: rekryt

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`), `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`	`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`	`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

Usage Guidance

This skill is documentation/instruction-only and appears consistent with its stated purpose (teaching/generating AMPHP v3 code). Before installing, consider: (1) confirm you trust the skill source (README references a GitHub repo), (2) if you grant the agent Bash or Agent permissions, be aware it could run shell commands such as composer require or tests — only enable those tools if you want the agent to run commands in your environment, and (3) review any templates or example code you plan to run, and run composer commands yourself rather than letting an agent run them automatically if you have network/security concerns.

Capability Analysis

Type: OpenClaw Skill Name: amphp Version: 1.0.0 The amphp skill bundle is a comprehensive and well-structured resource designed to teach AI agents how to write non-blocking asynchronous PHP using the AMPHP v3 ecosystem. It contains extensive documentation, best practices, migration guides, and code examples across numerous files such as SKILL.md, docs/common-mistakes.md, and various files in the examples/ and workflows/ directories. While the skill grants the agent access to powerful tools like Bash, the instructions are strictly focused on legitimate development tasks like running PHP scripts and executing PHPUnit tests. No evidence of malicious intent, data exfiltration, or prompt injection was found.

Capability Assessment

✓ Purpose & Capability

The name/description (AMPHP v3 async PHP) match the provided SKILL.md, README, docs, examples and workflows. The skill does not request unrelated credentials, binaries, or config paths; the large set of docs/examples is appropriate for a coding-assistant skill of this scope.

ℹ Instruction Scope

SKILL.md focuses on editing/authoring PHP code and loading only the listed docs/templates. It does not instruct the agent to read system credentials or unrelated files. It does list allowed-tools including Bash and Agent (so the agent may run shell commands or call other agents) — this is reasonable for a coding helper (composer commands, running tests) but is broader than pure read/edit and worth being aware of.

✓ Install Mechanism

No install spec and no code files that execute on install — this is an instruction/doc-only skill. No downloads, formulas, or archive extraction are present.

✓ Credentials

The skill declares no required environment variables, credentials, or config paths. The content references composer require examples (normal for PHP) but does not demand secrets or unrelated service tokens.

✓ Persistence & Privilege

always:false and no requests to modify other skills or system-wide agent configuration. Model/agent invocation is allowed (platform default) but there are no additional privileged settings.

Version History

v1.0.0

Initial public release of the amphp skill for async PHP development. - Adds comprehensive skill for non-blocking, async PHP using AMPHP v3 (amphp/amp ^3, revolt/event-loop ^1). - Covers usage across the amphp/* ecosystem: HTTP/WS servers and clients, file, cache, pipeline, parallel, databases, and more. - Enforces best practices, including strict types, async I/O, and critical AMPHP safety rules. - Includes detailed reference for docs, examples, workflows, templates, and migration guides from v2. - Designed to match real-world async PHP needs, even when "amphp" is implied but not stated.

Metadata

Slug amphp

Version 1.0.0

License MIT-0

All-time Installs 0

Active Installs 0

Total Versions 1

Frequently Asked Questions

What is amphp?

Writing non-blocking, async PHP code using the AMPHP framework — revolt/event-loop, amphp/amp ^3, and the full amphp/* ecosystem (http-server, http-client, w... It is an AI Agent Skill for Claude Code / OpenClaw, with 246 downloads so far.

How do I install amphp?

Run "/install amphp" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is amphp free?

Yes, amphp is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does amphp support?

amphp is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created amphp?

It is built and maintained by Sergey Krupkin (@rekryt); the current version is v1.0.0.

More Skills

amphp