Skip to main content

​
Overview

Full Instructor setup consists of following steps:
  • Step 1: Install Instructor via Composer
  • Step 2: Publish Instructor assets (configurations and prompts) to your project directory
  • Step 3: Set up LLM provider API key(s) in your .env file
  • Step 4: Set configuration location in your .env file (optional)

​
Step 1: Install Instructor via Composer

You can install Instructor via Composer by running: 
composer require cognesy/instructor-php
# @doctest id="6dc7"

​
Step 2: Publish Instructor Files to Your Project

Instructor comes with a set of configuration files and prompt templates that you can publish to your project directory. This will allow you to customize the library’s behavior and use different prompt templates. These files can be found in the vendor/cognesy/instructor-php directory:
  • .env-dist - Environment variables for API keys and configuration paths
  • /config/*.php - Configurations of Instructor modules
  • /prompts/* - Prompt templates for generating structured data from text
You can publish these files to your project directory by running following command: 
./vendor/bin/instructor-setup publish \n
  --target-config-dir=<target config dir location>
  --target-prompts-dir=<target prompts dir location>
  --target-env-file=<target .env file location>
# @doctest id="c09e"
You can also manually copy the required files to your project directory.
Read more:

​
Step 3: Set Up LLM Provider API Key(s)

If you’re using commercial LLM providers like OpenAI, you’ll need to set up API keys in your project’s .env file. Open the .env file in your project directory and set up API keys for the LLM providers you plan to use. You can find the keys in the respective provider’s dashboard. 
# OpenAI (default provider)
OPENAI_API_KEY='your-openai-api-key'
# @doctest .env=true
Check .env-dist for other API keys Instructor uses in its default configuration files.

​
Step 4: Set Configuration Location (optional)

Instructor uses a configuration directory to store its settings, e.g. LLM provider configurations. You can set the path to this directory via Settings::setPath('/path/to/config') in your code. But to make it easier you can just set the value in your .env file. Settings will pick it up automatically from there. This way you don’t have to set it in every script. 
INSTRUCTOR_CONFIG_PATHS='/path/to/your/config/dir/,another/path'
# @doctest .env=true
INSTRUCTOR_CONFIG_PATHS is set automatically if you use the Instructor CLI tool to publish assets.

​
Framework Integration

​
Laravel Projects

For Laravel applications, it’s recommended to align with the framework’s directory structure: 
./vendor/bin/instructor-setup publish \
    --target-config-dir=config/instructor \
    --target-prompts-dir=resources/prompts \
    --target-env-file=.env
# @doctest id="5b4a"
This will:
  • Place configuration files in Laravel’s config directory
  • Store prompts in Laravel’s resources directory
  • Use Laravel’s default .env file location
After publishing, you can load Instructor configuration in your config/app.php or create a dedicated service provider.

​
Symfony Projects

For Symfony applications, use the standard Symfony directory structure: 
./vendor/bin/instructor-setup publish \
    --target-config-dir=config/packages/instructor \
    --target-prompts-dir=resources/instructor/prompts \
    --target-env-file=.env
# @doctest id="b925"
This will:
  • Place configuration in Symfony’s package configuration directory
  • Store prompts in Symfony’s resources directory
  • Use Symfony’s default .env file location
For Symfony Flex applications, you may want to create a recipe to automate this setup process.

​
Custom Framework Location

You can use environment variables to set the location of configuration files: 
INSTRUCTOR_CONFIG_PATHS=/path/to/config,another/path
// @doctest id="9400"
This allows you to maintain consistent paths across your application without specifying them in each command.

​
Using CLI Tool

After installing Instructor via Composer, you may want to publish the library’s configuration files and resources to your project, so you can modify them according to your needs. You can do this either manually or automatically using the provided CLI tool. 
./vendor/bin/instructor-setup publish
# @doctest id="3298"
By default, this command will:
  1. Copy configuration files from vendor/cognesy/instructor-php/config to config/instructor/
  2. Copy prompt templates from vendor/cognesy/instructor-php/prompts to resources/prompts/
  3. Merge (or copy) vendor/cognesy/instructor-php/.env-dist file to .env with environment variables

​
Command Options

  • -c, --target-config-dir=DIR - Custom directory for configuration files (default: config/instructor)
  • -p, --target-prompts-dir=DIR - Custom directory for prompt templates (default: resources/prompts)
  • -e, --target-env-file=FILE - Custom location for .env file (default: .env)
  • -l, --log-file=FILE - Optional log file path to track the publishing process
  • --no-op - Dry run mode - shows what would be copied without making changes

​
Example Usage

./vendor/bin/instructor-setup publish \
    --target-config-dir=./config/instructor \
    --target-prompts-dir=./resources/prompts \
    --target-env-file=.env
# @doctest id="ca62"
When merging .env files, the tool will only add missing variables, preserving your existing file content, formatting and comments.

​
Manual Setup

If you prefer to set up Instructor manually or need more control over the process, you can copy the required files directly:

​
Configuration Files

# Create config in your preferred directory
mkdir -p config/instructor

# Copy configuration files
cp -r vendor/cognesy/instructor-php/config/* config/instructor/
# @doctest id="78b7"
These files contain LLM API connection settings and Instructor’s behavior configuration.

​
Prompt Templates

# Create prompts in your preferred directory
mkdir -p resources/prompts

# Copy prompt templates
cp -r vendor/cognesy/instructor-php/prompts/* resources/prompts/
# @doctest id="d7ac"
Prompt templates define how Instructor communicates with LLMs for different tasks.

​
Environment Configuration

If .env doesn’t exist, copy the environment template: 
[ ! -f .env ] && cp vendor/cognesy/instructor-php/config/.env-dist .env
# @doctest id="9c48"
Add key values to your .env: 
# OpenAI API key
OPENAI_API_KEY=your_api_key
# Other API keys (if you use other LLM providers)
# ...

# Set up Instructor configuration path (optional)
INSTRUCTOR_CONFIG_PATHS='<path/to/config>,<another/path>'
# @doctest id="ea9d"
⌘I