'events' => [
    // Enable bridging to Laravel's event dispatcher
    'dispatch_to_laravel' => env('INSTRUCTOR_DISPATCH_EVENTS', true),

    // Specify which events to bridge (empty = all events)
    'bridge_events' => [
        // Only bridge specific events
        \Cognesy\Instructor\Events\ExtractionComplete::class,
        \Cognesy\Instructor\Events\ExtractionFailed::class,
    ],
],
// @doctest id="3c33"

// app/Listeners/LogExtractionComplete.php
namespace App\Listeners;

use Cognesy\Instructor\Events\ExtractionComplete;
use Illuminate\Support\Facades\Log;

class LogExtractionComplete
{
    public function handle(ExtractionComplete $event): void
    {
        Log::info('Extraction completed', [
            'response_model' => $event->responseModel,
            'duration_ms' => $event->durationMs,
        ]);
    }
}
// @doctest id="4f8c"

// app/Providers/EventServiceProvider.php
namespace App\Providers;

use App\Listeners\LogExtractionComplete;
use Cognesy\Instructor\Events\ExtractionComplete;
use Illuminate\Foundation\Support\Providers\EventServiceProvider as ServiceProvider;

class EventServiceProvider extends ServiceProvider
{
    protected $listen = [
        ExtractionComplete::class => [
            LogExtractionComplete::class,
        ],
    ];
}
// @doctest id="3d51"

// app/Providers/AppServiceProvider.php
use Cognesy\Instructor\Events\ExtractionComplete;
use Cognesy\Instructor\Events\ExtractionFailed;
use Illuminate\Support\Facades\Event;

public function boot(): void
{
    Event::listen(ExtractionComplete::class, function ($event) {
        // Handle successful extraction
    });

    Event::listen(ExtractionFailed::class, function ($event) {
        // Handle failed extraction
    });
}
// @doctest id="02a2"

// app/Listeners/InstructorEventSubscriber.php
namespace App\Listeners;

use Cognesy\Instructor\Events\ExtractionComplete;
use Cognesy\Instructor\Events\ExtractionFailed;
use Cognesy\Instructor\Events\ExtractionStarted;
use Illuminate\Events\Dispatcher;

class InstructorEventSubscriber
{
    public function handleStart(ExtractionStarted $event): void
    {
        // Log start
    }

    public function handleComplete(ExtractionComplete $event): void
    {
        // Log completion
    }

    public function handleFailed(ExtractionFailed $event): void
    {
        // Alert on failure
    }

    public function subscribe(Dispatcher $events): array
    {
        return [
            ExtractionStarted::class => 'handleStart',
            ExtractionComplete::class => 'handleComplete',
            ExtractionFailed::class => 'handleFailed',
        ];
    }
}

// Register in EventServiceProvider
protected $subscribe = [
    InstructorEventSubscriber::class,
];
// @doctest id="31ef"

use Cognesy\Instructor\Events\ExtractionComplete;
use Cognesy\Instructor\Events\ExtractionFailed;
use Illuminate\Support\Facades\Log;

Event::listen(ExtractionComplete::class, function ($event) {
    Log::channel('llm')->info('Extraction successful', [
        'model' => $event->model,
        'tokens_used' => $event->tokensUsed,
        'duration_ms' => $event->durationMs,
    ]);
});

Event::listen(ExtractionFailed::class, function ($event) {
    Log::channel('llm')->error('Extraction failed', [
        'error' => $event->error->getMessage(),
        'model' => $event->model,
    ]);
});
// @doctest id="4121"

use Cognesy\Instructor\Events\ExtractionComplete;
use App\Services\MetricsService;

Event::listen(ExtractionComplete::class, function ($event) {
    app(MetricsService::class)->recordExtraction([
        'model' => $event->model,
        'tokens' => $event->tokensUsed,
        'latency' => $event->durationMs,
        'success' => true,
    ]);
});
// @doctest id="468c"

use Cognesy\Instructor\Events\ExtractionFailed;
use Illuminate\Support\Facades\Notification;
use App\Notifications\ExtractionFailedNotification;

Event::listen(ExtractionFailed::class, function ($event) {
    if ($event->isCritical) {
        Notification::route('slack', config('services.slack.webhook'))
            ->notify(new ExtractionFailedNotification($event));
    }
});
// @doctest id="43db"

use Cognesy\Instructor\Events\ExtractionComplete;
use Illuminate\Support\Facades\Cache;

Event::listen(ExtractionComplete::class, function ($event) {
    $cacheKey = 'extraction:' . md5($event->inputHash);

    Cache::put($cacheKey, $event->result, now()->addHours(24));
});
// @doctest id="bcc8"

// app/Listeners/ProcessExtractionAnalytics.php
namespace App\Listeners;

use Cognesy\Instructor\Events\ExtractionComplete;
use Illuminate\Contracts\Queue\ShouldQueue;

class ProcessExtractionAnalytics implements ShouldQueue
{
    public $queue = 'analytics';

    public function handle(ExtractionComplete $event): void
    {
        // Heavy analytics processing
    }
}
// @doctest id="50ef"

use Cognesy\Instructor\Laravel\Facades\StructuredOutput;

$person = StructuredOutput::with(
    messages: 'Extract person data...',
    responseModel: PersonData::class,
)
->wiretap(function ($event) {
    // Called for every event
    logger()->debug('Event: ' . get_class($event));
})
->get();
// @doctest id="7291"

// config/instructor.php
'events' => [
    'dispatch_to_laravel' => false,
],
// @doctest id="92b2"

INSTRUCTOR_DISPATCH_EVENTS=false
// @doctest id="af39"

use Cognesy\Instructor\Events\ExtractionComplete;
use Illuminate\Support\Facades\Event;

public function test_dispatches_extraction_event(): void
{
    Event::fake([ExtractionComplete::class]);

    StructuredOutput::with(
        messages: 'John is 30',
        responseModel: PersonData::class,
    )->get();

    Event::assertDispatched(ExtractionComplete::class);
}
// @doctest id="f0cc"

Event::assertDispatched(ExtractionComplete::class, function ($event) {
    return $event->responseModel === PersonData::class
        && $event->tokensUsed > 0;
});
// @doctest id="d19d"