Setup

​

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

​

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 publish \n
  --target-config-dir=<target config dir location>
  --target-prompts-dir=<target prompts dir location>
  --target-env-file=<target .env file location>

You can also manually copy the required files to your project directory.

​

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'

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_PATH='/path/to/your/config/dir/'

​

Framework Integration

​

Laravel Projects

For Laravel applications, it’s recommended to align with the framework’s directory structure:

./vendor/bin/instructor publish \
    --target-config-dir=config/instructor \
    --target-prompts-dir=resources/prompts \
    --target-env-file=.env

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 publish \
    --target-config-dir=config/packages/instructor \
    --target-prompts-dir=resources/instructor/prompts \
    --target-env-file=.env

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 default locations:

INSTRUCTOR_CONFIG_PATH=/path/to/config

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’ll 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 automatically using the provided CLI tool.

./vendor/bin/instructor publish

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 publish \
    --target-config-dir=./config/instructor \
    --target-prompts-dir=./resources/prompts \
    --target-env-file=.env

​

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 directory
mkdir -p config/instructor

# Copy configuration files
cp -r vendor/cognesy/instructor-php/config/* config/instructor/

These files contain LLM API connection settings and Instructor’s behavior configuration.

​

Prompt Templates

# Create prompts directory
mkdir -p resources/prompts

# Copy prompt templates
cp -r vendor/cognesy/instructor-php/prompts/* resources/prompts/

Prompt templates define how Instructor communicates with LLMs for different tasks.

​

Environment Configuration

If .env doesn’t exist, copy environment template:

[ ! -f .env ] && cp vendor/cognesy/instructor-php/config/.env-dist .env

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_PATH=<path/to/config>