How to Use phpClaw: The Beginner’s Guide (First Composer Install, the First Agent Call, Tools, and the Framework-Adapter Arc)

CodexFuse Team · 2026-11-02T16:53:05.761Z · 12 min read min read

phpClaw is the MIT-licensed PHP agent engine: one Composer package, one API key, one method call puts an AI agent inside your PHP app. This beginner’s guide covers install, providers, tools, the Laravel/WordPress adapter arc, and security guards.

Learning how to use phpClaw takes about an afternoon: one Composer install, one API key in your environment, and one method call — Claw::send() — puts a working AI agent inside your PHP application. This guide walks you through the first install, your first agent call, how the engine picks an LLM provider, the tools you can give it, the framework-adapter arc (Laravel, WordPress, and the rest), and the security guards that keep the agent from doing damage. If you are comfortable with Composer and have browsed the GitHub beginner guide, you have everything you need to follow along. If you searched how to use phpClaw and found only the vendor docs, this tutorial fills that gap — no independent walkthrough exists yet.

What Is phpClaw, Exactly?

phpClaw is an MIT-licensed AI agent runtime for PHP — a PHP agent framework that embeds an autonomous agent inside your own application process instead of shipping your work off to a chatbot service. You install one Composer package, point it at an LLM provider with a single API key, and call Claw::send(); the engine plans, calls tools, and returns an answer, all running on your own server with no managed runtime in the middle.

That "runs in your process" detail is the whole mental model. A chatbot API is a remote service you send prompts to. phpClaw is a library: the agent lives next to your database, your sessions, and your business logic, so it can read your live app data, run your shell commands, and hit your internal APIs. Everything below follows from that one idea.

The vendor's counts — 8 framework adapters, 8 LLM providers, 8 security guards — are the maker's own claims on phpclaw.ai, reported here as reported, not as independently tested fact. The project is young: its GitHub repository was created on 2026-07-09, and it launched publicly with a Show HN post on October 29, 2026.

phpClaw Tutorial: How Do You Install phpClaw and Send Your First Agent Call, Step by Step?

Here is the complete first-run flow, from empty directory to a working agent response. Every step is verified against the vendor's current documentation (phpclaw.ai and the GitHub README, fetched November 2, 2026).

1. Check your PHP version. phpClaw needs PHP 8.1 or newer (through 8.4), plus the ext-curl, ext-json, and ext-mbstring extensions. The core package ships zero framework dependencies, per the vendor.
2. Install the package. Run composer require phpclaw/phpclaw in your project. That is the entire installation.
3. Set one API key. Export ANTHROPIC_API_KEY (or an OpenAI, Groq, Gemini, Mistral, DeepSeek key, or OLLAMA_HOST for a local model). phpClaw auto-detects which provider you configured, in a fixed order — Anthropic first — so one key is all it takes to start.
4. Send your first agent call. In PHP:

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

5. Read the response object. The call returns an agent response carrying text plus provider, model, tokens, iterations, and duration_ms — so you always know what answered, on which model, and what it cost you in tokens.
6. Give it a tool (optional but where it gets fun). Register tools — shell commands, HTTP requests, database queries — and the engine will call them while answering, with the default approval gates asking before anything mutating runs.
7. Pick your path forward. Plain PHP script done? The framework adapters — Laravel, Symfony, WordPress, and five more — are the next section. Want the agent to work inside your editor instead? The MCP server package connects phpClaw to Claude Desktop, Claude Code, and Cursor.

How Does phpClaw Pick Which LLM Answers Your Request?

phpClaw auto-detects your provider from the environment: it checks for API keys in a fixed order — Anthropic, then OpenAI, Groq, Gemini, Mistral, DeepSeek, and finally an Ollama host — and uses the first one it finds. The vendor ships a default model per provider, and you can override both choices with the PHPCLAW_PROVIDER and PHPCLAW_MODEL environment variables.

The defaults table below is the vendor's own, verified on phpclaw.ai on November 2, 2026 — report it as the vendor's current configuration, not as a benchmarked fact:

The practical takeaway: set exactly one provider key while learning, so you know which model is answering. The response object's provider and model fields tell you the truth every call — check them rather than trusting your memory of the detection order.

Why Does a PHP Agent Framework Run Inside Your App?

Because proximity is the feature. An agent that runs in your PHP process can query your application's database directly, call your internal helper functions, and read files in your project — no API gateway, no webhook round-trip, no context re-upload. That is why phpClaw is a Composer library and not a hosted product: the engine has no managed runtime and charges no per-token markup, per the vendor's MIT-licensed pitch ("no paywall on the engine").

The tradeoff is honesty about: you run the infrastructure. Since the agent lives on your server, you also inherit the security responsibility — which is exactly why the vendor ships approval gates for mutating tools by default. Do not hand the agent shell access on production in step one; read the guards section first.

How to Use phpClaw with Laravel?

Install the Laravel adapter with composer require phpclaw/phpclaw-laravel, then run the agent from an Artisan command: php artisan phpclaw "hello". The adapter wires the engine into Laravel's service container, so the agent can use your application's config, database connections, and queued jobs like any other Laravel service.

Start with read-only tools — let the agent query your database and read logs — before you ever grant it write access. Laravel developers are used to gates and policies for users; treat your agent the same way, with phpClaw's own approval gates as the last line of defense, not the first.

How to Use phpClaw with WordPress, Symfony, and the Other Adapters?

phpClaw ships eight adapters, one per framework or platform: Laravel, Symfony, WordPress, Drupal, Joomla, Magento, PrestaShop, and OpenCart — plus a plain-PHP core for anything else. The pattern is the same everywhere: install the adapter package, and the engine gains framework-aware tools (routes, database, admin context) instead of generic ones.

WordPress users get the simplest path — no terminal, just a plugin upload in wp-admin — which is why phpclaw wordpress is a real search: yes, there is a WordPress adapter. The e-commerce platforms (Magento, PrestaShop, OpenCart) get an agent that can see products and orders natively. Since the agent runs on your own server, check your hosting plan first: a basic shared host may not give you the process control an always-on agent wants, which is where a small VPS hosting plan comes in.

How Do phpClaw's Security Guards Protect Your App?

The engine boots eight default guards on every run — via GuardRegistry::registerDefaults() — and gates mutating tool calls behind approvals unless you say otherwise. The guard list covers prompt injection (InjectionGuard, which the vendor says watches 11 attack patterns), Unicode and homoglyph tricks, role-switching attempts, PII exposure, code injection, destructive SQL, and over-long inputs. Partial guard names come from the README; the vendor's own pages do not name all eight, so treat the full roster as vendor-described.

The guards are a safety net, not a security policy. Keep doing the basics: run the agent with the least-privilege database user, keep approval gates on for anything that writes, and log every tool call the agent makes. An agent is a very capable intern — you still lock the office at night.

What Is the MCP Server For?

The phpclaw/phpclaw-mcp package turns your phpClaw app into a Model Context Protocol server — over stdio or Streamable HTTP — so outside agents can use it as a tool. The vendor says this exposes any phpClaw app to Claude Desktop, Claude Code, Cursor, Windsurf, and Zed, and that "phpClaw speaks JSON-RPC 2.0 out of the box." Those are vendor claims; the functional behavior was not independently verified for this guide.

The direction matters more than the protocol: instead of your PHP app calling the AI, your AI editor calls your PHP app. If you already pair-program with AI tooling, the Claude Code beginner guide is a natural companion — and if the MCP acronym itself is new, read what MCP is before wiring servers together.

phpClaw vs OpenClaw: What's the Difference?

They are different products that happen to share the word "Claw" — do not mix them up. phpClaw is an embeddable PHP agent engine: a Composer library that runs an agent inside your own PHP application against your live data. OpenClaw is a separate AI agent product in its own lane (a personal-agent runtime), with its own install story and its own documentation. They are never rivals on the same page, because they solve different problems at different layers.

Two more names to keep straight while searching: PyClaw (also styled Clawpack) is a Python scientific-computing package whose tutorials currently rank for "phpclaw tutorial" — different product, different universe. LaraClaw is a separate Laravel chatbot package built on laravel/ai that ranks for "phpclaw laravel" — also not this product. When a search result talks about Python simulations or laravel/ai chatbots, you have landed on the wrong Claw.

What Does the Project's Health Look Like in November 2026?

It looks like a genuine, early, fast-moving open-source launch — with all the caveats that implies. As of November 2, 2026: the GitHub repository (phpclaw-php/phpclaw) shows 6 stars, 0 forks, 32 commits, 6 tags, zero releases, and the 0.x branch; the repo is a read-only mirror auto-published from a private phpclaw-monorepo, so issues and pull requests live elsewhere. Date-stamp those numbers — they will move quickly.

The vendor's trust signals are vendor claims: 2,687 tests with 80% line coverage enforced in CI. One honest inconsistency to note: phpclaw.ai advertises "54 lifecycle events" while the GitHub README says "50 lifecycle hooks" — both figures are the vendor's own words on the vendor's own pages, and neither was independently counted for this guide.

What Are the Beginner Mistakes to Avoid with phpClaw?

Should You Learn phpClaw in 2026?

Yes, if you are a PHP developer who wants agents inside your own applications — and you should budget for a moving target. The field is wide open: no independent phpClaw tutorial exists yet, the vendor documentation is the whole canon, and the project has zero releases. What you learn now is the foundation, but expect the adapter list, provider defaults, and guard names to shift as the 0.x line matures.

The honest summary: phpClaw is the easiest way to give a PHP app an AI agent today — one package, one key, one method call — with MIT licensing and no engine fees. It is not yet a mature ecosystem, and the 6-star count says so plainly. Learn it for the pattern it teaches (agents that live in your process), and you will keep the lesson even if the package changes.

Sources

Every factual claim above traces to a page fetched on November 2, 2026:

1. phpclaw.ai — the vendor site: adapters, providers and their defaults, guards, install commands, the Claw::send() usage, license, and MCP/JSON-RPC claims (vendor claims, reported as reported).
2. github.com/phpclaw-php/phpclaw — the GitHub repository: created 2026-07-09, 6 stars, 0 forks, 32 commits, 6 tags, 0 releases, MIT license, read-only mirror note, 2,687-test and 80%-coverage trust signals (vendor claim).
3. theneuron.ai (November 1, 2026) — newsletter coverage: "phpClaw gives PHP developers an MIT-licensed agent runtime with tools, memory, and adapters for Laravel, Symfony, WordPress, Drupal, and Magento."
4. my2cents.ai/news/2026-10-30-open-source-agents/ (October 30, 2026) — open-source agent roundup listing phpClaw in the October launch wave.
5. zeli.app/story/50293361 — Show HN mirror for phpClaw's October 29, 2026 launch post.

Frequently Asked Questions

Is phpClaw free?

The engine is MIT-licensed with what the vendor calls "no paywall on the engine, no per-token markup, no usage fees." You still pay your LLM provider for the API calls the agent makes — phpClaw itself adds no charge on top.

Does phpClaw work with Laravel?

Yes — Laravel is one of the eight adapters. Install phpclaw/phpclaw-laravel and run the agent through php artisan phpclaw. The adapter wires the engine into Laravel's container so the agent can use your app's config and database connections.

Is phpClaw the same as OpenClaw?

No. phpClaw is an embeddable PHP agent engine (a Composer library running inside your PHP app); OpenClaw is a separate AI agent product. The shared word "Claw" is a coincidence — treat them as unrelated.

Which LLM does phpClaw use by default?

Whichever provider it finds first in its detection order (Anthropic before OpenAI before Groq, and so on), on that provider's vendor default — Anthropic's default is claude-haiku-4-5-20251001, per the vendor. Set one key to know exactly what is answering, or pin both choices with PHPCLAW_PROVIDER and PHPCLAW_MODEL.

Can I use phpClaw without an API key?

Yes, via Ollama: point OLLAMA_HOST at a local Ollama instance and the engine defaults to qwen2.5:7b. Your agent then runs entirely on your own hardware — the provider, the runtime, everything.