README

Yii AI Dialog

This package embeds the ai-dialog AI chat widget into a Yii2 application: a 💬 button in the page corner that sends the current page context to a shared gateway and streams the answer back. It is wired up like the debug toolbar — through bootstrap in the dev section of the config, guarded by IP. Nothing is added to the project's code (layout, assets): the widget bundle widget.js is pulled in as an npm-asset Composer dependency and wired up automatically.

🇷🇺 Документация на русском: docs/README.ru.md.

Architecture — what you are installing

This Composer package is only the client. It injects a small widget.js that, by itself, does nothing useful — it needs a separate shared service, the gateway:

Widget on the page ──wss──► Gateway (one shared service) ──► AI engine (with access to your repo)

The gateway accepts widget connections and, by the project + token pair, routes the request to the configured AI engine (e.g. Claude Code with read access to your repository). One gateway serves all projects. So a working setup always has two sides:

1. Client (this package) — bootstrap + module config in your Yii2 app (below).
2. Gateway — your project registered in its projects.json, gateway running and reachable over wss. See The gateway.

You don't have to memorize this: the widget guides you. Once it appears, open it — on any connection problem it shows exactly what is wrong (gateway down, project not registered, wrong token) and copy-paste-ready steps to fix it.

Requirements

• PHP 8.1 or higher.

Installation

The widget bundle is distributed as an npm-asset (npm-asset/carono-ai-dialog-widget) and pulled in by Composer. Because Composer does not inherit repositories from dependencies, the consuming project's composer.json must enable asset-packagist once:

{
    "repositories": [
        { "type": "composer", "url": "https://asset-packagist.org" }
    ],
    "config": {
        "allow-plugins": {
            "composer/installers": true,
            "oomphinc/composer-installers-extender": true
        }
    },
    "extra": {
        "installer-types": ["npm-asset"],
        "installer-paths": {
            "vendor/npm-asset/{$name}": ["type:npm-asset"]
        }
    }
}

Then:

composer require carono/yii2-ai-dialog

If Composer reports npm-asset/carono-ai-dialog-widget could not be found, asset-packagist has not indexed the package yet. As a temporary workaround add an inline repository to the project and re-run require:

{
    "type": "package",
    "package": {
        "name": "npm-asset/carono-ai-dialog-widget",
        "version": "0.2.0",
        "type": "npm-asset",
        "dist": { "type": "tar", "url": "https://registry.npmjs.org/carono-ai-dialog-widget/-/carono-ai-dialog-widget-0.2.0.tgz" }
    }
}

Setup

All configuration lives in the config, in the dev section. As with yii2-debug, wrap the registration in YII_ENV_DEV so the widget never reaches production.

config/web.php:

$config = [ /* ... */ ];

if (YII_ENV_DEV) {
    $config['bootstrap'][] = 'aiDialog';
    $config['modules']['aiDialog'] = [
        'class'   => \Carono\AiDialog\Module::class,
        'project' => 'myapp',          // = the project key in the gateway's projects.json
        'token'   => 'project-secret', // = this project's token on the gateway
        // optional:
        // 'gateway'    => 'wss://your-gateway.example', // remote gateway; omit for local ws://<host>:8787
        // 'allowedIPs' => ['127.0.0.1', '::1'],    // who sees the widget (same as debug)
        // 'enabled'    => true,                    // master switch
    ];

    // usually already present for debug/gii:
    // $config['bootstrap'][] = 'debug';
    // $config['modules']['debug'] = ['class' => \yii\debug\Module::class];
}

Three values must match the gateway side (projects.json):

How it works

The module implements BootstrapInterface. On every request it checks the client IP against allowedIPs (the same logic as yii\debug\Module) and, if access is allowed and the response is a regular HTML page, appends a <script src=".../widget.js" data-project data-gateway data-token> tag at the end of <body>. JSON/AJAX responses are left untouched.

Widget access is restricted by allowedIPs only; that is enough for local development. Protection of the gateway itself (the project token) lives on its side.

The gateway

The gateway is the shared service the widget talks to (see Architecture). You do not set up a server, nginx, or certificates per project — that part is shared and already running. To connect a new project you only:

1. Register the project in the gateway's projects.json:

   "myapp": {
     "endpoint": "claude-code",
     "repoPath": "/absolute/path/to/repo",
     "token": "project-secret",
     "allowWrite": false
   }

   • endpoint — claude-code (agent with read access to the repo), dashboard (answers from page content only), or opencode (not implemented yet).
   • repoPath — absolute path to the repo root (required for claude-code).
   • token — must equal the module's token.
   • allowWrite — keep false: the agent can only read code, not change files.

2. Restart the gateway (it reads the registry on start) and confirm your project is listed:

   curl -s http://127.0.0.1:8787/health   # {"ok":true,"projects":["myapp", ...]}

If you don't run the gateway yourself, ask its owner to add your project and give you the token.

The full, step-by-step runbook — also written so an AI agent can deploy the gateway and wire a project end-to-end — is docs/INTEGRATION.md in the ai-dialog repository.

Troubleshooting

Open the widget first — its panel names the exact problem and shows copy-paste steps. Reference:

After changing the config, clear published assets and hard-reload (Ctrl+F5):

rm -rf web/assets/*

Documentation

• Internals

If you need help or have a question, the Yii Forum is a good place for that. You may also check out other Yii Community Resources.

License

The Yii AI Dialog is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.

Support the project

Follow updates