Skip to main content
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"