Deck Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require promptphp/deck
   php artisan vendor:publish --provider="PromptPHP\Deck\Providers\DeckServiceProvider"
   php artisan migrate
   

2. Create your first prompt:

   php artisan make:prompt order-summary
   

   This generates a versioned structure in resources/prompts/order-summary/.

3. Edit the prompt: Modify resources/prompts/order-summary/v1/system.md with your AI instructions, using {{ $variable }} syntax for dynamic values.

4. Use the prompt in code:

   use PromptPHP\Deck\Facades\Deck;
   
   $prompt = Deck::get('order-summary');
   $rendered = $prompt->system(['tone' => 'friendly', 'order' => $orderDetails]);
   

First Use Case

AI Agent Integration: For a Laravel AI SDK agent, add the HasPromptTemplate trait to auto-load prompts:

use PromptPHP\Deck\Concerns\HasPromptTemplate;

class OrderAgent extends Agent {
    use HasPromptTemplate;
}

Implementation Patterns

Core Workflows

1. Prompt Development Cycle

• Create: Use make:prompt to scaffold versioned prompts.
• Edit: Modify role files (system.md, user.md, etc.) in versioned directories.
• Test: Validate changes with prompt:test before activation.
• Activate: Deploy updates via prompt:activate or programmatically.

2. Version Management

• Branching: Create new versions (make:prompt) for experimental changes.
• Comparison: Use prompt:diff to analyze differences between versions.
• Rollback: Activate previous versions (prompt:activate) if needed.

3. Dynamic Rendering

• Variable Interpolation: Pass variables to prompts:

  $prompt->system(['tone' => 'professional', 'product' => $product]);
  

• Multi-Role Prompts: Render all roles at once:

  $messages = $prompt->toMessages(['tone' => 'friendly']);
  

4. Performance Tracking (Optional)

• Enable tracking in config/deck.php:

  'track_performance' => true,
  

• Log usage metrics automatically when rendering prompts.

5. A/B Testing

• Activate different versions in different environments or via feature flags.
• Compare performance via the prompt_versions table.

Integration Tips

Laravel AI SDK

• Auto-Loading: Use HasPromptTemplate to eliminate manual instructions() definitions.
• Agent Generation: Run make:agent to auto-scaffold matching prompts.

Custom Stubs

• Override default templates by publishing and modifying stubs:

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

Environment-Specific Prompts

• Use config/deck.php to define environment-specific prompt paths:

  'paths' => [
      'prompts' => resource_path('prompts'),
      'stubs'   => __DIR__.'/../stubs',
  ],
  

CI/CD Pipelines

• Validation: Add prompt:test to CI to catch rendering errors early.
• Activation: Use prompt:activate in deployment scripts for zero-downtime updates.

Gotchas and Tips

Pitfalls

1. Variable Syntax Conflicts

• Issue: Using {{ $var }} in Markdown may conflict with Laravel Blade syntax.
• Fix: Escape variables with an extra $:

  {{ $${variable} }}
  

2. Missing Role Files

• Issue: toMessages() fails if a role file is missing in a version.
• Fix: Ensure all roles are scaffolded during creation (--role=assistant).

3. Database Tracking Overhead

• Issue: Performance tracking adds queries on every prompt render.
• Fix: Disable tracking in config/deck.php if unused:

  'track_performance' => env('DECK_TRACK_PERFORMANCE', false),
  

4. Version Numbering

• Issue: Manual version activation may skip numbers (e.g., v1 → v3).
• Fix: Use prompt:list to verify versions before activation.

5. File Permissions

• Issue: Artisan commands fail if resources/prompts lacks write permissions.
• Fix: Set correct permissions:

  chmod -R 755 resources/prompts
  

Debugging Tips

1. Prompt Rendering Issues

• Debug: Use prompt:test to isolate variable interpolation errors:

  php artisan prompt:test order-summary --variables='{"tone":"friendly"}'
  

2. Version Activation Errors

• Debug: Check the prompt_versions table for inconsistencies:

  SELECT * FROM prompt_versions WHERE prompt_name = 'order-summary';
  

3. Diff Output Confusion

• Tip: Use --type=system or --type=user to narrow down diffs to specific roles.

4. Laravel AI SDK Integration

• Debug: Verify the prompt_name in your agent matches the prompt directory:

  class OrderAgent extends Agent {
      use HasPromptTemplate;
  
      protected $promptName = 'order-summary'; // Must match directory name
  }
  

Extension Points

1. Custom Variable Parsers

• Extend PromptPHP\Deck\Contracts\VariableParser to support custom syntax (e.g., {{{variable}}}).

2. Additional Role Types

• Add new role stubs by publishing and modifying:

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

3. Performance Metrics

• Extend the prompt_versions table to track custom metrics (e.g., response_time_ms).

4. Web Interface

• Build a dashboard using the Deck facade to list/activate prompts via a Laravel controller.

5. Git Hooks

• Automate version bumps with a pre-commit hook:

  # Example: Increment version on commit to prompt files
  git diff --name-only HEAD~1 HEAD | grep 'resources/prompts/' && php artisan prompt:bump