Artisan Commands¶

The package provides several Artisan commands to help with development and testing.

instructor:install¶

Installs and configures the Instructor package.

php artisan instructor:install

What It Does¶

Publishes the configuration file (config/instructor.php)
Checks for API key configuration in .env
Shows next steps for getting started

Options¶

Option	Description
`--force`	Overwrite existing configuration files

Example Output¶

Installing Instructor for Laravel...

Publishing configuration... done
Checking API key configuration... ✓

Next steps:

  1. Configure your API keys in .env:
     OPENAI_API_KEY=your-key-here

  2. Create a response model:
     php artisan make:response-model PersonData

  3. Extract structured data:
     $person = StructuredOutput::with(
         messages: "John is 30 years old",
         responseModel: PersonData::class,
     )->get();

  4. Test your installation:
     php artisan instructor:test

Instructor installed successfully!

instructor:test¶

Tests your Instructor installation and API configuration.

php artisan instructor:test

What It Does¶

Displays current configuration
Makes a test API call
Verifies the response

Options¶

Option	Description
`--preset=`	Test a specific connection preset
`--inference`	Test raw inference instead of structured output

Examples¶

# Test default connection
php artisan instructor:test

# Test specific connection
php artisan instructor:test --preset=anthropic

# Test raw inference
php artisan instructor:test --inference

Example Output¶

Testing Instructor installation...

Preset ............................................. openai
Driver ............................................. openai
Model .............................................. gpt-4o-mini
API Key ............................................ sk-...abc ✓

Testing structured output extraction... ✓

Structured output test completed!

make:response-model¶

Generates a new response model class.

php artisan make:response-model {name}

Arguments¶

Argument	Description
`name`	The name of the response model class

Options¶

Option	Description
`--collection`, `-c`	Create a collection response model
`--nested`, `-n`	Create a nested objects response model
`--description=`, `-d`	Set the class description
`--force`, `-f`	Overwrite existing file

Examples¶

Basic Response Model¶

php artisan make:response-model PersonData

Creates app/ResponseModels/PersonData.php:

<?php

declare(strict_types=1);

namespace App\ResponseModels;

/**
 * TODO: Add description for this response model
 */
final class PersonData
{
    public function __construct(
        /** The name of the person */
        public readonly string $name,

        /** The age of the person in years */
        public readonly int $age,

        /** Optional email address */
        public readonly ?string $email = null,
    ) {}
}

Collection Response Model¶

php artisan make:response-model ProductList --collection

Creates a model with an array of items:

final class ProductList
{
    public function __construct(
        /** List of extracted items */
        public readonly array $items,
    ) {}
}

final class ProductListItem
{
    public function __construct(
        public readonly string $name,
        public readonly ?string $description = null,
    ) {}
}

Nested Objects Response Model¶

php artisan make:response-model CompanyProfile --nested

Creates a model with nested objects:

final class CompanyProfile
{
    public function __construct(
        public readonly string $title,
        public readonly CompanyProfileContact $contact,
        public readonly ?CompanyProfileAddress $address = null,
    ) {}
}

final class CompanyProfileContact
{
    public function __construct(
        public readonly string $name,
        public readonly string $email,
        public readonly ?string $phone = null,
    ) {}
}

final class CompanyProfileAddress
{
    public function __construct(
        public readonly string $street,
        public readonly string $city,
        public readonly string $country,
        public readonly ?string $postalCode = null,
    ) {}
}

With Description¶

php artisan make:response-model Invoice --description="Represents an invoice extracted from PDF documents"

Creates a model with the specified description in the docblock.

Customizing Stubs¶

Publish the stubs to customize them:

php artisan vendor:publish --tag=instructor-stubs

This copies stubs to stubs/instructor/:

stubs/instructor/
├── response-model.stub
├── response-model.collection.stub
└── response-model.nested.stub

Edit these files to customize generated response models.

Stub Placeholders¶

Placeholder	Description
`{{ namespace }}`	The class namespace
`{{ class }}`	The class name
`{{ description }}`	The class description

Creating Custom Commands¶

Extend the package commands for your specific needs:

// app/Console/Commands/ExtractInvoiceCommand.php
namespace App\Console\Commands;

use App\ResponseModels\InvoiceData;
use Cognesy\Instructor\Laravel\Facades\StructuredOutput;
use Illuminate\Console\Command;

class ExtractInvoiceCommand extends Command
{
    protected $signature = 'invoice:extract {file}';
    protected $description = 'Extract invoice data from a file';

    public function handle(): int
    {
        $content = file_get_contents($this->argument('file'));

        $invoice = StructuredOutput::with(
            messages: $content,
            responseModel: InvoiceData::class,
        )->get();

        $this->info("Invoice Number: {$invoice->number}");
        $this->info("Amount: \${$invoice->amount}");
        $this->info("Due Date: {$invoice->dueDate}");

        return self::SUCCESS;
    }
}

Command Reference¶

Command	Description
`instructor:install`	Install and configure the package
`instructor:test`	Test API configuration
`make:response-model`	Generate a response model class