README

⚠️ Fork Notice

This package is a maintained fork of the original
frittenkeez/laravel-vouchers.

Why this fork exists

✅ Adds Laravel 13 compatibility
✅ Aligns with 3neti migration ownership architecture
🔄 Will evolve independently to support:
- settlement integration
- idempotency
- metadata improvements

This package is now the source of truth for the vouchers table schema in the 3neti ecosystem.

📦 Installation

composer require 3neti/laravel-vouchers:^1.2

🚨 Migration Policy (Important)

Unlike the original package:

❌ Original behavior

Requires vendor:publish for migrations

✅ This fork

Uses loadMigrationsFrom()
No publishing required
Migrations are loaded automatically

php artisan migrate

Native JSON metadata

The vouchers.metadata and redeemers.metadata columns use Laravel's jsonb() schema declaration. Fresh databases therefore use PostgreSQL jsonb, MySQL json, and SQLite's JSON-compatible text storage.

Metadata is limited to 8 MiB by default. It is intended for structured instructions, settlement facts, and evidence descriptors. Store images, signatures, PDFs, and other binary artifacts in private object storage and keep only their storage references, hashes, MIME types, and dimensions in voucher metadata.

'metadata' => [
    'max_bytes' => 8 * 1024 * 1024,
],

The limit may be overridden in config/vouchers.php when an application has a reviewed operational reason.

🧠 Ownership Rule

This package owns:

vouchers table
voucherables table
all schema updates related to vouchers

Other packages (e.g., 3neti/voucher, 3neti/cash)
must NOT modify voucher tables directly

🔄 Versioning Strategy

Current: v1.2.0

Upcoming releases will follow:

v1.x → compatibility + internal alignment
v2.x → schema ownership + architectural changes

⚙️ Configuration

php artisan vendor:publish --tag=config --provider="FrittenKeeZ\\Vouchers\\VouchersServiceProvider"

🚀 Usage

This package provides the Vouchers facade:

use FrittenKeeZ\\Vouchers\\Facades\\Vouchers;

Generate Codes

$code = Vouchers::generate('***-***-***', '1234567890');

$codes = Vouchers::batch(10);

Create Vouchers

$voucher = Vouchers::create();
$vouchers = Vouchers::create(10);

Redeem Vouchers

Vouchers::redeem('123-456-789', $user);

Handles exceptions:

VoucherNotFoundException
VoucherRedeemedException
VoucherExpiredException
VoucherUnstartedException

Unredeem Vouchers

Vouchers::unredeem('123-456-789', $user);

🧩 Traits

HasVouchers

use FrittenKeeZ\\Vouchers\\Concerns\\HasVouchers;

$user->vouchers;
$user->createVoucher();

HasRedeemers

use FrittenKeeZ\\Vouchers\\Concerns\\HasRedeemers;

$user->redeemers;

🧠 Architectural Notes (3neti)

This fork is part of a larger system:

voucher → business logic
cash → financial ledger
settlement-envelope → settlement gating
wallet → balance orchestration

Role of this package

Schema + Core Voucher Engine

It should remain:

deterministic
storage-focused
side-effect minimal

🚫 Anti-Patterns

Do NOT:

modify voucher tables outside this package
duplicate voucher schema in other packages
treat vouchers as business logic containers

🧪 Testing

composer test

The release matrix covers PHP 8.3 and 8.4 on Laravel 12 and 13. Native metadata contracts are additionally exercised against PostgreSQL 16 and MySQL 8.4. The declared constraints retain compatibility with Laravel 10 and 11 for existing consumers.

🙏 Acknowledgement

Original package by: Frederik Sauer
https://github.com/FrittenKeeZ/laravel-vouchers

📄 License

MIT

3neti / laravel-vouchers

Maintainers

Package info

Statistics

Security