Getting Started

phpClaw is one Composer package. Install it, set an API key, and send a message. It works with or without a framework.

---

Requirements

Requirement	Version
PHP	8.1 or later
Extensions	curl, json, mbstring
A model	an API key for Anthropic, OpenAI, Groq, Gemini, Mistral or DeepSeek, or a local Ollama

ext-intl is optional and widens the look-alike character check in the guards. ext-redis is needed only for Redis memory.

Install

composer require phpclaw/phpclaw

Core has no Composer dependencies beyond PHP and the three extensions.

Set an API key

phpClaw picks the provider from whichever key it finds first:

export ANTHROPIC_API_KEY=sk-ant-...
# or OPENAI_API_KEY, GROQ_API_KEY, GEMINI_API_KEY, MISTRAL_API_KEY, DEEPSEEK_API_KEY
# or OLLAMA_HOST=http://localhost:11434

When several are set, the order is Anthropic, OpenAI, Groq, Gemini, Mistral, DeepSeek, then Ollama. PHPCLAW_PROVIDER wins over that order, even when a key for another provider is set:

export PHPCLAW_PROVIDER=ollama   # uses Ollama even if ANTHROPIC_API_KEY is also set

See Providers.

No API key? Use Ollama

Ollama runs models on your own machine. Install it, then pull phpClaw’s default Ollama model:

ollama pull qwen2.5:7b
export OLLAMA_HOST=http://localhost:11434

---

Your first message

require 'vendor/autoload.php';

use PhpClaw\Claw;

$agent    = Claw::builder()->build();
$response = $agent->send('Explain what a PHP trait is in two sentences.');

echo $response->text;

A plain builder registers no tools. The agent can answer from what the model knows, but it cannot look at your server, files or database until you give it tools. The next section does that.

---

Add tools

Tools let the agent take real actions: run shell commands, make HTTP calls, read files and query databases.

use PhpClaw\Claw;
use PhpClaw\Tools\HttpTool;
use PhpClaw\Tools\ShellTool;

$agent = Claw::builder()
    ->tools([
        new ShellTool(allowlist: ['df', 'uptime', 'date']),
        new HttpTool,
    ])
    ->build();

echo $agent->send('How much disk space is free, and how long has the server been up?')->text;

Now the agent can run df and uptime and answer from their output. The model decides which of the registered tools to call, and when.

Each built-in tool enforces its own limits: the shell accepts only allowlisted commands, HTTP refuses private addresses, and the file tools stay inside a workspace. See Tools and Security.

To query a database, pass a PDO connection. Only single read-only SELECT or WITH queries are accepted:

use PhpClaw\Tools\DatabaseQueryTool;

$agent = Claw::builder()->tools([new DatabaseQueryTool($pdo)])->build();

---

Stream the answer

Streaming is useful for command-line output and Server-Sent Events.

$agent->stream('Write a deployment checklist for a PHP app', function (string $token): void {
    echo $token;
    flush();
});

Tokens arrive as the model produces them when the agent has no tools. With tools registered, the answer is delivered in pieces after it is complete. See Providers: streaming.

---

Keep a conversation

use PhpClaw\Claw;
use PhpClaw\Memory\FileMemory;

$agent = Claw::builder()->memory(new FileMemory)->build();

$turn1 = $agent->sendInConversation($agent->conversation(), 'My name is Alice.');
$turn2 = $agent->sendInConversation($turn1->conversation, 'What is my name?');

echo $turn2->response->text;

Passing $turn1->conversation carries the history forward in the same process, even without memory. Memory is what lets you reopen a conversation later by its id, for example on the next request.

FileMemory writes to storage/phpclaw/memory under the current working directory. For anything beyond a script, set storageDir or use another driver. See Memory.

---

Choose a provider or model

$agent = Claw::builder()
    ->provider('openai')
    ->model('gpt-4o')
    ->build();

Or with environment variables:

PHPCLAW_PROVIDER=openai
PHPCLAW_MODEL=gpt-4o

---

Read the response

send() returns an AgentResponse:

$response = $agent->send('...');

$response->text;
$response->provider;
$response->model;
$response->iterations;     // agent loop iterations in this run
$response->durationMs;
$response->inputTokens;    // null when the provider reports no usage
$response->outputTokens;
$response->totalTokens();
$response->toolsCalled;

iterations, durationMs and the token counts are useful for watching cost and speed in production.

---

Using a framework or CMS

The adapters wire phpClaw into the platform: its database for memory, its permissions, its CLI, and platform-specific tools. An adapter installs core for you.

Platform	Install
Laravel 10 to 13	composer require phpclaw/phpclaw-laravel
Symfony 6.4, 7, 8	composer require phpclaw/phpclaw-symfony
Drupal 10, 11	composer require phpclaw/phpclaw-drupal
Magento 2	composer require phpclaw/phpclaw-magento
WordPress	upload the plugin ZIP in the admin
Joomla	upload the package ZIP in the admin
OpenCart	upload the extension ZIP in the admin
PrestaShop	upload the module ZIP in the admin

From the command line:

php artisan phpclaw "summarise today's failed jobs"     # Laravel
bin/console phpclaw "summarise today's failed jobs"      # Symfony

See All Adapters.

---

Next

• Architecture: what happens inside send()
• Tools: the built-in tools and writing your own
• Memory: conversations, storage and memory drivers
• Security: what each protection covers, and what it does not
• Providers: providers, models, prompt caching and web search