PHPackages                             3neti/voucher - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Payment Processing](/categories/payments)
4. /
5. 3neti/voucher

ActiveLibrary[Payment Processing](/categories/payments)

3neti/voucher
=============

Digital voucher module for issuance, redemption, and lifecycle management

0.10.3(2mo ago)020↓90.9%1proprietaryPHPPHP ^8.2

Since Apr 3Pushed 1mo agoCompare

[ Source](https://github.com/3neti/voucher)[ Packagist](https://packagist.org/packages/3neti/voucher)[ RSS](/packages/3neti-voucher/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (3)Dependencies (32)Versions (9)Used By (1)

Digital Voucher System with Cash Entity
=======================================

[](#digital-voucher-system-with-cash-entity)

Overview
--------

[](#overview)

The **Digital Voucher System** is designed to manage and redeem vouchers that may include monetary value (cash), specific validation rules, feedback mechanisms, and instructions for issuing or redeeming vouchers. This system includes robust handling for **cash entities** that are tightly integrated with **redeemable vouchers**.

This document outlines the `Cash` entity, its relationship to the voucher system, and its critical features like tagging, status management, redemption rules, and validation.

---

Core Components
---------------

[](#core-components)

1. **Cash Entity (`Cash` Model)**:

    - Represents a monetary value or cash amount tied to a voucher.
    - Features secure handling with hashed secrets for redemption.
    - Enables tagging, tracking statuses, and metadata storage.
    - Supports advanced validation, including expiry and custom rules.
2. **Voucher Entity (`Voucher` Model)**:

    - Represents the actual voucher, which may reference associated `Cash`.
    - Includes instructions for issuing or redeeming vouchers (e.g., feedback or rider instructions).

---

Features of the `Cash` Model
----------------------------

[](#features-of-the-cash-model)

### 1. **Attributes**

[](#1-attributes)

- `amount`: Represents the monetary value in minor units using the [Brick\\Money](https://brick.money) library.
- `currency`: Default to **PHP** but configurable on creation.
- `meta`: Stores custom metadata (`ArrayObject`).
- `secret`: A **hashed value** used for secure redemption.
- `expires_on`: Specifies when the cash expires.
- `status`: Tracks the current status of the cash (`e.g., MINTED, EXPIRED`).
- `reference`: A morph-to relationship to link cash to a voucher or any reference.

### 2. **Status Management**

[](#2-status-management)

- Uses the Spatie `HasStatuses` trait for dynamic status management.
- Allows status tracking with reasons for changes.
- Provides methods like:
    - `setStatus(CashStatus $status, string $reason = null)`
    - `hasStatus(CashStatus $status)`
    - `hasHadStatus(CashStatus $status)`
    - `getCurrentStatus()`

### 3. **Tagging**

[](#3-tagging)

- Uses the Spatie `HasTags` trait for adding tags to cash.
- Supports:
    - Attaching/detaching tags.
    - Querying models by tags.
    - Setting translated tags.

### 4. **Secure Redemption**

[](#4-secure-redemption)

- Each cash entity includes a **hashed secret** for redemption validation:
    - Use `setSecretAttribute` to hash the secret before saving.
    - Validate with `verifySecret(string $providedSecret)`.
- Combines expiration and secret-checking for redemption with `canRedeem()`.

### 5. **Validation and Metadata**

[](#5-validation-and-metadata)

- Custom validation rules are supported via `CashValidationRulesData` (e.g., location, country, and mobile validations).
- Metadata extends flexibility, allowing custom annotations when linking to vouchers.

### 6. **Integration with Vouchers**

[](#6-integration-with-vouchers)

- A `Cash` instance can reference a voucher via polymorphic relationships.
- Voucher instructions include:
    - `cash` validations and amounts.
    - Feedback and rider instructions.

---

How It Works
------------

[](#how-it-works)

### **Cash Creation**

[](#cash-creation)

A `Cash` instance typically gets created and linked to a voucher:

```
use LBHurtado\Voucher\Models\Cash;
use Brick\Money\Money;

$cash = Cash::create([
    'amount' => Money::of(1000, 'PHP'), // 1,000 PHP in major units
    'currency' => 'PHP',
    'meta' => ['usage' => 'transport allowance'],
    'expires_on' => now()->addWeek(),
    'secret' => 'secure-secret-key', // Automatically hashed
]);
```

### **Redemption Validation**

[](#redemption-validation)

The `canRedeem()` method ensures that the cash:

1. Has not expired.
2. Matches the provided secret:

```
if ($cash->canRedeem($providedSecret)) {
    // Process redemption logic here
} else {
    // Handle failure (e.g., invalid secret or expired cash)
}
```

### **Status Tracking**

[](#status-tracking)

Handle status changes such as `MINTED`, `EXPIRED`, or `DISBURSED`:

```
use LBHurtado\Voucher\Enums\CashStatus;

$cash->setStatus(CashStatus::DISBURSED, 'Funds disbursed for purchase');
```

### **Tagging Example**

[](#tagging-example)

Tags can classify or group cash instances:

```
$cash->attachTags(['finance', 'budget']);
$cashWithTags = Cash::withAnyTags(['finance'])->get();
```

---

Testing
-------

[](#testing)

### **Unit Testing**

[](#unit-testing)

- The suite uses **Pest** for fast and expressive unit tests.
- Coverage for:
    - Validation: `CashValidationRulesDataTest.php`, `CashInstructionDataTest.php`
    - Secure redemption: `CashSecretTest.php`
    - Tagging: `CashTagTest.php`
    - Statuses: `CashStatusTest.php`
    - Instructions and metadata: `VoucherInstructionsDataTest.php`

### **Sample Test:**

[](#sample-test)

Tests ensure methods like `canRedeem` work as expected:

```
it('does not allow redemption if cash has expired', function () {
    $cash = Cash::factory()->create([
        'expires_on' => now()->subDay(), // Expired yesterday
        'secret' => 'secure-secret',
    ]);

    $validSecret = 'secure-secret';

    expect($cash->canRedeem($validSecret))->toBeFalse(); // Fails due to expiration
});
```

Run the test suite:

```
./vendor/bin/pest
```

---

Code Structure
--------------

[](#code-structure)

### Models

[](#models)

- **`Cash`**: Core monetary entity with statuses, tags, and secure redemption.
- **`Voucher`**: A redeemable voucher that may have associated cash.

### Data Classes

[](#data-classes)

- `CashValidationRulesData`: For cash-specific validation rules (e.g., mobile, location).
- `VoucherInstructionsData`: Holds all voucher-related instructions.

### Enums

[](#enums)

- `CashStatus`: Tracks the current state of cash (e.g., `MINTED`, `EXPIRED`).
- `VoucherInputField`: Lists possible input fields for voucher instructions (e.g., `MOBILE`, `EMAIL`).

---

Key Files
---------

[](#key-files)

FilePurpose`CashTest.php`Core tests for `Cash` model functionality`CashSecretTest.php`Tests secure secret handling and redemption logic`CashStatusTest.php`Tests status management for `Cash` entity`CashTagTest.php`Tests tagging functionality for `Cash` entity`VoucherInstructionsDataTest`Tests voucher instructions and serialization---

Example Workflow
----------------

[](#example-workflow)

### 1. **Create a Voucher with Cash**:

[](#1-create-a-voucher-with-cash)

Use structured data classes to create a voucher with cash, inputs, and validation:

```
$instructions = new VoucherInstructionsData([
    'cash' => [
        'amount' => 1000,
        'currency' => 'PHP',
        'validation' => [
            'secret' => 'secure-secret',
        ],
    ],
]);

$voucher = Vouchers::create([
    'metadata' => ['instructions' => $instructions],
]);
```

### 2. **Redeem a Voucher**:

[](#2-redeem-a-voucher)

Validate cash redemption:

```
$cash = $voucher->cash;

if ($cash->canRedeem($providedSecret)) {
    $cash->setStatus(CashStatus::DISBURSED);
}
```

---

Conclusion
----------

[](#conclusion)

The **Digital Voucher System** with the `Cash` entity provides a robust framework for managing redeemable vouchers. Combined with secure secret handling, tagging, validation, and metadata storage, this system is designed to meet modern financial and transactional needs. Propel your application with this flexible and modular system! 🚀

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance90

Actively maintained with recent releases

Popularity6

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~2 days

Total

8

Last Release

75d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/586e1ed70140038e6348728222adbcf68bfc4455b1f94a4f8bcbe57917a63d57?d=identicon)[3neti](/maintainers/3neti)

---

Top Contributors

[![3neti](https://avatars.githubusercontent.com/u/89447696?v=4)](https://github.com/3neti "3neti (28 commits)")

---

Tags

laravelpaymentswalletvoucherredemptionissuance

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/3neti-voucher/health.svg)

```
[![Health](https://phpackages.com/badges/3neti-voucher/health.svg)](https://phpackages.com/packages/3neti-voucher)
```

###  Alternatives

[bavix/laravel-wallet-swap

Addition to the package laravel-wallet.

2529.6k](/packages/bavix-laravel-wallet-swap)[musahmusah/laravel-multipayment-gateways

A Laravel Package that makes implementation of multiple payment Gateways endpoints and webhooks seamless

882.2k1](/packages/musahmusah-laravel-multipayment-gateways)[threesquared/laravel-paymill

Laravel wrapper for the Paymill API

121.3k](/packages/threesquared-laravel-paymill)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)