# Laravel: LMS integration
A step-by-step guide to connecting a **Laravel** LMS (Laravel 10, 11 or 12, PHP 8.1+) to the AI Tutor chat.
This guide implements the contract in the [LMS integration guide](https://aichat.tutorpro.in/developers/lms). Read its Introduction first, and check it for the exact rules: manifest fields, display shapes and error codes. The code here is a working starting point. Wherever it says **Adapt**, replace the example queries with your own models.
> **Using Claude Code?** Give it `https://aichat.tutorpro.in/developers/lms/laravel.md` together with the prompt at the end of this guide.
## What you'll build
| File | Purpose |
| --- | --- |
| `config/services.php` | The chat's URL, your project API key and the signing secret |
| `app/Http/Middleware/VerifyAiChatSignature.php` | Rejects any request that isn't signed by the chat |
| `app/AiChat/AiTool.php`, `AiToolException.php`, `ToolRegistry.php` | The base class for tools, and the list of tools |
| `app/AiChat/Tools/*.php` | One class per tool: progress, exams, packages |
| `app/Http/Controllers/AiChatToolController.php` | Serves `GET /ai/manifest` and `POST /ai/tools/{name}` |
| `routes/api.php` | The routes, behind the middleware |
| `app/Services/AiChatClient.php` | Opens chat sessions and signs learners out |
| `app/Http/Controllers/AiTutorController.php` | The "AI Tutor" link learners tap |
| `app/Listeners/RevokeAiChatSessions.php` | Signs learners out of the chat when they log out |
| `tests/Feature/AiChatToolsTest.php` | Signature and tool tests |
## 1. Configuration
Add these to `.env`, using the values the AI chat admin gives you:
```bash
AI_CHAT_URL=https://aichat.tutorpro.in
AI_CHAT_API_KEY=ak_... # Project chat key: opens chat sessions
AI_CHAT_SIGNING_SECRET=lms_... # Verifies requests from the chat
```
Add this to the array in `config/services.php`:
```php
'ai_chat' => [
'url' => env('AI_CHAT_URL'),
'api_key' => env('AI_CHAT_API_KEY'),
'signing_secret' => env('AI_CHAT_SIGNING_SECRET'),
],
```
Run `php artisan config:clear`, or `php artisan config:cache` in production.
## 2. Verify every request
The chat signs each request with HMAC-SHA256 over `"<timestamp>.<raw body>"`. This middleware rejects anything unsigned, signed with the wrong secret, or older than 5 minutes.
`app/Http/Middleware/VerifyAiChatSignature.php`:
```php
<?php
namespace App\Http\Middleware;
use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;
class VerifyAiChatSignature
{
public function handle(Request $request, Closure $next): Response
{
$secret = (string) config('services.ai_chat.signing_secret');
$timestamp = (string) $request->header('X-AI-Chat-Timestamp', '');
$signature = (string) $request->header('X-AI-Chat-Signature', '');
// Sign the raw bytes: never re-encode the parsed JSON.
$expected = 'v1=' . hash_hmac('sha256', $timestamp . '.' . $request->getContent(), $secret);
if ($secret === ''
|| !ctype_digit($timestamp)
|| abs(time() - (int) $timestamp) > 300
|| !hash_equals($expected, $signature)) {
return response()->json(['ok' => false, 'error' => ['code' => 'forbidden']], 401);
}
return $next($request);
}
}
```
## 3. Tools
Each tool is a small class. Its properties form its manifest entry, and `handle()` returns the `data` for the response.
`app/AiChat/AiToolException.php`:
```php
<?php
namespace App\AiChat;
use RuntimeException;
/** An expected failure, sent to the chat as {"ok": false, "error": {"code": ...}}. */
class AiToolException extends RuntimeException
{
public function __construct(
public readonly string $errorCode, // not_found, forbidden, invalid_arguments or unavailable
string $message = '',
public readonly int $status = 400,
) {
parent::__construct($message);
}
}
```
`app/AiChat/AiTool.php`:
```php
<?php
namespace App\AiChat;
use DateTimeInterface;
abstract class AiTool
{
/** Lowercase snake_case; the URL is /ai/tools/{name}. */
public string $name;
public string $title;
/** What the chat reads to decide when to call this tool. Say what it returns and when to use it. */
public string $description;
/** Arguments, as JSON Schema properties (string, integer, number or boolean). Empty: none. */
public array $parameters = [];
public array $required = [];
/** true: the result depends on the learner, who is given by $userId. */
public bool $personal = true;
public int $cacheSeconds = 0;
/** text, progress, exam_list, package_cards or table. */
public string $display = 'text';
/**
* Return the "data" for the chat. $userId is the learner from the chat session: only ever
* return this learner's data. Throw AiToolException for expected failures.
*/
abstract public function handle(?string $userId, ?string $courseId, array $args): array;
public function definition(): array
{
$definition = [
'name' => $this->name,
'title' => $this->title,
'description' => $this->description,
'personal' => $this->personal,
'cache_seconds' => $this->cacheSeconds,
'display' => $this->display,
];
// Leave "parameters" out when empty: PHP would encode [] as a JSON list, not an object.
if ($this->parameters) {
$definition['parameters'] = ['type' => 'object', 'properties' => $this->parameters];
if ($this->required) {
$definition['parameters']['required'] = $this->required;
}
}
return $definition;
}
/** ISO 8601 with offset, as the chat expects. */
protected function iso(?DateTimeInterface $value): ?string
{
return $value?->format(DATE_ATOM);
}
}
```
`app/AiChat/ToolRegistry.php`:
```php
<?php
namespace App\AiChat;
class ToolRegistry
{
/** Every tool the chat may see. The admin still chooses which ones it uses. */
private const TOOLS = [
Tools\CourseProgress::class,
Tools\UpcomingExams::class,
Tools\Packages::class,
];
/** @return AiTool[] */
public function all(): array
{
return array_map(fn (string $class) => app($class), self::TOOLS);
}
public function find(string $name): ?AiTool
{
foreach ($this->all() as $tool) {
if ($tool->name === $name) {
return $tool;
}
}
return null;
}
}
```
### Example tools
These use example models (`Enrollment`, `Exam`, `Package`). **Adapt** the queries to your schema; keep the returned shapes.
`app/AiChat/Tools/CourseProgress.php` (display `progress`):
```php
<?php
namespace App\AiChat\Tools;
use App\AiChat\AiTool;
use App\Models\Enrollment;
class CourseProgress extends AiTool
{
public string $name = 'get_course_progress';
public string $title = 'Your progress';
public string $description = "The learner's completion percentage, lessons done and next lesson for each enrolled course. Use when they ask about their progress, how much is left or what to study next.";
public string $display = 'progress';
public function handle(?string $userId, ?string $courseId, array $args): array
{
// Adapt: your enrollment model and progress fields.
$enrollments = Enrollment::with('course')->where('user_id', $userId)->get();
return [
'courses' => $enrollments->map(fn (Enrollment $enrollment) => [
'name' => $enrollment->course->title,
'percent' => (int) round($enrollment->progress_percent),
'completed_lessons' => $enrollment->completed_lessons,
'total_lessons' => $enrollment->course->lessons_count,
'next_lesson' => $enrollment->nextLesson()?->title,
'last_activity' => $this->iso($enrollment->last_activity_at),
'url' => route('courses.show', $enrollment->course),
])->values()->all(),
];
}
}
```
`app/AiChat/Tools/UpcomingExams.php` (display `exam_list`, with an argument):
```php
<?php
namespace App\AiChat\Tools;
use App\AiChat\AiTool;
use App\Models\Exam;
class UpcomingExams extends AiTool
{
public string $name = 'list_upcoming_exams';
public string $title = 'Your exams';
public string $description = 'Upcoming and live exams the learner can take, soonest first, with date, time and duration. Use when they ask about exams, tests, exam dates or their schedule.';
public array $parameters = [
'limit' => ['type' => 'integer', 'minimum' => 1, 'maximum' => 10, 'description' => 'How many exams to return'],
];
public int $cacheSeconds = 300;
public string $display = 'exam_list';
public function handle(?string $userId, ?string $courseId, array $args): array
{
$limit = min(10, max(1, (int) ($args['limit'] ?? 5)));
// Adapt: exams of courses this learner is enrolled in that haven't ended.
$exams = Exam::with('course')
->whereHas('course.enrollments', fn ($query) => $query->where('user_id', $userId))
->where('ends_at', '>', now())
->orderBy('starts_at')
->limit($limit)
->get();
return [
'exams' => $exams->map(fn (Exam $exam) => [
'title' => $exam->title,
'course' => $exam->course->title,
'starts_at' => $this->iso($exam->starts_at),
'duration_minutes' => $exam->duration_minutes,
'status' => $exam->starts_at->isPast() ? 'live' : 'upcoming',
'url' => route('exams.show', $exam),
])->values()->all(),
];
}
}
```
`app/AiChat/Tools/Packages.php` (display `package_cards`):
```php
<?php
namespace App\AiChat\Tools;
use App\AiChat\AiTool;
use App\Models\Package;
class Packages extends AiTool
{
public string $name = 'get_packages';
public string $title = 'Plans for you';
public string $description = 'Packages the learner can buy, with price, validity, features and checkout link. Use when they ask about prices, plans, upgrading or unlocking content.';
public int $cacheSeconds = 300;
public string $display = 'package_cards';
public function handle(?string $userId, ?string $courseId, array $args): array
{
// Adapt: active packages this learner hasn't bought, priced for them.
$packages = Package::where('is_active', true)
->whereDoesntHave('purchases', fn ($query) => $query->where('user_id', $userId))
->orderBy('sort_order')
->get();
return [
'packages' => $packages->map(fn (Package $package) => [
'name' => $package->name,
'price' => (float) $package->price,
'currency' => 'INR',
'original_price' => $package->mrp ? (float) $package->mrp : null,
'validity' => $package->validity_months . ' months',
'features' => $package->features ?? [], // An array cast on the model
'highlight' => (bool) $package->is_featured,
'checkout_url' => route('checkout.show', $package),
])->values()->all(),
];
}
}
```
Links must be absolute `https://` URLs. Make sure `APP_URL` is `https://…` so `route()` builds them that way.
## 4. Controller and routes
`app/Http/Controllers/AiChatToolController.php`:
```php
<?php
namespace App\Http\Controllers;
use App\AiChat\AiTool;
use App\AiChat\AiToolException;
use App\AiChat\ToolRegistry;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Throwable;
class AiChatToolController extends Controller
{
public function manifest(ToolRegistry $tools): JsonResponse
{
return response()->json([
'version' => 1,
'tools' => array_map(fn (AiTool $tool) => $tool->definition(), $tools->all()),
]);
}
public function tool(Request $request, ToolRegistry $tools, string $name): JsonResponse
{
$tool = $tools->find($name);
if (!$tool) {
return $this->error('not_found', 'Unknown tool', 404);
}
$input = json_decode($request->getContent(), true);
if (!is_array($input)) {
return $this->error('invalid_arguments', 'The body must be a JSON object', 422);
}
$userId = isset($input['user_id']) ? (string) $input['user_id'] : null;
$courseId = isset($input['course_id']) ? (string) $input['course_id'] : null;
$args = is_array($input['args'] ?? null) ? $input['args'] : [];
if ($tool->personal && $userId === null) {
return $this->error('forbidden', 'This tool needs a learner', 403);
}
try {
return response()->json(['ok' => true, 'data' => $tool->handle($userId, $courseId, $args)]);
} catch (AiToolException $exception) {
return $this->error($exception->errorCode, $exception->getMessage(), $exception->status);
} catch (Throwable $exception) {
report($exception); // Logged for you; the learner is told to try again later.
return $this->error('unavailable', 'Temporarily unavailable', 503);
}
}
private function error(string $code, string $message, int $status): JsonResponse
{
return response()->json(['ok' => false, 'error' => ['code' => $code, 'message' => $message]], $status);
}
}
```
`routes/api.php` (on Laravel 11 or 12 without this file, run `php artisan install:api` first):
```php
use App\Http\Controllers\AiChatToolController;
use App\Http\Middleware\VerifyAiChatSignature;
use Illuminate\Support\Facades\Route;
Route::prefix('ai')
->middleware([VerifyAiChatSignature::class, 'throttle:120,1'])
->group(function () {
Route::get('manifest', [AiChatToolController::class, 'manifest']);
Route::post('tools/{name}', [AiChatToolController::class, 'tool'])
->where('name', '[a-z][a-z0-9_]*');
});
```
Routes in `routes/api.php` are served under `/api`. Your **base URL** for the admin is therefore `https://your-lms.example.com/api`.
## 5. Opening the chat
`app/Services/AiChatClient.php`:
```php
<?php
namespace App\Services;
use Illuminate\Http\Client\PendingRequest;
use Illuminate\Support\Facades\Http;
class AiChatClient
{
/** Opens a chat session for a learner and returns the URL to send them to. */
public function chatUrl(string $userId, ?string $courseId = null, array $claims = []): string
{
$body = ['user_id' => $userId, 'ttl_seconds' => 43200];
if ($courseId !== null) {
$body['course_id'] = $courseId;
}
if ($claims) {
$body['claims'] = $claims; // Leave out when empty: [] is not a JSON object.
}
return $this->http()->post('chat/sessions', $body)->throw()->json('chat_url');
}
/** Signs a learner out of every chat session. */
public function revoke(string $userId): void
{
$this->http()->delete('chat/sessions?' . http_build_query(['user_id' => $userId]))->throw();
}
private function http(): PendingRequest
{
return Http::baseUrl(rtrim((string) config('services.ai_chat.url'), '/'))
->withHeaders(['X-API-Key' => config('services.ai_chat.api_key')])
->acceptJson()
->timeout(10);
}
}
```
`app/Http/Controllers/AiTutorController.php`:
```php
<?php
namespace App\Http\Controllers;
use App\Services\AiChatClient;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
class AiTutorController extends Controller
{
public function open(Request $request, AiChatClient $chat, ?string $course = null): RedirectResponse
{
$user = $request->user();
$url = $chat->chatUrl((string) $user->getAuthIdentifier(), $course, [
// Adapt: how your LMS knows a learner has paid.
'plan' => $user->hasActivePurchase() ? 'paid' : 'free',
]);
return redirect()->away($url);
}
}
```
In `routes/web.php`:
```php
use App\Http\Controllers\AiTutorController;
Route::get('ai-tutor/{course?}', [AiTutorController::class, 'open'])
->middleware('auth')
->name('ai-tutor');
```
Link to it from lessons, for example `route('ai-tutor', $course->ai_chat_course_id)`. The course must exist in the AI chat project under that ID; ask the admin to create courses with your IDs.
**Mobile apps:** add an authenticated API route (for example with Sanctum) that returns `['chat_url' => $chat->chatUrl(...)]` as JSON. The app then opens that URL in a webview. The chat page can't be embedded in an iframe.
## 6. Sign learners out with the LMS
`app/Listeners/RevokeAiChatSessions.php`:
```php
<?php
namespace App\Listeners;
use App\Services\AiChatClient;
use Illuminate\Auth\Events\Logout;
use Throwable;
class RevokeAiChatSessions
{
public function __construct(private AiChatClient $chat)
{
}
public function handle(Logout $event): void
{
if (!$event->user) {
return;
}
try {
$this->chat->revoke((string) $event->user->getAuthIdentifier());
} catch (Throwable $exception) {
report($exception); // Never block logging out.
}
}
}
```
Laravel 11 and 12 discover this listener automatically. On Laravel 10, register it in `EventServiceProvider::$listen` under `Illuminate\Auth\Events\Logout::class`.
## 7. Tests
`tests/Feature/AiChatToolsTest.php`:
```php
<?php
namespace Tests\Feature;
use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Testing\TestResponse;
use Tests\TestCase;
class AiChatToolsTest extends TestCase
{
use RefreshDatabase;
protected function setUp(): void
{
parent::setUp();
config(['services.ai_chat.signing_secret' => 'test-secret']);
}
/** Sends a request signed exactly as the chat signs it. */
private function signed(string $method, string $uri, ?array $payload = null, ?int $timestamp = null): TestResponse
{
$body = $payload === null ? '' : json_encode($payload);
$timestamp = (string) ($timestamp ?? time());
$signature = 'v1=' . hash_hmac('sha256', $timestamp . '.' . $body, 'test-secret');
return $this->call($method, $uri, [], [], [], [
'HTTP_X_AI_CHAT_TIMESTAMP' => $timestamp,
'HTTP_X_AI_CHAT_SIGNATURE' => $signature,
'CONTENT_TYPE' => 'application/json',
'HTTP_ACCEPT' => 'application/json',
], $body);
}
public function test_manifest_lists_the_tools(): void
{
$this->signed('GET', '/api/ai/manifest')
->assertOk()
->assertJsonPath('version', 1)
->assertJsonFragment(['name' => 'get_course_progress']);
}
public function test_unsigned_and_stale_requests_are_rejected(): void
{
$this->getJson('/api/ai/manifest')->assertStatus(401);
$this->signed('GET', '/api/ai/manifest', null, time() - 600)->assertStatus(401);
}
public function test_progress_is_returned_for_the_requested_learner(): void
{
$user = User::factory()->create();
$this->signed('POST', '/api/ai/tools/get_course_progress', [
'user_id' => (string) $user->id,
'course_id' => null,
'args' => [],
])->assertOk()->assertJsonPath('ok', true)->assertJsonStructure(['data' => ['courses']]);
}
public function test_unknown_tools_return_not_found(): void
{
$this->signed('POST', '/api/ai/tools/nope', ['user_id' => '1', 'course_id' => null, 'args' => []])
->assertStatus(404)
->assertJsonPath('error.code', 'not_found');
}
}
```
Add a test per tool proving that one learner never sees another learner's records.
## 8. Go live
1. Deploy, and set the three `.env` values on the server.
2. Give the AI chat admin your base URL: `https://your-lms.example.com/api`.
3. The admin presses *Sync tools*, enables the tools, and uses *Test* with a real learner ID.
4. Open the chat through `/ai-tutor` as a test learner, and ask "How am I doing?" and "When is my next exam?".
If something fails, the admin panel's call log shows the error code. The [Troubleshooting](https://aichat.tutorpro.in/developers/lms#9-troubleshooting) table explains each one.
## Prompt for Claude Code
```text
Read https://aichat.tutorpro.in/developers/lms/laravel.md (and https://aichat.tutorpro.in/developers/lms.md for the full
contract) and implement the AI Tutor chat integration in this Laravel app:
1. config/services.php "ai_chat" settings from AI_CHAT_URL, AI_CHAT_API_KEY, AI_CHAT_SIGNING_SECRET.
2. VerifyAiChatSignature middleware, exactly as in the guide.
3. AiTool, AiToolException and ToolRegistry, and tools get_course_progress, list_upcoming_exams,
get_exam_results (display "table") and get_packages, using OUR models and relationships.
Inspect the codebase to find them; only ever return data for the given user_id.
4. AiChatToolController and the routes in routes/api.php.
5. AiChatClient, an "AI Tutor" route that opens the chat with claims {"plan": "free"|"paid"},
and the Logout listener that revokes sessions.
6. Feature tests from the guide, plus one per tool proving learners can't see each other's data.
Keep every tool read-only. Ask me before guessing business rules, such as who counts as "paid".
```
AI Tutor Developers