Weave Code
Deck Laravel Package
promptphp/deck
Deck (formerly Prompt Deck) brings versioned AI prompt management to Laravel and PHP: store prompts as files, interpolate variables, track performance, run A/B tests, and activate versions across your app with Laravel AI SDK integration.
Deck (formerly Prompt Deck) brings AI prompt management to Laravel and PHP. Store your agent instructions as versioned files, compare prompt performance, and activate the right version across your app — with variable interpolation, usage tracking, A/B testing, and first-class Laravel AI SDK integration.
- Artisan scaffolding —
make:promptgenerates a clean, versioned directory structure - Version metadata — per-version files for system, user, and custom roles
- Variable interpolation — inject dynamic values into prompts at runtime
- A/B testing — compare versions and roll out the winner
- Config & migrations — publishable, framework-native setup
Frequently asked questions about Deck
- How do I install Deck in a Laravel application?
- Install it with composer require promptphp/deck. Then publish the config and migrations with php artisan vendor:publish for PromptPHP\Deck\Providers\DeckServiceProvider and run php artisan migrate. Scaffold your first prompt with php artisan make:prompt order-summary. The minimum viable integration can be just prompt files plus a Deck facade call; tracking and A/B testing are optional.
- Which Laravel and PHP versions does promptphp/deck support?
- The supplied materials do not list a definitive Laravel and PHP version matrix, so check the package composer.json and Packagist metadata before adopting it. The README includes a PHP version badge from Packagist, but you should confirm current and next LTS Laravel targets explicitly. Because the package is pre-1.0, pin the exact version you validate.
- How does the make:prompt command scaffold prompt files?
- Running php artisan make:prompt order-summary creates resources/prompts/order-summary with a prompt-level metadata.json and a v1 directory containing version metadata and system.md. Pass --user to add a user prompt, or --role= to create a custom role file. The generated files are plain Markdown and JSON, so they can live in version control with your application code.
- How do I interpolate variables in a Deck prompt?
- Deck prompts support variable interpolation using {{ $variable }} placeholders in the prompt Markdown. You supply the values when rendering the prompt through the Deck facade, and the rendered output can be converted to chat messages with toMessages(). This works for system, user, and custom roles, so the same prompt file can serve different runtime inputs.
- Can I A/B test prompt versions with Deck in Laravel?
- Yes. Deck includes A/B testing to measure prompt performance and switch between versions. The feature depends on the optional persistence layer, so publish the config and migrations and enable tracking before relying on it. You can then compare versions and activate the winner for your application.
- What happens when metadata.json active version and the database disagree?
- The file metadata acts as the bootstrap default, while the database holds environment state once a version has been activated. The package changed metadata precedence so the database overrides metadata.json after activation. This means activating a version is an environment change, not just a deploy, and you should align that behavior with your promotion and rollback process.
- Is promptphp/deck safe for production at version 0.4.x?
- It is pre-1.0 software with a single maintainer, modest adoption, and no dependent packages, so there is limited third-party production evidence. Its changelog candidly documents early fixes including path traversal validation, version directory regex handling, activation updates, and tracking table errors. That does not disqualify it, but you should pin exact versions, read every changelog entry, and test upgrades. Treat it as a dependency on your AI critical path and review security fixes carefully.
- How do I fix a no such table error when using Deck tracking?
- Tracking can default on in production and throw a no such table error on the first Deck::get() if the optional tables are missing. Publish the package migrations and run php artisan migrate, or disable tracking in the published config if you only need file-backed prompts. Clear cached config after changing tracking settings.
- Can I use Deck prompts without the Laravel AI SDK?
- Yes. Deck's variable interpolation and toMessages() output can drive any chat-completion API, not only the Laravel AI SDK. The optional HasPromptTemplate trait is only needed when you integrate with the Laravel AI SDK. For other providers, render the prompt through the facade and pass the resulting messages to your client.
- How do I upgrade from veeqtoh/prompt-deck to promptphp/deck?
- From v0.4.0 the package moved from veeqtoh/prompt-deck to promptphp/deck and the namespace changed from Veeqtoh\PromptDeck to PromptPHP\Deck. Update your Composer requirement and replace namespace imports, then follow the UPGRADE.md guide. Republish config and migrations if the new version changes them, and test prompt activation and tracking after the upgrade.
Weaver
How can I help you explore Laravel packages today?