Skip to main content
When you need to define the shape of extracted data at runtime — based on user input, configuration, or processing context — PHP classes are not flexible enough. The Structure class from the cognesy/dynamic package solves this by letting you define arbitrary data shapes dynamically.

​
When to Use Structures

Structures are the right choice when:
  • The data shape is not known at compile time
  • Users configure what fields to extract
  • You need to adapt the extraction schema based on context
  • Defining a PHP class for a one-off shape would be unnecessary ceremony
For static, known data shapes, a PHP class is simpler and provides better IDE support.

​
Defining a Structure

Use StructureFactory to build a Structure from various sources. The most common approach is building from a JSON Schema array. 
use Cognesy\Dynamic\StructureFactory;

$factory = new StructureFactory();

$structure = $factory->fromJsonSchema([
    'type' => 'object',
    'x-title' => 'person',
    'description' => 'A person object',
    'properties' => [
        'name' => ['type' => 'string', 'description' => 'Name of the person'],
        'age' => ['type' => 'integer', 'description' => 'Age of the person'],
        'role' => [
            'type' => 'string',
            'enum' => ['manager', 'line'],
            'description' => 'Role of the person',
        ],
    ],
    'required' => ['name', 'age', 'role'],
]);
// @doctest id="1de3"

​
From a String Definition

For quick prototyping, you can define structures using a compact string syntax. 
$structure = $factory->fromString(
    name: 'person',
    typeString: 'name:string, age:int, role:string',
    description: 'A person object',
);
// @doctest id="008c"

​
From a PHP Class

You can also create a structure from an existing class, which is useful when you want to manipulate the schema dynamically after reflection. 
$structure = $factory->fromClass(Person::class);
// @doctest id="fab4"

​
From Key-Value Data

Infer the schema from sample data. 
$structure = $factory->fromArrayKeyValues('person', [
    'name' => 'Jane',
    'age' => 25,
    'active' => true,
]);
// @doctest id="5d1a"

​
Extracting Data

Pass a Structure as the response model to StructuredOutput. The result is a Structure object with the extracted data. 
use Cognesy\Instructor\StructuredOutput;

$text = <<<TEXT
    Jane Doe lives in Springfield. She is 25 years old and works as a line worker.
TEXT;

$person = (new StructuredOutput)->with(
    messages: $text,
    responseModel: $structure,
)->get();

// Access properties directly via __get
echo $person->name;  // "Jane Doe"
echo $person->age;   // 25

// Or use get()
echo $person->get('role');  // "line"

// Convert to array
$data = $person->toArray();
// ['name' => 'Jane Doe', 'age' => 25, 'role' => 'line']
// @doctest id="8ae5"
If you prefer a raw array result, use intoArray(). 
$data = (new StructuredOutput)->with(
    messages: $text,
    responseModel: $structure,
)->intoArray()->get();
// @doctest id="5711"

​
Working with Structure Objects

Structure objects provide get() for reading properties and set() for creating modified copies. Direct property access via __get is also supported for reading. 
// Reading
$name = $person->get('name');
$name = $person->name;

// Writing (returns new instance -- Structure is immutable)
$updated = $person->set('name', 'John Doe');

// Check if property exists
$person->has('name'); // true

// Convert to array
$person->toArray();
// @doctest id="3afc"
Note that Structure is immutable. The set() method returns a new instance with the updated value, leaving the original unchanged. Direct property assignment via __set throws a BadMethodCallException.

​
Alternative Approaches

If you do not need the full Structure class, Instructor offers simpler alternatives for dynamic schemas:
  • JSON Schema array — pass a raw schema array as the response model (see Manual Schemas)
  • JsonSchema builder — use the fluent JsonSchema API for programmatic schema construction
  • Scalar — extract a single typed value (string, integer, float, boolean, or enum)
  • Sequence — extract a list of typed objects
These cover most use cases without requiring the dynamic package.