Search by

itmosoft / laravel-gift-cards

adeelrao007

Gift card issuance, balance management, redemption, and transaction ledger for Laravel applications.

Package info

github.com/ITMOSOFT/laravel-gift-cards

pkg:composer/itmosoft/laravel-gift-cards

Statistics

Installs: 6

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.0.0 2026-11-14 15:26 UTC

This package is auto-updated.

Last update: 2026-11-14 15:27:49 UTC


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.
  • reference is 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.