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 core for Laravel, powered by the Laravel AI SDK. 00PHPCI passing Since Jun 18Pushed todayCompare [ Source](https://github.com/kevariable/phpclaw-laravel)[ Packagist](https://packagist.org/packages/kevariable/phpclaw-laravel)[ RSS](/packages/kevariable-phpclaw-laravel/feed)WikiDiscussions main Synced today READMEChangelogDependenciesVersions (1)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, built on the [Laravel AI SDK](https://github.com/laravel/ai). 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" ``` For the built-in Gemini driver, also install the Laravel AI SDK (needs Laravel 12.62+ or 13) and set your key — or bind your own `LlmDriver` and skip it: ``` composer require laravel/ai ``` ``` GEMINI_API_KEY=your-key PHPCLAW_API_TOKEN=a-long-random-string # for the REST API PHPCLAW_BROWSER_TOKEN=a-long-random-string # for the browser extension ``` 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 20 — LowBetter than 13% of packages Maintenance65 Regular maintenance activity Popularity0 Limited adoption so far Community6 Small or concentrated contributor base Maturity11 Early-stage or recently created project Bus Factor1 Top contributor holds 100% 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. ### 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 (25 commits)") ### 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 [reinink/remember-query-strings Laravel middleware that automatically remembers and restores query strings. 76638.4k3](/packages/reinink-remember-query-strings)[nicmart/numbers Format numbers in various formats, like scientific notation or unit-suffix notation 54189.3k1](/packages/nicmart-numbers)[spatie/mjml-sidecar Compile MJML to HTML using Sidecar 1355.1k](/packages/spatie-mjml-sidecar) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)