Getting Started

Minimal Setup

Install Dependencies:

composer require symfony/ai-session-message-store symfony/ai-chat symfony/http-foundation

Configure Laravel Session Driver: Ensure your .env uses a supported driver (Redis recommended for production):
```
SESSION_DRIVER=redis
```

Create a Basic Adapter: Add this to app/Providers/AppServiceProvider.php:

use Symfony\Component\Ai\Chat\MessageStoreInterface;
use Illuminate\Support\Facades\Session;

public function register()
{
    $this->app->singleton(MessageStoreInterface::class, function () {
        return new class implements MessageStoreInterface {
            public function load(string $sessionId): array
            {
                Session::setId($sessionId);
                return Session::get('ai_messages', []);
            }

            public function save(string $sessionId, array $messages): void
            {
                Session::setId($sessionId);
                Session::put('ai_messages', $messages);
            }
        };
    });
}

First Use Case: Create a simple AI chat route in routes/web.php:

use Symfony\Component\Ai\Chat\AiChat;
use Symfony\Component\Ai\Chat\MessageStoreInterface;

Route::post('/ai/chat', function () {
    $aiChat = new AiChat(app(MessageStoreInterface::class));
    $response = $aiChat->chat('Hello!');
    return response()->json(['response' => $response]);
});

Where to Look First

Adapter Pattern: Focus on the MessageStoreInterface implementation in src/MessageStore.php (if provided by the package).
Symfony AI Chat Docs: Symfony AI Chat Documentation for message store expectations.
Laravel Session Docs: Laravel Session Documentation for driver-specific quirks.

Implementation Patterns

Core Workflows

Session-Backed AI Chat:

// Store messages in session
$store->save($request->session()->getId(), $messages);

// Load messages for continuation
$messages = $store->load($request->session()->getId());

Hybrid Storage Pattern: Combine session (for active chats) with database (for archives):

public function load(string $sessionId): array
{
    $sessionMessages = parent::load($sessionId);
    $archivedMessages = DB::table('ai_messages')->where('session_id', $sessionId)->get();
    return array_merge($sessionMessages, $archivedMessages->toArray());
}

Flash Message Integration: Use Symfony’s FlashBag for AI notifications:

$this->session->getFlashBag()->add('ai_notification', 'Your chat is saved!');

Integration Tips

Service Container Binding: Bind the message store in Laravel’s container for dependency injection:

$this->app->bind(MessageStoreInterface::class, function ($app) {
    return new LaravelSessionMessageStore($app->make('session'));
});

Middleware for Session Initialization: Ensure sessions start before AI routes:

Route::middleware(['web', 'share_session_data'])->group(function () {
    Route::post('/ai/chat', [AiController::class, 'handle']);
});

Testing Strategy: Mock the message store in tests:

$store = Mockery::mock(MessageStoreInterface::class);
$store->shouldReceive('load')->andReturn([...]);
$store->shouldReceive('save')->once();

Advanced Patterns

Session TTL Management: Automatically clean up old AI messages:

use Illuminate\Support\Facades\Cache;

public function save(string $sessionId, array $messages): void
{
    Cache::remember("ai_messages_{$sessionId}", now()->addHours(1), function () use ($messages) {
        return $messages;
    });
}

Multi-Tenant Isolation: Use Redis namespaces or database prefixes:

public function load(string $sessionId): array
{
    return Session::namespace("tenant_{$tenantId}")->get('ai_messages', []);
}

Event-Driven Extensions: Dispatch events for message store actions:
```
event(new AiMessagesSaved($sessionId, $messages));
```

Gotchas and Tips

Common Pitfalls

Session ID Mismatches:
- Issue: Laravel’s session ID may differ from Symfony’s expectations.
- Fix: Explicitly set the session ID before loading/saving:
```
$request->session()->setId($sessionId); // Ensure consistency
```
Flash Message Conflicts:
- Issue: Symfony’s FlashBag may not align with Laravel’s flash().
- Fix: Normalize flash messages in the adapter:
```
public function getFlash(string $key): array
{
    return $this->session->getFlashBag()->get($key, []);
}
```
Session Driver Limitations:
- Issue: File sessions fail under load; database sessions may bloat.
- Fix: Use Redis with a dedicated namespace:
```
SESSION_DRIVER=redis
SESSION_REDIS_PREFIX=ai_chat_
```

Message Size Limits:

Issue: Large message histories may exceed session storage limits.

Fix: Implement pagination or archiving:

public function load(string $sessionId, int $limit = 100): array
{
    return array_slice(parent::load($sessionId), -$limit);
}

Debugging Tips

Log Session Data: Add debug logs to inspect stored messages:

\Log::debug('AI Messages:', ['session_id' => $sessionId, 'messages' => $messages]);

Validate Session Backend: Check if messages persist across requests:
```
dd($store->load($request->session()->getId()));
```
Symfony-Laravel API Mismatches: Use dd() to compare method signatures:
```
dd(method_exists($store, 'load')); // Verify interface compliance
```

Extension Points

Custom Message Serialization: Override serialization for complex message objects:

public function save(string $sessionId, array $messages): void
{
    $serialized = json_encode($messages);
    $this->session->put('ai_messages', $serialized);
}

Rate Limiting: Add request throttling for AI endpoints:

use Illuminate\Cache\RateLimiting\Limit;

Route::middleware(['throttle:10,1'])->group(function () {
    Route::post('/ai/chat', [AiController::class, 'handle']);
});

Analytics Integration: Track AI interactions via Laravel’s logging:

\Log::channel('ai')->info('Chat interaction', [
    'session_id' => $sessionId,
    'user_id' => auth()->id(),
    'timestamp' => now(),
]);

Configuration Quirks

Redis Configuration: Ensure Redis is properly configured in config/database.php:

'redis' => [
    'client' => 'predis',
    'options' => [
        'prefix' => 'laravel_ai_',
    ],
],

Session Timeout: Adjust SESSION_LIFETIME in .env to match AI chat needs:
```
SESSION_LIFETIME=1440 # 24 hours
```
CORS for AI Endpoints: If using API routes, configure CORS in config/cors.php:
```
'paths' => ['api/ai/*', 'sanctum/csrf-cookie'],
```

Ai Session Message Store Laravel Package