Helpers

Description

Helpers is a shared utility package for the Laravel Enso ecosystem.

It bundles small reusable services, model traits, request helpers, casts, enums, contracts, and exceptions that are consumed by many backend packages. The package is intentionally broad: instead of modelling one business feature, it centralizes low-level building blocks that would otherwise be duplicated across the ecosystem.

Typical use cases include precise decimal arithmetic, monetary calculations, JSON parsing, factory resolution in package models, request key normalization, active-state handling, cent-based storage, seeder progress reporting, and a few convenience enums and casts.

Installation

This package is usually installed transitively by other Enso backend packages.

For standalone installation:

composer require laravel-enso/helpers

No publishing step is required.

Features

Provides decimal-safe arithmetic helpers built on BCMath.
Includes utility services for JSON reading, object wrapping, disk-size formatting, loan rates, pricing, chunk sizing, and factory resolution.
Provides Eloquent and request traits for active state, cent-based persistence, request-key normalization, morph-map handling, observer cascading, and touch propagation.
Includes casts for encrypted strings and JSON-backed object payloads.
Ships helper enums for VAT rates and payment methods.
Provides ecosystem-level helper exceptions and a JSON-friendly EnsoException.
Exposes an Activatable contract used by packages that model is_active semantics.

Usage

Use Decimals for precise arithmetic:

use LaravelEnso\Helpers\Services\Decimals;

$gross = Decimals::add('100.25', '19.75');
$vat = Decimals::mul('100', '0.19', 4);

Use JsonReader to load JSON in different formats:

use LaravelEnso\Helpers\Services\JsonReader;

$data = (new JsonReader($path))->array();
$obj = (new JsonReader($path))->obj();

Use PriceComputor for pricing totals:

use LaravelEnso\Helpers\Services\PriceComputor;

$total = (new PriceComputor('100'))
    ->quantity('2')
    ->discountPercent('10')
    ->vatPercent('19')
    ->total();

Use the InCents trait when values are stored as integers in the database:

use Illuminate\Database\Eloquent\Model;
use LaravelEnso\Helpers\Traits\InCents;

class Product extends Model
{
    use InCents;

    protected array $centAttributes = ['amount'];
}

Normalize validated request keys through MapsRequestKeys:

use Illuminate\Foundation\Http\FormRequest;
use LaravelEnso\Helpers\Traits\MapsRequestKeys;

class StoreCompany extends FormRequest
{
    use MapsRequestKeys;
}