Module:
Ws\Http\Plugin—PluginRegistry; contract:Ws\Http\Contract\PluginInterface,PluginContext,AuthProviderInterface; built-ins:Plugin\OpenAI\*,Plugin\WordPress\*
The plugin layer adapts third-party HTTP services into ergonomic, semantic PHP clients. A plugin is a three-piece pattern:
- Auth provider (
AuthProviderInterface) — knows how to seal credentials intoRequestOptions(e.g. Bearer header, Application Password); - Endpoints — URL-scoped operation objects (e.g.
chat(),posts()); - Semantic methods — the public surface users actually call (
$client->chat()->create('hi')).
Registration is minimal by design: a registry + an interface — no container, no events, no auto-discovery. Plugins can also contribute cross-cutting extensions (auth providers, comparison operators, extraction sources) through PluginContext.
interface PluginInterface
{
public function name(): string;
public function register(PluginContext $ctx): void;
}
interface PluginContext
{
public function addAuth(string $name, AuthProviderInterface $provider): void;
public function addComparator(string $op, ComparatorInterface $impl): void; // assertion operators
public function addExtractor(string $source, ExtractorInterface $impl): void; // extraction sources
public function share(string $key, object $service): void; // shared services
public function authProviders(): array;
public function services(): array;
}$registry = new PluginRegistry();
$registry->register(new OpenAIPlugin()); // duplicate name → InvalidArgumentException (501)
$registry->register(new WordPressPlugin());final class OpenAI\Client
{
public function __construct(string $apiKey, ?Request $http = null, string $baseUrl = self::DEFAULT_BASE_URL)
public function chat(): ChatEndpoint // POST /chat/completions
public function models(): ModelsEndpoint // GET /models
public function options(): RequestOptions // Bearer-sealed options
public function baseUrl(): string
}
final class ChatEndpoint
{
/**
* @param string|array $prompt string shorthand or full messages array
* @param array<string, mixed> $extra extra payload keys (temperature, tools, ...)
*/
public function create($prompt, string $model = 'gpt-3.5-turbo', array $extra = []): Response;
}Works with any OpenAI-protocol-compatible service — change the base URL (OpenAI, DeepSeek, Qianfan, vLLM…).
final class WordPress\Client
{
public function __construct(string $siteUrl, string $appPassword, ?string $user = null, ?Request $http = null)
public function posts(): PostsEndpoint // create/list/update/delete
public function media(): MediaEndpoint // upload/list
}Authentication: Application Password (ApplicationPasswordAuthProvider).
Signatures verified against src/Ws/Http/Plugin/:
OpenAI
// ChatEndpoint (POST /chat/completions)
public function create($prompt, string $model = 'gpt-3.5-turbo', array $extra = []): Response;
// $prompt: string shorthand → [['role' => 'user', 'content' => $prompt]]
// $extra: payload keys merged at top level (temperature, max_tokens, tools, ...)
// ModelsEndpoint (GET /models)
public function list(): Response;WordPress
// PostsEndpoint
public function list(array $query = []): Response; // WP_Query args
public function get(int $id): Response;
public function create(string $title, string $content, string $status = 'draft'): Response;
public function update(int $id, array $fields): Response; // partial fields
public function delete(int $id): Response;
// MediaEndpoint
public function upload(string $filepath, array $extra = []): Response; // $extra: title 等 WP attachment 字段All endpoint methods return the core Response — JSON auto-decoding and Watcher assertions apply unchanged.
use Ws\Http\Plugin\OpenAI\Client;
$client = new Client($apiKey, null, 'https://api.deepseek.com/v1');
$response = $client->chat()->create(
'Reply with exactly one word: pong', // string shorthand → messages array
'deepseek-chat'
);
echo $response->body->choices[0]->message->content;
echo $response->body->usage->total_tokens;$response = $client->chat()->create(
[
['role' => 'system', 'content' => 'You are terse.'],
['role' => 'user', 'content' => 'Summarize HTTP status codes.'],
],
'gpt-4o-mini',
['temperature' => 0.2, 'max_tokens' => 256]
);use Ws\Http\Plugin\WordPress\Client;
$wp = new WordPress\Client('https://blog.example.com', $appPassword, 'admin');
$wp->posts()->create('Hello', 'First post body');
$wp->media()->upload('/tmp/photo.jpg', ['title' => 'My photo']);use Ws\Http\Contract\{PluginInterface, PluginContext};
final class WeChatPlugin implements PluginInterface
{
public function name(): string { return 'wechat'; }
public function register(PluginContext $ctx): void
{
$ctx->addAuth('wechat-sign', new WeChatSignAuthProvider()); // custom credential sealing
$ctx->share('client', new WeChatClient()); // semantic client for consumers
}
}- Plugins are configured through their constructors (keys, base URLs, injected
Request); there is no global plugin configuration file. - Note: plugin auth ↔ scenario
authfield interop ({"type": "plugin:wechat-sign"}) is reserved in design/17, not yet implemented.
- Depends on: core
Request/RequestOptions(all plugin clients are core consumers),Contract\*interfaces. - Depended on by:
NanoGpt\Transport\OpenAiCompatibleTransport(composesPlugin\OpenAI\Clientfor the agent transport layer — composition, not inheritance).
Design details: design/17-Plugin层设计.md.