laravel-gift-cards maintained by itmosoft
ITMOSOFT Laravel Gift Cards
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.