PHPackages kevariable/phpclaw-laravel - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. kevariable/phpclaw-laravel ActiveLibrary[Utility & Helpers](/categories/utility) kevariable/phpclaw-laravel ========================== Role-routed, tool-using AI agent platform for Laravel that works with any LLM (Laravel AI SDK, Prism, or your own driver). v0.1.2(1mo ago)1616[2 PRs](https://github.com/kevariable/phpclaw-laravel/pulls)MITPHPPHP ^8.3CI passing Since Jun 19Pushed 1w agoCompare [ Source](https://github.com/kevariable/phpclaw-laravel)[ Packagist](https://packagist.org/packages/kevariable/phpclaw-laravel)[ Docs](https://github.com/kevariable/phpclaw-laravel)[ GitHub Sponsors](https://github.com/kevariable)[ RSS](/packages/kevariable-phpclaw-laravel/feed)WikiDiscussions main Synced 2w ago READMEChangelogDependencies (15)Versions (2)Used By (0) [![PHPClaw for Laravel logo](art/logo.png)](art/logo.png) PHPClaw for Laravel =================== [](#phpclaw-for-laravel) [![Latest Version on Packagist](https://camo.githubusercontent.com/5f01c86238998442423ee6807eed5b0c93f30cb2809dc14a583e0a616f545ddc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6b657661726961626c652f706870636c61772d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/kevariable/phpclaw-laravel)[![run-tests](https://github.com/kevariable/phpclaw-laravel/actions/workflows/run-tests.yml/badge.svg)](https://github.com/kevariable/phpclaw-laravel/actions/workflows/run-tests.yml)[![PHPStan](https://github.com/kevariable/phpclaw-laravel/actions/workflows/phpstan.yml/badge.svg)](https://github.com/kevariable/phpclaw-laravel/actions/workflows/phpstan.yml) A role-routed, tool-using AI agent platform for Laravel — **model-agnostic**. The core depends on a small `LlmDriver` port, so it works with any LLM: the [Laravel AI SDK](https://github.com/laravel/ai) (OpenAI, Anthropic, Gemini, Bedrock, …), [Prism](https://github.com/prism-php/prism), or your own driver. Inspired by [PHPClaw](https://github.com/vilanobeachflorida/phpclaw), rebuilt the Laravel way: SOLID, CQRS, and a driver port so the whole agent layer is testable without ever calling a model. Full docs in [docs/](docs/): [architecture](docs/architecture.md) · [routing](docs/routing.md) · [tools](docs/tools.md) · [modules](docs/modules.md) · [sessions](docs/sessions.md) · [memory](docs/memory.md) · [tasks](docs/tasks.md) · [REST API](docs/api.md) · [commands](docs/commands.md) · [browser control](docs/browser.md) · [development](docs/development.md). What it gives you ----------------- [](#what-it-gives-you) - **Role-based model routing with fallback** — a role maps to a primary model and an ordered fallback chain; the runner fails over when a model errors or rate-limits. - **Tools** — 14 shipped (calculator, http, filesystem-read, grep, system/project/code analysis, memory) handed to the model via the Laravel AI SDK's function-calling. Add your own by implementing one interface. - **Modules / tool-router** — per-task tool whitelists (`reasoning`, `coding`, `research`, …) bundling a role + the tools that task may use. - **Sessions** — persisted chat transcripts that carry context across turns. - **Memory** — long-term notes the agent can write and recall, with compaction. - **Queued tasks** — run the agent in the background on Laravel's queue. - **REST API** — a token-guarded `POST /phpclaw/chat` endpoint. - **Browser control** — a bundled (TypeScript) Chrome extension lets the agent drive a real browser. - **Dangerous tools, guarded** — `shell_exec` / `file_write` / `delete_file` ship behind a static prohibition guard (like `DB::prohibitDestructiveCommands()`). - **CQRS bus** — every action is a `Command`/`Query` dispatched to a dedicated handler. - **A driver port (`LlmDriver`)** — the core depends on an interface; `laravel/ai` is one (optional) driver, so the whole stack is unit-tested with a fake driver. Installation ------------ [](#installation) ``` composer require kevariable/phpclaw-laravel php artisan vendor:publish --tag="phpclaw-laravel-config" ``` ### Pick an LLM provider [](#pick-an-llm-provider) Roles point at a `provider` + `model`, driven by env (defaults shown): ``` PHPCLAW_PROVIDER=gemini # any provider your driver supports (openai, anthropic, gemini, ollama, …) PHPCLAW_MODEL=gemini-2.5-flash PHPCLAW_FAST_MODEL=gemini-2.5-flash-lite PHPCLAW_PRO_MODEL=gemini-2.5-pro PHPCLAW_API_TOKEN=a-long-random-string # for the REST API PHPCLAW_BROWSER_TOKEN=a-long-random-string # for the browser extension ``` Then choose how the package talks to that provider — it ships with the `LlmDriver` port and three ways to fill it: 1. **Laravel AI SDK** (default driver) — `composer require laravel/ai` (Laravel 12.62+ / 13), configure its provider. Supports OpenAI, Anthropic, Gemini, Bedrock, and more. 2. **Prism** — if your app already uses [Prism](https://github.com/prism-php/prism), bind a tiny Prism driver (see [docs/drivers.md](docs/drivers.md)). 3. **Your own** — implement `Kevariable\PhpclawLaravel\Contracts\LlmDriver` and bind it. ``` // Bring your own driver: $this->app->singleton(\Kevariable\PhpclawLaravel\Contracts\LlmDriver::class, MyDriver::class); ``` Usage ----- [](#usage) ``` use Kevariable\PhpclawLaravel\Facades\Phpclaw; use Kevariable\PhpclawLaravel\Tools\CalculatorTool; // Run by role $result = Phpclaw::run('reasoning', 'What is 19 * 23?', tools: [new CalculatorTool]); echo $result->text; // model output echo $result->model; // the model that actually answered (after any fallback) // Run by module (uses the module's role + its tool whitelist) Phpclaw::runModule('coding', 'Find where the bus is bound and explain it.'); // Inspect configuration Phpclaw::roles(); // list Phpclaw::tools(); // list Phpclaw::modules(); // list ``` ### Roles & modules [](#roles--modules) `config/phpclaw.php`: ``` 'roles' => [ 'reasoning' => [ 'provider' => 'gemini', 'model' => 'gemini-2.5-flash', 'timeout' => 120, 'fallback' => [['provider' => 'gemini', 'model' => 'gemini-2.5-flash-lite']], ], ], 'modules' => [ 'coding' => ['role' => 'coding', 'tools' => ['file_read', 'dir_list', 'grep_search', 'code_symbols']], ], ``` ### Custom tools [](#custom-tools) Implement `Kevariable\PhpclawLaravel\Contracts\Tool` and add the class to `phpclaw.tools` (or scaffold one with `php artisan make:phpclaw-tool WeatherTool`): ``` class WeatherTool implements Tool { public function name(): string { return 'weather'; } public function description(): string { return 'Get the weather for a city.'; } public function parameters(): array { return ['city' => ['type' => 'string', 'description' => 'City name.', 'required' => true]]; } public function run(array $arguments): string { return "Sunny in {$arguments['city']}."; } } ``` ### Dangerous tools [](#dangerous-tools) `shell_exec`, `file_write`, `file_append`, `delete_file`, `mkdir`, `move_file`, and `db_query` are shipped but **prohibited by default** — every call is gated like Laravel's `DB::prohibitDestructiveCommands()`. Opt in when you trust the environment: ``` use Kevariable\PhpclawLaravel\DangerousTools; DangerousTools::allow(); // enable (off by default) — any dangerous tool works DangerousTools::prohibit(); // re-lock; calls throw DangerousToolsProhibitedException // or via the facade: Phpclaw::prohibitDangerousTools(); ``` ### Sessions, memory & queued tasks [](#sessions-memory--queued-tasks) ``` Phpclaw::run('reasoning', 'long job…'); // synchronous // Background (queued) — see docs/tasks.md php artisan phpclaw:run reasoning "long job…" --queue ``` Artisan commands ---------------- [](#artisan-commands) CommandPurpose`phpclaw:run {role} {prompt}`One-shot generation (`--queue` to background it)`phpclaw:chat`Interactive REPL (`--role`, `--module`, `--session`)`phpclaw:roles` / `:providers` / `:models`Inspect roles, providers, models`phpclaw:tools` / `:tools:test`List / smoke-test tools`phpclaw:modules`List modules`phpclaw:status`Config summary`phpclaw:sessions` / `:session:show {id}`Chat sessions`phpclaw:memory:show` / `:memory:compact`Long-term memory`phpclaw:tasks` / `:task:show {id}`Queued tasks`make:phpclaw-tool {name}`Generate a tool stubSee [docs/commands.md](docs/commands.md) for the full reference. REST API -------- [](#rest-api) ``` curl -X POST http://localhost:8000/phpclaw/chat \ -H "Authorization: Bearer $PHPCLAW_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"prompt":"Explain CQRS in one sentence.","module":"reasoning"}' # => {"response":"…","model":"gemini-2.5-flash"} ``` See [docs/api.md](docs/api.md). Browser control --------------- [](#browser-control) A bundled TypeScript Chrome extension lets the agent drive a real browser. Publish the built extension, load it unpacked, and add the `BrowserControlTool`: ``` php artisan vendor:publish --tag="phpclaw-extension" # -> base_path('phpclaw-extension') ``` See [docs/browser.md](docs/browser.md) for the full setup and the extension's TypeScript build. Testing ------- [](#testing) Targets PHP 8.4 (Laravel 13 pulls Symfony 8, which needs PHP >= 8.4.1). The bundled Docker image pins it: ``` make build # build the PHP 8.4 image make test # Pest suite make coverage # coverage (100%) make analyse # PHPStan (level 5 + Larastan) make format # Pint ``` Natively, with PHP 8.4: `composer test` / `composer analyse` / `composer format`. See [docs/development.md](docs/development.md). License ------- [](#license) The MIT License (MIT). See [License File](LICENSE.md). ### Health Score 43 — FairBetter than 89% of packages Maintenance95 Actively maintained with recent releases Popularity21 Limited adoption so far Community9 Small or concentrated contributor base Maturity38 Early-stage or recently created project Bus Factor1 Top contributor holds 93.9% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 45d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/56016477?v=4)[Kevin](/maintainers/kevariable)[@kevariable](https://github.com/kevariable) --- Top Contributors [![kevariable](https://avatars.githubusercontent.com/u/56016477?v=4)](https://github.com/kevariable "kevariable (31 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (1 commits)") --- Tags laravelaiAgentkevariablephpclaw ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/kevariable-phpclaw-laravel/health.svg) ``` [![Health](https://phpackages.com/badges/kevariable-phpclaw-laravel/health.svg)](https://phpackages.com/packages/kevariable-phpclaw-laravel) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3355.4M352](/packages/psalm-plugin-laravel)[laravel/mcp Rapidly build MCP servers for your Laravel applications. 78727.1M205](/packages/laravel-mcp)[defstudio/telegraph A laravel facade to interact with Telegram Bots 817336.8k3](/packages/defstudio-telegraph)[nativephp/mobile NativePHP for Mobile 1.1k102.1k123](/packages/nativephp-mobile)[harris21/laravel-fuse Circuit breaker for Laravel queue jobs. Protect your workers from cascading failures. 24773.9k](/packages/harris21-laravel-fuse)[simplestats-io/laravel-client Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof. 5222.6k](/packages/simplestats-io-laravel-client) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)