Prompting

Instructor shifts much of the “prompting” work into the response model itself. A well-designed class with clear property names, PHPDoc comments, and typed fields often communicates intent more effectively than a lengthy system prompt.

General Principles

State the task plainly. A short, direct instruction outperforms a wall of text.
Provide the source material. Pass the text you want analyzed as part of the message.
Let the schema do the heavy lifting. Prefer changing the response model before adding more prompt detail.

Use PHPDoc Comments as Instructions

The model receives your class structure as a JSON Schema. PHPDoc comments on the class and its properties become description fields in that schema, giving the model precise guidance without bloating the prompt.

/** Extract the user's profile from the provided text. */
final class UserDetail {
    public int $age;
    public string $name;
    /** Assign the most appropriate role based on context. */
    public ?Role $role = null;
}
// @doctest id="538c"

Nullable Fields for Optional Data

Use PHP’s nullable types and set a default of null to signal that a field is truly optional. This prevents the model from inventing values when the source text does not contain the information.

final class UserDetail {
    public int $age;
    public string $name;
    public ?string $nickname = null;
}
// @doctest id="b6ba"

Enums for Standardized Fields

Use backed enums whenever a property has a fixed set of valid values. Always include a fallback case so the model can signal uncertainty rather than forcing an incorrect choice.

enum Role: string {
    case Principal = 'principal';
    case Teacher = 'teacher';
    case Student = 'student';
    case Other = 'other';
}

final class UserDetail {
    public int $age;
    public string $name;
    /** Correctly assign one of the predefined roles to the user. */
    public Role $role;
}
// @doctest id="f114"

Chain of Thought

Adding a “reasoning” or “chain of thought” field encourages the model to think step-by-step before producing the final answer. This works especially well for classification, entity extraction, and any task where intermediate reasoning improves accuracy.

final class Role {
    /** Think step by step to determine the correct title. */
    public string $chainOfThought;
    public string $title;
}

final class UserDetail {
    public int $age;
    public string $name;
    public Role $role;
}
// @doctest id="07dd"

You can make chain of thought modular by embedding it inside nested components rather than at the top level of the response model.

Reiterate Long Instructions

For complex extraction rules, restate the instructions in the field description. This keeps the guidance close to the point where the model generates its output.

/** Extract the role based on the following rules: <your rules> */
final class Role {
    /** Restate the instructions and rules to correctly determine the title. */
    public string $instructions;
    public string $title;
}
// @doctest id="6a93"

Handle Arbitrary Properties

When the set of properties is not known ahead of time, use a list of key-value pairs.

final class Property {
    public string $key;
    public string $value;
}

final class UserDetail {
    public int $age;
    public string $name;
    /** @var Property[] Extract any other relevant properties. */
    public array $properties;
}
// @doctest id="c944"

Limiting List Length

Control the number of extracted items by stating the constraint in the PHPDoc comment and optionally enforcing it with validation.

final class UserDetail {
    public int $age;
    public string $name;
    /** @var Property[] Extracted properties, no more than 3. */
    public array $properties;
}
// @doctest id="15bd"

Consistent Keys Across Records

When extracting multiple records with arbitrary properties, instruct the model to use consistent key names so downstream code can process them uniformly.

final class UserDetails {
    /** @var UserDetail[] Use consistent key names for properties across users. */
    public array $users;
}
// @doctest id="abb5"

Define Entity Relationships

When relationships exist between extracted entities, model them explicitly with identifiers and reference arrays.

final class UserDetail {
    /** Unique identifier for each user. */
    public int $id;
    public int $age;
    public string $name;
    public string $role;
    /** @var int[] IDs of coworkers this user collaborates with. */
    public array $coworkers;
}

final class UserRelationships {
    /** @var UserDetail[] Capture all users and their relationships. */
    public array $users;
}
// @doctest id="3616"

Reuse Components Across Contexts

The same class can appear in multiple properties with different PHPDoc descriptions, giving each usage its own semantic meaning.

final class TimeRange {
    /** The start time in hours. */
    public int $startTime;
    /** The end time in hours. */
    public int $endTime;
}

final class UserDetail {
    public string $name;
    /** Time range during which the user is working. */
    public TimeRange $workTime;
    /** Time range reserved for leisure activities. */
    public TimeRange $leisureTime;
}
// @doctest id="0e8a"

Error Handling with Wrapper Models

Create a wrapper class that can hold either a successful result or an error message. This lets you stay within structured output even when the input is ambiguous or invalid.

final class MaybeUser {
    public ?UserDetail $result = null;
    public bool $error = false;
    public ?string $errorMessage = null;

    public function get(): ?UserDetail {
        return $this->error ? null : $this->result;
    }
}
// @doctest id="c441"

Packages

Instructor

Polyglot

Agents

Agent-ctrl

Telemetry

Sandbox

HTTP Client

Laravel

Symfony

Xprompt

General Principles

Use PHPDoc Comments as Instructions

Nullable Fields for Optional Data

Enums for Standardized Fields

Chain of Thought

Reiterate Long Instructions

Handle Arbitrary Properties

Limiting List Length

Consistent Keys Across Records

Define Entity Relationships

Reuse Components Across Contexts

Error Handling with Wrapper Models

​General Principles

​Use PHPDoc Comments as Instructions

​Nullable Fields for Optional Data

​Enums for Standardized Fields

​Chain of Thought

​Reiterate Long Instructions

​Handle Arbitrary Properties

​Limiting List Length

​Consistent Keys Across Records

​Define Entity Relationships

​Reuse Components Across Contexts

​Error Handling with Wrapper Models

General Principles

Use PHPDoc Comments as Instructions

Nullable Fields for Optional Data

Enums for Standardized Fields

Chain of Thought

Reiterate Long Instructions

Handle Arbitrary Properties

Limiting List Length

Consistent Keys Across Records

Define Entity Relationships

Reuse Components Across Contexts

Error Handling with Wrapper Models