> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instructorphp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Laravel

# Instructor for Laravel

Laravel integration for [Instructor PHP](https://github.com/cognesy/instructor-php) -- the structured output library for LLMs.

## Overview

Instructor for Laravel brings the full power of structured LLM output extraction into the Laravel ecosystem. Rather than parsing free-form text responses from language models, Instructor lets you define PHP classes that describe the data you need, and the package takes care of prompting the model, validating its response, and deserializing the result into typed objects.

This package provides seamless integration between Instructor PHP and Laravel, giving you:

* **Laravel Facades** -- Use `StructuredOutput::`, `Inference::`, `Embeddings::`, and `AgentCtrl::` facades for expressive, framework-native access to LLM capabilities.
* **Dependency Injection** -- Inject `StructuredOutput`, `Inference`, or `Embeddings` directly into your classes through Laravel's service container.
* **Testing Fakes** -- Mock LLM responses with `StructuredOutput::fake()`, `Inference::fake()`, `Embeddings::fake()`, and `AgentCtrl::fake()`, complete with assertion helpers for verifying extraction calls, connection usage, and model selection.
* **Native Agent Runtime** -- Resolve native `Cognesy\Agents` registries, loop factories, session runtime, broadcasting helpers, and telemetry wiring directly from Laravel's container.
* **Laravel HTTP Client** -- All API calls go through Laravel's `Http::` client under the hood, which means `Http::fake()` works out of the box in your test suite.
* **Event Bridge** -- Instructor's internal events are automatically dispatched through Laravel's event system, so you can attach listeners, subscribers, and queued handlers with no extra wiring.
* **Batteries Included Observability** -- Native agent broadcasting, telemetry projectors, and Laravel logging presets are wired through first-party config instead of app-local glue.
* **Artisan Commands** -- Generate response model scaffolding with `make:response-model`, verify your API configuration with `instructor:test`, and bootstrap the package with `instructor:install`.
* **Configuration Publishing** -- Laravel-style config file with environment variable support for all settings, from API keys and model selection to HTTP timeouts and logging presets.

The package deliberately separates two agent surfaces:

* native `Cognesy\Agents` runtime integration under `config('instructor.agents')`
* external CLI code agents via `AgentCtrl` under `config('instructor.agent_ctrl')`

## Quick Start

### 1. Install the Package

```bash theme={null}
composer require cognesy/instructor-laravel
# @doctest id="c954"
```

### 2. Configure API Key

Add to your `.env`:

```env theme={null}
OPENAI_API_KEY=your-openai-api-key
// @doctest id="2ff4"
```

### 3. Extract Structured Data

```php theme={null}
use Cognesy\Instructor\Laravel\Facades\StructuredOutput;

// Define a response model
final class PersonData
{
    public function __construct(
        public readonly string $name,
        public readonly int $age,
    ) {}
}

// Extract structured data from text
$person = StructuredOutput::with(
    messages: 'John Smith is 30 years old',
    responseModel: PersonData::class,
)->get();

echo $person->name; // "John Smith"
echo $person->age;  // 30
// @doctest id="9e13"
```

## Documentation

| Guide                              | Description                                                               |
| ---------------------------------- | ------------------------------------------------------------------------- |
| [Installation](installation)       | Detailed installation and setup instructions                              |
| [Configuration](configuration)     | Complete configuration reference                                          |
| [Facades](facades)                 | Using StructuredOutput, Inference, Embeddings, and AgentCtrl facades      |
| [Native Agents](native-agents)     | Terminology and config boundaries for native `Cognesy\Agents` integration |
| [Response Models](response-models) | Creating and using response models                                        |
| [Code Agents](agents)              | Using `AgentCtrl` for Claude Code, Codex, and OpenCode                    |
| [Testing](testing)                 | Testing with facade fakes plus native-agent helper utilities              |
| [Events](events)                   | Event handling and Laravel integration                                    |
| [Commands](commands)               | Artisan command reference                                                 |
| [Advanced](advanced)               | Streaming, validation, and advanced patterns                              |
| [Troubleshooting](troubleshooting) | Common issues and solutions                                               |

## Example: Complete Workflow

```php theme={null}
use Cognesy\Instructor\Laravel\Facades\StructuredOutput;
use App\ResponseModels\InvoiceData;

class InvoiceProcessor
{
    public function extractFromEmail(string $emailBody): InvoiceData
    {
        return StructuredOutput::with(
            messages: $emailBody,
            responseModel: InvoiceData::class,
            system: 'Extract invoice details from the email.',
        )->get();
    }
}

// In your test
public function test_extracts_invoice_data(): void
{
    $fake = StructuredOutput::fake([
        InvoiceData::class => new InvoiceData(
            invoiceNumber: 'INV-001',
            amount: 150.00,
            dueDate: '2024-12-31',
        ),
    ]);

    $processor = new InvoiceProcessor();
    $invoice = $processor->extractFromEmail('Invoice #INV-001...');

    $this->assertEquals('INV-001', $invoice->invoiceNumber);
    $fake->assertExtracted(InvoiceData::class);
}
// @doctest id="9bf8"
```

## Requirements

* PHP 8.2+
* Laravel 10.x, 11.x, or 12.x

## Support

* [GitHub Issues](https://github.com/cognesy/instructor-php/issues)
* [Documentation](https://docs.instructorphp.com)