Skip to main content

​
Start Here

Most PHP developers need just one package: 
composer require cognesy/instructor-php
This gives you everything: structured output extraction, validation, retries, and support for all major LLM providers. You’re ready to go.

​
When You Need More Control

Instructor is built on a modular architecture. If you need to work at a lower level or integrate with specific frameworks, these packages are available separately.

​
The Stack

┌─────────────────────────────────────────────────────────┐
│                    YOUR APPLICATION                      │
└───────────────────────────┬─────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────┐
│                      INSTRUCTOR                          │
│                                                          │
│   • Define a PHP class                                   │
│   • Get a validated object back                          │
│   • Automatic retries with LLM feedback                  │
│                                                          │
│   composer require cognesy/instructor-php                │
└───────────────────────────┬─────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────┐
│                       POLYGLOT                           │
│                                                          │
│   • One API for 20+ LLM providers                        │
│   • Swap OpenAI ↔ Claude ↔ Gemini with one line         │
│   • Embeddings, streaming, tool calling                  │
│                                                          │
│   composer require cognesy/polyglot                      │
└───────────────────────────┬─────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────┐
│                      HTTP CLIENT                         │
│                                                          │
│   • Streaming-first HTTP layer                           │
│   • Connection pooling, middleware                       │
│   • Multiple backends (Guzzle, Symfony, native)          │
│                                                          │
│   composer require cognesy/http-client                   │
└───────────────────────────┬─────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────┐
│                    LLM PROVIDER APIs                     │
│                                                          │
│   OpenAI • Anthropic • Google • Mistral • Cohere         │
│   Groq • Fireworks • Together • Ollama • Azure • ...     │
└─────────────────────────────────────────────────────────┘

​
Package Details

​
Instructor

The main package. Start here. Structured data extraction powered by LLMs. Define a PHP class with typed properties, pass it to Instructor with some text, get a validated object back. 
<?php
class Person {
    public string $name;
    public int $age;
}

$person = (new StructuredOutput)
    ->withResponseClass(Person::class)
    ->withMessages("John is 25 years old")
    ->get();

// $person->name = "John"
// $person->age = 25
Why use it:
  • Type-safe outputs (your IDE understands the response)
  • Automatic validation with Symfony Validator
  • Self-correcting retries (LLM gets feedback on errors)
  • Works with any provider through Polyglot
→ Instructor Documentation

​
Polyglot

Use this when you need direct LLM access without structured extraction. A unified interface for LLM providers. Write code once, run it against any provider. Useful when you’re building chat interfaces, agents, or need raw completions. 
<?php
$response = (new LLM)->using('anthropic')->chat("Explain PHP generators");

// Switch providers with one line
$response = (new LLM)->using('openai')->chat("Explain PHP generators");
$response = (new LLM)->using('gemini')->chat("Explain PHP generators");
Why use it:
  • Same code works with 20+ providers
  • No vendor lock-in
  • Streaming, embeddings, tool calling
  • Test with cheap/fast models, deploy with powerful ones
→ Polyglot Documentation

​
HTTP Client

Use this when you need low-level HTTP control. The HTTP layer that powers Polyglot. Most developers never touch this directly, but it’s available if you need custom HTTP handling, middleware, or want to build your own LLM integrations. 
<?php
$client = new HttpClient();
$response = $client->handle($request);

// Streaming responses
foreach ($client->stream($request) as $chunk) {
    echo $chunk;
}
Why use it:
  • Streaming-first design
  • Middleware pipeline
  • Multiple backends
  • Connection pooling
→ HTTP Client Documentation

​
Laravel Integration

Use this if you’re building with Laravel. Adds Laravel-specific conveniences: service provider, facades, config publishing, and testing fakes. 
<?php
// Use the facade
use Cognesy\Instructor\Facades\Instructor;

$person = Instructor::respond()
    ->withResponseClass(Person::class)
    ->withMessages($text)
    ->get();

// Or inject via dependency injection
public function extract(StructuredOutput $instructor)
{
    return $instructor->withResponseClass(Person::class)->get();
}
Why use it:
  • Auto-discovery (just install and use)
  • Laravel-style configuration
  • Testing fakes for unit tests
  • Integrates with Laravel’s logging
→ Laravel Documentation

​
Internal Packages

These packages are used internally by Instructor and Polyglot. They’re not meant for direct use, but they’re available if you’re extending the library or curious about the architecture.
PackagePurpose
addonsOptional extensions (image handling, web scraping, agents)
schemaPHP class → JSON Schema conversion
messagesMessage/conversation handling
eventsInternal event system
configConfiguration management
evalsLLM evaluation tools
metricsUsage tracking and observability
templatesPrompt templating
streamStream processing utilities

​
Quick Decision Guide

I want to…Use this
Extract structured data from textInstructor
Extract data from imagesInstructor
Build a chatbot or agentPolyglot
Switch between LLM providers easilyPolyglot (or Instructor, which includes it)
Use Instructor in LaravelInstructor + Laravel package
Build custom LLM integrationsHTTP Client + Polyglot
Just get started quicklyInstructor (includes everything)

​
Installation

# Most developers - get everything
composer require cognesy/instructor-php

# Direct LLM access only (no structured extraction)
composer require cognesy/polyglot

# Laravel integration
composer require cognesy/instructor-laravel

# Low-level HTTP only
composer require cognesy/http-client