itmosoft / laravel-gift-cards
Gift card issuance, balance management, redemption, and transaction ledger for Laravel applications.
v1.0.0
2026-11-14 15:26 UTC
Requires
- php: ^8.3
- illuminate/contracts: ^12.0 || ^13.0
- illuminate/database: ^12.0 || ^13.0
- illuminate/support: ^12.0 || ^13.0
Requires (Dev)
- orchestra/testbench: ^10.0 || ^11.0
- phpunit/phpunit: ^11.0 || ^12.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Gift card issuance, balance management, redemption, and transaction ledger for Laravel 12 and 13.
Features
- Issue gift cards with unique codes and initial balances.
- Find cards by code.
- Redeem full or partial balances.
- Track issuance and redemption in a transaction ledger.
- Expiration and disable timestamps.
- Optional metadata and external reference.
- Configurable table names and prefix.
- Database transactions and row locking around redemption.
Requirements
- PHP 8.3+
- Laravel 12 or 13
Installation
composer require itmosoft/laravel-gift-cards php artisan vendor:publish --tag=itmosoft-gift-cards-config php artisan migrate
Publishing config is optional.
Usage
use ItmoSoft\GiftCards\GiftCardManager; $manager = app(GiftCardManager::class); $card = $manager->issue( amount: 100, currency: 'USD', code: 'WELCOME100', ); $found = $manager->findByCode('WELCOME100'); $transaction = $manager->redeem( giftCard: $card, amount: 25, reference: 'ORDER-1001', ); $manager->disable($card);
Configuration
return [ 'cards_table' => 'itmosoft_gift_cards', 'transactions_table' => 'itmosoft_gift_card_transactions', 'prefix' => '', 'code_length' => 16, 'allow_partial_redemption' => true, 'currency' => 'USD', 'default_expiry_days' => null, ];
Security and accounting limitations
- Gift card codes are bearer credentials. Treat them as secrets, show them only when needed, and avoid logging them.
- This release generates random codes but does not hash them at rest, rate-limit lookup attempts, or provide a redemption PIN. Add these controls in the consuming application before public production use.
- Code uniqueness is enforced by the database. Applications issuing cards concurrently should catch unique constraint violations and retry code generation.
- Amounts are stored as decimal(12,2), but the public manager currently accepts PHP floats. For strict financial arithmetic, consider a future minor-unit/integer API and currency-specific precision rules.
- Currency compatibility between card and checkout is the caller's responsibility; no FX conversion is included.
- Expiration is checked during redemption, but there is no scheduled expiration job.
referenceis informational and is not unique/idempotent. Enforce idempotency in the application.lockForUpdate()depends on database engine support; SQLite does not provide production-equivalent row-locking guarantees.- No payment capture, refund, accounting journal, or gift-card purchase checkout integration is included.
- Applications must authorize issue, disable, and redemption operations.
Testing
composer validate --strict
composer install
composer test
MIT License. See LICENSE.