PHPackages                             3neti/instruction - 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. [Utility & Helpers](/categories/utility)
4. /
5. 3neti/instruction

ActiveLibrary[Utility & Helpers](/categories/utility)

3neti/instruction
=================

Instruction pricing and charge evaluation package.

v0.2.2(1mo ago)015MITPHPPHP ^8.2

Since Apr 11Pushed 1mo agoCompare

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

READMEChangelog (2)Dependencies (9)Versions (6)Used By (0)

3neti/instruction
=================

[](#3netiinstruction)

Instruction Pricing Engine for Laravel

---

Overview
--------

[](#overview)

`3neti/instruction` is a standalone Laravel package that evaluates the cost of instruction-based workflows.

It extracts the pricing and charge computation logic from the x-change platform into a reusable domain package.

### What it does

[](#what-it-does)

- Calculates charges for instruction payloads
- Supports dynamic instruction structures
- Applies tariff-based pricing per component
- Handles validation-based pricing rules
- Computes slice-based fees for divisible vouchers
- Supports wallet-based purchases via Bavix Laravel Wallet
- Uses **Brick Money** for safe and precise monetary handling

---

Key Concepts
------------

[](#key-concepts)

### Money Handling

[](#money-handling)

This package uses a dual representation of money:

TypeExampleMeaningDecimal (human)`'5.00'`₱5.00Minor units (system)`500`₱5.00#### Rules

[](#rules)

- Use decimal strings when defining prices:

    ```
    'price' => '5.00'
    ```
- Internally, all values are stored and computed as integer minor units:

    ```
    500
    ```
- API responses return human-readable decimal values, while also exposing minor units.

This ensures:

- no floating point errors
- consistent financial calculations
- compatibility with wallet systems

---

Installation
------------

[](#installation)

```
composer require 3neti/instruction
```

Publish config and migrations:

```
php artisan vendor:publish --tag=instruction-config
php artisan vendor:publish --tag=instruction-migrations
```

Run migrations:

```
php artisan migrate
```

Seed canonical instruction items:

```
php artisan db:seed --class="LBHurtado\Instruction\Database\Seeders\InstructionItemSeeder"
```

---

Usage
-----

[](#usage)

### Using the Action

[](#using-the-action)

```
use LBHurtado\Instruction\Actions\EvaluateInstructionCharges;
use LBHurtado\Instruction\Support\ArrayChargeableCustomer;
use LBHurtado\Instruction\Support\ArrayInstructionSource;

$customer = new ArrayChargeableCustomer([
    'email' => 'user@example.com',
]);

$instructions = new ArrayInstructionSource([
    'count' => 2,
    'inputs' => [
        'fields' => ['email'],
    ],
]);

$result = app(EvaluateInstructionCharges::class)
    ->handle($customer, $instructions);
```

---

Wallet Integration
------------------

[](#wallet-integration)

Instruction items are wallet-capable products.

- Each `InstructionItem` has its own wallet
- Charges can be:
    - estimated (no wallet interaction)
    - executed (via wallet purchase flow)

Example:

```
$customer->deposit(10000); // ₱100.00

$customer->pay($instructionItem);
```

Revenue is credited to the instruction item's wallet.

---

API
---

[](#api)

### Endpoint

[](#endpoint)

`POST /api/instruction/v1/estimate`

### Request

[](#request)

```
{
  "customer": {
    "email": "user@example.com"
  },
  "instructions": {
    "count": 2,
    "inputs": {
      "fields": ["email"]
    }
  }
}
```

### Response

[](#response)

```
{
  "success": true,
  "data": {
    "charges": [
      {
        "index": "inputs.fields.email",
        "unit_price": 5,
        "unit_price_minor": 500,
        "quantity": 2,
        "price": 10,
        "price_minor": 1000,
        "currency": "PHP",
        "label": "Email",
        "pay_count": 1
      }
    ],
    "total_amount": 10,
    "total_amount_minor": 1000,
    "total_items_charged": 1,
    "currency": "PHP"
  },
  "meta": {}
}
```

---

Price History
-------------

[](#price-history)

Instruction items support price history tracking.

Each change can be recorded with:

- old price
- new price
- effective date
- optional reason and actor

This enables:

- auditability
- pricing analytics
- future dashboards

---

Design Principles
-----------------

[](#design-principles)

### 1. Minor Unit Accounting

[](#1-minor-unit-accounting)

All monetary values are stored and computed in minor units (e.g., centavos) to ensure precision and eliminate floating-point errors.

### 2. Separation of Concerns

[](#2-separation-of-concerns)

The package is structured into clear layers:

- Models -> persistence and wallet integration
- Services -> pricing and evaluation logic
- DTOs -> serialization and API output

This keeps the system maintainable and testable.

### 3. Human vs System Representation

[](#3-human-vs-system-representation)

- Human-facing inputs use decimal strings:

    ```
    'price' => '5.00'
    ```
- System computations use integers (minor units):

    ```
    500
    ```

This removes ambiguity and ensures consistent behavior.

### 4. Wallet-First Design

[](#4-wallet-first-design)

Instruction items are treated as products with wallets:

- Each item can accumulate revenue
- Enables per-instruction accounting
- Supports future dashboards and reconciliation

### 5. Deterministic Pricing

[](#5-deterministic-pricing)

All pricing decisions are:

- explicit
- rule-based
- data-driven

This guarantees consistent results across environments and executions.

### 6. Extensibility

[](#6-extensibility)

The system is designed to evolve:

- new instruction types
- additional validation rules
- pricing modifiers
- reporting and analytics

without breaking existing behavior.

---

Architecture Diagram (logical)
------------------------------

[](#architecture-diagram-logical)

```
Client / API / Host App
        |
        v
+-------------------------------+
| EvaluateInstructionCharges    |
| Action                        |
+-------------------------------+
        |
        v
+-------------------------------+
| InstructionCostEvaluator      |
| Service                       |
+-------------------------------+
        |
        +--------------------+
        |                    |
        v                    v
+-------------------+   +----------------------+
| InstructionItem   |   | InstructionSource    |
| Repository        |   | / Customer Adapters  |
+-------------------+   +----------------------+
        |
        v
+-------------------------------+
| InstructionItem Model         |
| - Brick Money                 |
| - Minor-unit price storage    |
| - Bavix ProductInterface      |
| - Wallet-enabled              |
+-------------------------------+
        |
        +--------------------+
        |                    |
        v                    v
+-------------------+   +----------------------+
| instruction_items |   | instruction_item_    |
| table             |   | price_histories      |
+-------------------+   +----------------------+
        |
        v
+-------------------------------+
| API / DTO Layer               |
| - ChargeBreakdownData         |
| - ChargeEstimateData          |
| - decimal display output      |
| - minor-unit metadata         |
+-------------------------------+

```

### Reading the flow

[](#reading-the-flow)

1. A client, controller, or host app calls the action.
2. The action delegates pricing logic to `InstructionCostEvaluator`.
3. The evaluator loads instruction items from the repository.
4. The evaluator inspects the instruction payload and customer context.
5. `InstructionItem` supplies wallet/product pricing behavior and money normalization.
6. Charges are computed in minor units.
7. DTOs serialize the result into API-friendly decimal values, while preserving minor-unit fields.

---

Testing
-------

[](#testing)

```
composer test
```

---

License
-------

[](#license)

MIT

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance89

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity40

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 ~1 days

Total

5

Last Release

54d 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 (7 commits)")

###  Code Quality

TestsPest

### Embed Badge

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

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

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3325.1M337](/packages/psalm-plugin-laravel)[laravel/ai

The official AI SDK for Laravel.

9782.1M153](/packages/laravel-ai)[spatie/laravel-health

Monitor the health of a Laravel application

88011.3M149](/packages/spatie-laravel-health)[pressbooks/pressbooks

Pressbooks is an open source book publishing tool built on a WordPress multisite platform. Pressbooks outputs books in multiple formats, including PDF, EPUB, web, and a variety of XML flavours, using a theming/templating system, driven by CSS.

45344.0k1](/packages/pressbooks-pressbooks)[api-platform/laravel

API Platform support for Laravel

59156.3k10](/packages/api-platform-laravel)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)

PHPackages © 2026

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