Skip to main content
Sometimes you need a single value — a number, a string, a boolean — without the overhead of defining a dedicated response class. The Scalar adapter handles this by wrapping a single typed field in a minimal schema.

​
Basic Usage

use Cognesy\Instructor\Extras\Scalar\Scalar;
use Cognesy\Instructor\StructuredOutput;

$age = (new StructuredOutput)
    ->with(
        messages: 'Jason is 28 years old.',
        responseModel: Scalar::integer('age'),
    )
    ->get();

// int(28)
// @doctest id="09ce"
The first argument to each factory method is the field name, which gives the model semantic context about what value to extract. An optional second argument provides a description for additional guidance.

​
Available Types

​
String

$name = (new StructuredOutput)
    ->with(
        messages: 'Jason is 28 years old.',
        responseModel: Scalar::string(name: 'firstName'),
    )
    ->get();

// string("Jason")
// @doctest id="bb03"

​
Integer

$age = (new StructuredOutput)
    ->with(
        messages: 'Jason is 28 years old.',
        responseModel: Scalar::integer('age'),
    )
    ->get();

// int(28)
// @doctest id="c534"

​
Float

$time = (new StructuredOutput)
    ->with(
        messages: 'His 100m sprint record is 11.6 seconds.',
        responseModel: Scalar::float(name: 'recordTime'),
    )
    ->get();

// float(11.6)
// @doctest id="811d"

​
Boolean

$isAdult = (new StructuredOutput)
    ->with(
        messages: 'Jason is 28 years old.',
        responseModel: Scalar::boolean(name: 'isAdult'),
    )
    ->get();

// bool(true)
// @doctest id="9a44"

​
Enum

Use Scalar::enum() to select one value from a backed enum: 
enum CitizenshipGroup: string {
    case EU = 'eu';
    case US = 'us';
    case Other = 'other';
}

$group = (new StructuredOutput)
    ->with(
        messages: 'Jason is 28 years old and lives in Germany.',
        responseModel: Scalar::enum(CitizenshipGroup::class, name: 'citizenshipGroup'),
    )
    ->get();

// CitizenshipGroup::Other
// @doctest id="aad6"
The model sees the enum’s backed values as the allowed options and returns one of them. Instructor deserializes it back into the enum instance.

​
Factory Method Signatures

All factory methods accept the same optional parameters: 
Scalar::string(
    name: 'value',            // Field name shown to the model
    description: 'Response value', // Additional guidance
    required: true,           // Whether the field is required
    defaultValue: null,       // Default if not extracted
);
// @doctest id="e278"
FactoryPHP return type
Scalar::string(...)string
Scalar::integer(...)int
Scalar::float(...)float
Scalar::boolean(...)bool
Scalar::enum(...)The backed enum instance

​
Typed Convenience Methods

When you are already working with a StructuredOutput or PendingStructuredOutput instance, you can skip get() and call a typed accessor that validates the return type: 
$age = (new StructuredOutput)
    ->with(messages: 'Jason is 28.', responseModel: Scalar::integer('age'))
    ->getInt();

$name = (new StructuredOutput)
    ->with(messages: 'Jason is 28.', responseModel: Scalar::string('name'))
    ->getString();
// @doctest id="ed38"
Available typed methods: getString(), getInt(), getFloat(), getBoolean(). These methods throw an exception if the result is not of the expected type, which provides an extra safety check beyond what get() offers.