Skip to main content
This guide walks you through installing Instructor and running your first extraction. For detailed configuration options, see Setup.

​
Installation

Install the package via Composer: 
composer require cognesy/instructor-struct
# @doctest id="e4d4"
Instructor requires PHP 8.3 or later.

​
Your First Extraction

​
Step 1: Set Your API Key

Instructor needs credentials for the LLM provider you plan to use. The simplest approach is to export an environment variable before running your script: 
export OPENAI_API_KEY="sk-your-key-here"
# @doctest id="1610"
In a real project, store API keys in a .env file or your framework’s secret manager. Never hard-code keys in source files.

​
Step 2: Define a Response Model

Create a PHP class with typed public properties. Instructor will generate a JSON Schema from this class and instruct the LLM to return data matching that shape: 
class City {
    public string $name;
    public string $country;
    public int $population;
}
// @doctest id="8177"

​
Step 3: Run the Extraction

Use StructuredOutput to send a request and receive a typed result: 
<?php
require __DIR__ . '/vendor/autoload.php';

use Cognesy\Instructor\StructuredOutput;

class City {
    public string $name;
    public string $country;
    public int $population;
}

$city = StructuredOutput::using('openai')
    ->with(
        messages: 'What is the capital of France?',
        responseModel: City::class,
    )
    ->get();

echo $city->name;       // Paris
echo $city->country;    // France
echo $city->population; // 2148000
// @doctest id="749e"
The get() method returns a fully hydrated City instance. Public typed properties define the schema that Instructor sends to the model.

​
Alternative API Styles

Instructor offers several ways to build the same request. Choose whichever reads best in your codebase.

​
Fluent Builder

Chain individual with* methods for maximum readability: 
$city = StructuredOutput::using('openai')
    ->withMessages('What is the capital of France?')
    ->withResponseClass(City::class)
    ->get();
// @doctest id="398f"

​
Compact with() Call

Pass everything as named arguments to a single with() call: 
$city = StructuredOutput::using('openai')
    ->with(
        messages: 'What is the capital of France?',
        responseModel: City::class,
        model: 'gpt-4o-mini',
    )
    ->get();
// @doctest id="dd95"

​
Explicit Provider Configuration

When you need full control over the provider and model, use LLMConfig directly: 
use Cognesy\Instructor\StructuredOutput;
use Cognesy\Polyglot\Inference\Config\LLMConfig;

$city = StructuredOutput::fromConfig(
    LLMConfig::fromDsn('driver=openai,model=gpt-4o-mini')
)
    ->with(
        messages: 'What is the capital of France?',
        responseModel: City::class,
    )
    ->get();
// @doctest id="cbdf"

​
Streaming Partial Updates

For long extractions or real-time UIs, stream partial updates as the LLM generates its response: 
$stream = StructuredOutput::using('openai')
    ->with(
        messages: 'What is the capital of France?',
        responseModel: City::class,
    )
    ->stream();

foreach ($stream->partials() as $partial) {
    echo "Partial: " . ($partial->name ?? '...') . "\n";
}

$city = $stream->finalValue();
echo $city->name; // Paris
// @doctest id="0258"

​
Adding Validation

Add Symfony Validator constraints to your response model. If the LLM returns data that fails validation, Instructor will automatically retry with the error details: 
use Symfony\Component\Validator\Constraints as Assert;

class City {
    #[Assert\NotBlank]
    public string $name;

    #[Assert\NotBlank]
    public string $country;

    #[Assert\Positive]
    public int $population;
}

$city = StructuredOutput::using('openai')
    ->with(
        messages: 'What is the capital of France?',
        responseModel: City::class,
    )
    ->get();
// @doctest id="7404"
To enable retries, configure maxRetries on the runtime. See Validation for details.

​
Choosing the Right Entry Point

ScenarioEntry Point
Quick extraction with a presetStructuredOutput::using('openai')
Explicit provider/model controlStructuredOutput::fromConfig(LLMConfig::fromDsn(...))
Retries, events, or custom pipelineStructuredOutputRuntime

​
Next Steps

  • Setup — installation details and provider configuration
  • Usage — the full request-building API
  • Data Model — defining response model classes
  • Validation — validation and retry behavior
  • Modes — output modes (tool calls, JSON, JSON Schema)