PHPackages                             codechap/yii3-claude-code - 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. [CLI & Console](/categories/cli)
4. /
5. codechap/yii3-claude-code

ActiveLibrary[CLI & Console](/categories/cli)

codechap/yii3-claude-code
=========================

Yii3 wrapper for the Claude Code CLI with DI integration, multi-turn conversations, and immutable fluent API.

1.0.0(1mo ago)03↓100%MITPHPPHP 8.2 - 8.5

Since Mar 13Pushed 1mo agoCompare

[ Source](https://github.com/codeChap/yii3-claude-code)[ Packagist](https://packagist.org/packages/codechap/yii3-claude-code)[ RSS](/packages/codechap-yii3-claude-code/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (5)Versions (2)Used By (0)

Yii3 Claude Code
================

[](#yii3-claude-code)

A Yii3 wrapper for the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) with DI integration, immutable fluent API, and multi-turn conversation support.

Works on **Linux**, **macOS**, and **Windows**. Supports both **subscription** and **API key** authentication.

Requirements
------------

[](#requirements)

- PHP 8.2 - 8.5
- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and in your PATH (or configured via `binaryPath`)

Installation
------------

[](#installation)

```
composer require codechap/yii3-claude-code
```

Configuration is auto-loaded via Yii3's [config-plugin](https://github.com/yiisoft/config).

Quick start
-----------

[](#quick-start)

```
use Codechap\Yii3ClaudeCode\ClaudeCodeInterface;

final class MyController
{
    public function __construct(
        private readonly ClaudeCodeInterface $claude,
    ) {}

    public function actionAsk(): string
    {
        $response = $this->claude->query('What is the capital of France?');

        return $response->getResult();
    }
}
```

Authentication
--------------

[](#authentication)

### Subscription (default)

[](#subscription-default)

If you're logged in via `claude auth login`, no extra config is needed. The package unsets `ANTHROPIC_API_KEY` in the subprocess by default to prevent accidental API charges.

### API key

[](#api-key)

Set the API key in your params to use pay-as-you-go billing instead of a subscription:

```
// config/params.php
return [
    'codechap/yii3-claude-code' => [
        'apiKey' => 'sk-ant-...',
    ],
];
```

Or at runtime:

```
$response = $claude
    ->withApiKey('sk-ant-...')
    ->query('Hello');
```

When an API key is provided, it takes priority — the `ANTHROPIC_API_KEY` environment variable is set in the subprocess instead of being unset.

> **Note:** With an API key, you are billed per token (pay-as-you-go). With a subscription, usage is included in your monthly plan. Verify your auth method with `claude auth status`.

Configuration
-------------

[](#configuration)

Override defaults in your application's `config/params.php`:

```
return [
    'codechap/yii3-claude-code' => [
        // Path to the claude binary. Empty string = auto-detect via PATH.
        'binaryPath' => '',

        // Default model: 'sonnet', 'opus', or 'haiku'.
        'model' => 'sonnet',

        // Default system prompt sent with every query.
        'systemPrompt' => '',

        // Maximum number of agentic turns (null = unlimited).
        'maxTurns' => null,

        // Tools the CLI is allowed to use.
        'allowedTools' => [],

        // Process timeout in seconds.
        'timeout' => 300,

        // Environment variables to unset in the subprocess (recursion prevention).
        'envUnset' => ['CLAUDECODE', 'ANTHROPIC_API_KEY'],

        // Anthropic API key (null = use subscription auth).
        'apiKey' => null,

        // Custom environment variables passed to the subprocess.
        'envSet' => [],
    ],
];
```

Usage
-----

[](#usage)

All `with*` methods are **immutable** — they return a new instance, leaving the original unchanged.

### Model selection

[](#model-selection)

```
use Codechap\Yii3ClaudeCode\Model;

$response = $claude
    ->withModel(Model::Opus)
    ->query('Explain quantum computing');
```

### JSON mode

[](#json-mode)

```
$response = $claude
    ->withJson()
    ->query('List 3 colors as a JSON array');

$array = $response->toArray(); // Decoded JSON
```

### Multi-turn conversations

[](#multi-turn-conversations)

```
// Start a conversation
$r1 = $claude
    ->withJson()
    ->query('What is the capital of France?');

// Continue with session ID
$r2 = $claude
    ->withJson()
    ->withSessionId($r1->getSessionId())
    ->query('And Germany?');

// Or continue the most recent conversation
$r3 = $claude
    ->withContinue()
    ->query('What about Italy?');
```

### System prompts

[](#system-prompts)

```
$response = $claude
    ->withSystemPrompt('Reply in haiku form only.')
    ->query('Describe the ocean');
```

### Allowed tools

[](#allowed-tools)

```
$response = $claude
    ->withAllowedTools(['Read', 'Grep', 'Glob'])
    ->query('Find all TODO comments in this project');
```

### Working directory

[](#working-directory)

```
$response = $claude
    ->withWorkingDirectory('/path/to/project')
    ->query('Describe this codebase');
```

### Custom environment variables

[](#custom-environment-variables)

Useful when running under a web server where `$HOME` and `$PATH` differ from your shell:

```
$response = $claude
    ->withEnv([
        'HOME' => '/home/myuser',
        'PATH' => '/usr/local/bin:/usr/bin:/bin',
    ])
    ->query('Hello');
```

### Additional CLI flags

[](#additional-cli-flags)

Pass arbitrary flags to the `claude` binary that don't have a dedicated `with*` method. Three forms are supported:

```
// Boolean flag (no value)
$response = $claude
    ->withFlags(['--dangerously-skip-permissions'])
    ->query('Delete all temp files');

// Single-value flag
$response = $claude
    ->withFlags(['--effort' => 'high'])
    ->query('Refactor this module');

// Multi-value flag
$response = $claude
    ->withFlags(['--add-dir' => ['/data', '/config']])
    ->query('Analyze these directories');

// Mix all three forms
$response = $claude
    ->withFlags([
        '--dangerously-skip-permissions',
        '--effort' => 'high',
        '--add-dir' => ['/data', '/config'],
    ])
    ->query('Go wild');
```

These are appended after the built-in flags. Run `claude --help` to see all available flags.

### Timeout

[](#timeout)

```
$response = $claude
    ->withTimeout(600) // 10 minutes
    ->query('Refactor this entire module');
```

### Callback

[](#callback)

```
$claude->query('Hello', function (Response $response): void {
    logger()->info('Claude responded', [
        'session' => $response->getSessionId(),
        'elapsed' => $response->getElapsedSeconds(),
    ]);
});
```

Console command
---------------

[](#console-command)

Requires [`yiisoft/yii-console`](https://github.com/yiisoft/yii-console).

```
# Basic query
./yii claude:query "What is PHP?"

# With options
./yii claude:query "Explain this code" --model=opus --json
./yii claude:query "Continue our discussion" --continue
./yii claude:query "More details" --resume=session-id-here
./yii claude:query "Hello" --system-prompt="Be concise"
./yii claude:query "Hello" --api-key=sk-ant-...
```

Use `-v` for verbose output (session ID and elapsed time).

Response object
---------------

[](#response-object)

MethodReturnsDescription`getResult()``string`Extracted response text`getRawOutput()``string`Unprocessed CLI output`getSessionId()``?string`Session ID for multi-turn (JSON mode)`getElapsedSeconds()``float`Wall-clock time in seconds`isJson()``bool`Whether JSON mode was used`toArray()``array`Decode result as JSON (throws `ParseException` on failure)`__toString()``string`Same as `getResult()`Default CLI flags
-----------------

[](#default-cli-flags)

Every query invokes the `claude` binary with these flags:

FlagValueDescription`--print`*(always set)*Non-interactive mode — sends prompt via stdin and exits. Cannot be disabled.`--output-format``text` or `json`Controlled by `withJson()`. Defaults to `text`.`--model``sonnet`Configurable via params (`model`) or `withModel()`. Defaults to `sonnet`.The resulting command looks like:

```
claude --print --output-format text --model sonnet

```

Additional flags (`--system-prompt`, `--max-turns`, `--allowedTools`, `--resume`, `--continue`) are appended only when their corresponding `with*` method has been called. For any other CLI flag (e.g. `--dangerously-skip-permissions`, `--effort`, `--add-dir`), use `withFlags()`.

Platform notes
--------------

[](#platform-notes)

### Binary detection

[](#binary-detection)

The package auto-detects the `claude` binary using `which` (Linux/macOS) or `where` (Windows). If auto-detection fails — common under web servers with a minimal `$PATH` — set `binaryPath` explicitly:

```
'binaryPath' => '/home/myuser/.npm-global/bin/claude',
```

### Web server context

[](#web-server-context)

When PHP runs under Apache/nginx, the subprocess inherits the web server's environment. This means:

- `$HOME` points to the web server user (e.g. `www-data`), which won't have Claude authenticated
- `$PATH` may not include the directory where `claude` is installed

Solutions:

1. Set `binaryPath` to the full path of the `claude` binary
2. Use `envSet` to pass the correct `HOME` (for subscription auth) or use `apiKey` (for API auth)

```
'binaryPath' => '/home/deploy/.npm-global/bin/claude',
'envSet' => ['HOME' => '/home/deploy'],
```

### Recursion prevention

[](#recursion-prevention)

By default, `CLAUDECODE` and `ANTHROPIC_API_KEY` are unset in the subprocess to prevent:

- Infinite recursion if your app is itself running inside Claude Code
- Accidental API charges when you intend to use a subscription

This is configurable via `envUnset`. When `apiKey` is set, it overrides the `ANTHROPIC_API_KEY` unset.

Testing
-------

[](#testing)

```
composer test          # PHPUnit with --testdox
composer analyse       # Psalm static analysis
```

Integration tests that call the real Claude CLI are automatically skipped if the binary is not available.

License
-------

[](#license)

MIT

###  Health Score

41

—

FairBetter than 88% of packages

Maintenance95

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 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.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

56d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/eb9295442ae3080252d831794578a67b53968136834c0ebb1878d4f495a1f79a?d=identicon)[CodeChap](/maintainers/CodeChap)

---

Top Contributors

[![codeChap](https://avatars.githubusercontent.com/u/451621?v=4)](https://github.com/codeChap "codeChap (2 commits)")

---

Tags

cliaiclaudeanthropicyii3claude-code

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm

Type Coverage Yes

### Embed Badge

![Health badge](/badges/codechap-yii3-claude-code/health.svg)

```
[![Health](https://phpackages.com/badges/codechap-yii3-claude-code/health.svg)](https://phpackages.com/packages/codechap-yii3-claude-code)
```

###  Alternatives

[cilex/cilex

The PHP micro-framework for Command line tools based on the Symfony2 Components

6183.2M14](/packages/cilex-cilex)[helhum/typo3-console

A reliable and powerful command line interface for TYPO3 CMS

2939.0M192](/packages/helhum-typo3-console)[cognesy/instructor-php

The complete AI toolkit for PHP: unified LLM API, structured outputs, agents, and coding agent control

310107.9k1](/packages/cognesy-instructor-php)[n98/magerun

Tools for managing Magento projects and installations

1.4k264.7k7](/packages/n98-magerun)[n98/magerun2

Tools for managing Magento projects and installations

928244.3k6](/packages/n98-magerun2)[laminas/laminas-cli

Command-line interface for Laminas projects

563.7M54](/packages/laminas-laminas-cli)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)