The universal AI agent engine for PHP.

Tools, memory, security, and a ReAct loop, already built. Zero framework dependencies in core. Any LLM provider.

Documentation · Adapters · Why phpClaw · Install · MCP · Security

First agent in seconds

composer require phpclaw/phpclaw
export ANTHROPIC_API_KEY="sk-ant-..."

$agent = PhpClaw\Claw::builder()->build();
echo $agent->send('What can you help me with?')->text;

One env var, one builder, one send(). The builder checks ANTHROPIC_API_KEY, then OPENAI_API_KEY, GROQ_API_KEY, GEMINI_API_KEY, MISTRAL_API_KEY, DEEPSEEK_API_KEY, OLLAMA_HOST, in that order, and uses whichever it finds first. No YAML, no agent framework to learn, no vendor lock-in.

Give your agent tools

An agent without tools can only talk. Register the ones your application needs and it starts doing real work:

use PhpClaw\Claw;
use PhpClaw\Tools\ShellTool;
use PhpClaw\Tools\HttpTool;
use PhpClaw\Tools\FileReadTool;
use PhpClaw\Tools\DatabaseQueryTool;
use PhpClaw\Tools\CodeSearchTool;

$agent = Claw::builder()
    ->tools([
        new ShellTool(allowlist: ['df', 'ps', 'tail']),
        new HttpTool(),
        new FileReadTool(),
        new DatabaseQueryTool($pdo),
        new CodeSearchTool(),
    ])
    ->build();

> Check disk usage and tail the last 20 lines of the error log
> Is api.example.com responding right now?
> Run a read-only SELECT to count today's orders
> Find every place UserService is used in this codebase

The agent decides which tools to call and in what order, running a ReAct loop (reason, act, observe, repeat) until it has an answer or hits the iteration cap. This works identically whether the tools touch your shell, your database, your HTTP APIs, or your codebase.

Why phpClaw

Every "AI in PHP" tutorial ends the same way: an HTTP client bolted onto a provider API, a hand-rolled tool-call loop, and a prayer that the prompt holds up in production. A generic LLM SDK gives you the API client. phpClaw gives you the agent runtime around it: the loop, the guards, the memory, the framework wiring, already assembled.

Not trying to be everything. phpClaw isn't built for complex RAG pipelines or multi-agent orchestration. It's built for one job: give an LLM tools, memory, and security controls against your real application, in an afternoon.

What phpClaw provides

Agent runtime. A ReAct loop with a hard iteration cap (max_iterations, default 20), pluggable tools, pluggable memory, and keyword-matched skills, all running inside a single reasoning cycle.

Provider flexibility. 7 providers auto-detected from environment variables: Anthropic, OpenAI, Groq, Gemini, Mistral, DeepSeek, Ollama. A custom OpenAI-compatible endpoint is also supported, opt-in via PHPCLAW_PROVIDER=custom. Switch providers with ->provider() and ->model(), no code changes elsewhere.

Production controls. 8 security guards on by default (prompt injection, PII, code injection, Unicode, homoglyph, role-switch, destructive SQL, message length), plus rate limiting available as an opt-in guard. Tool results are sanitised unconditionally by ToolOutputGuard, which sits outside the guard registry, and LLM output sanitisation is on by default and can be disabled with ->sanitiseOutput(false). ShellTool is allowlist-only with a hard-coded command blocklist that can't be overridden. HttpTool validates resolved IPs, not just hostnames, closing the DNS-rebinding gap a prefix blocklist alone would miss. FileReadTool/FileWriteTool are workspace-sandboxed and refuse sensitive paths and extensions.

Developer experience. Token-by-token streaming, prompt caching (cached input tokens billed at Anthropic's discounted cache-read rate, see Anthropic's pricing for the exact figure), and extended thinking (Claude's reasoning chain exposed on $response->thinking).

Ecosystem. 8 framework and CMS adapters, an MCP server for exposing your tools to Claude Desktop and Claude Code, and an optional cloud transport for a hosted, continuously-updated prompt-scan guard.

Framework & CMS adapters

Each adapter wires phpClaw into its host's own idioms: Eloquent for Laravel, Doctrine for Symfony, WP-CLI for WordPress, Drush for Drupal, and so on. Every adapter ships an admin chat or CLI and the same 3-table memory schema underneath.

CMS adapters ship as ZIP downloads from Releases, not Composer, because that's how their host platforms install extensions.

php artisan phpclaw "deploy staging and notify #ops"          # Laravel
bin/console phpclaw "check all database connections"          # Symfony
drush phpclaw:run "list recently-active users"                # Drupal
bin/magento phpclaw:run "check order-queue status"             # Magento
wp phpclaw send "summarise today's posts"                     # WordPress
php cli/joomla.php phpclaw "list recent articles"              # Joomla
php cli/phpclaw.php send "check low stock products"            # OpenCart
php modules/phpclaw/cli/phpclaw.php send "check stock levels"  # PrestaShop

Full per-adapter reference (tools, REST routes, CLI commands, settings, memory drivers) lives on the doc site. Each adapter's own README is a short pointer, not a manual. Building a new one? See the community adapter guides.

MCP Server

phpclaw/phpclaw-mcp exposes your existing ToolRegistry over the Model Context Protocol, so Claude Desktop, Claude Code, Cursor, or any MCP-compatible client can call your tools directly, with the same guard chain protecting every call. No changes to the tools themselves.

composer require phpclaw/phpclaw-mcp

Full quick start, transport, and security details: phpclaw.ai/docs/mcp.

Security

Every message runs through the default guard chain before it reaches the provider. ShellTool accepts only a caller-supplied allowlist; a fixed, non-overridable blocklist of dangerous commands is checked first regardless of what's allowlisted. HttpTool blocks requests by hostname prefix, then re-validates every resolved IP address, catching CGNAT and DNS-rebinding attempts that hostname checks alone would miss. FileReadTool and FileWriteTool are sandboxed to a configured workspace root and refuse credentials, keys, and framework-internal directories unconditionally.

Full guard reference, the exact ShellTool blocklist, and the SSRF/sandbox implementation details: phpclaw.ai/docs/security. Found a vulnerability? See SECURITY.md, do not open a public issue.

Architecture

Message
  → Guards       (blocks injection/PII before the LLM sees it)
  → Hooks         (lifecycle events fire, 40 across the loop)
  → Agent          (ReAct loop: provider + tools + memory + skills)
  → AgentResponse  (text, tokens, tool calls, timing)

Providers, tools, memory, guards, and skills are all pluggable via static registries; every adapter wires them from its own config or environment. Full architecture diagram and design rules: phpclaw.ai/docs/architecture.

Extensibility

Six pluggable static registries: ToolRegistry, GuardRegistry, HookRegistry, MemoryRegistry, ProviderRegistry, SkillRegistry. Drop a class in packages/core/src/<Subsystem>/ with the matching attribute (#[Tool], #[Provider], #[Memory], #[Skill], #[Hook], #[Guard]), run composer dump-autoload, it's live. Or register from code with ->register() on the relevant registry.

Full extension recipes with working code for every subsystem: phpclaw.ai/docs.

Testing

for pkg in core cloud mcp; do (cd packages/$pkg && composer test); done

Working on packages/core and testing through an adapter? Adapters consume the three libraries
as copied composer path repositories, not symlinks, and most composer commands will not refresh
that copy:

After editing packages/core, packages/cloud or packages/mcp, run composer sync-core in the
adapter you are testing, or you are testing a stale copy. The first install succeeding is what
makes the second one dangerous: the command appears to work, so nobody suspects it later.

Unit tests use mocks and stubs for HTTP clients, \Redis, and the filesystem: no external network calls and no API keys are needed to run the suite for core, cloud, or mcp. Coverage requirements and the full testing rules are in CONTRIBUTING.md.

Documentation

This README gets you installed. Everything else, architecture, the full provider/tool/guard/hook/memory/skill reference, per-adapter tool and REST tables, code examples, upgrading, troubleshooting, lives at:

phpclaw.ai/docs

• CONTRIBUTING.md · SECURITY.md

Requirements

• PHP: 8.1, 8.2, 8.3, 8.4
• Extensions: ext-curl, ext-json, ext-mbstring (core only; adapters may need more, documented per-package)

License

MIT, built with love for the PHP community. Part of the phpClaw project.