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, 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, 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();

Normalize request keys before validation with ToSnakeCase:

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

class StoreCompany extends FormRequest
{
    use ToSnakeCase;
}

Use Laravel's native validated input API to exclude validated fields:

$attributes = $request->safe()->except('roles');

Deprecated Traits

The following traits are kept for backwards compatibility only and should not be used in new code:

• FiltersRequest; use $request->safe()->except(...).
• MapsRequestKeys; use ToSnakeCase.
• InCents; use explicit model casts, accessors, and mutators for monetary values.

API

Services

Core helpers:

• Decimals
• JsonReader
• Obj
• FactoryResolver
• OptimalChunk
• DiskSize

Financial helpers:

• PriceComputor
• Loan

Utility placeholder:

• Dummy

Traits

Model traits:

• ActiveState
• AvoidsDeletionConflicts
• CascadesMorphMap
• CascadesObservers
• ForceableIndex
• InCents (deprecated)
• UpdatesOnTouch

Request / validation traits:

• FiltersRequest (deprecated)
• MapsRequestKeys (deprecated)
• ToSnakeCase
• TransformMorphMap

Seeder traits:

• SeederProgress
• DatabaseSeedProgress

Casts

• LaravelEnso\Helpers\Casts\Encrypt
• LaravelEnso\Helpers\Casts\Obj

Enums

• LaravelEnso\Helpers\Enums\PaymentMethods
• LaravelEnso\Helpers\Enums\VatRates

Contracts

• LaravelEnso\Helpers\Contracts\Activatable

Exceptions

• LaravelEnso\Helpers\Exceptions\EnsoException
• LaravelEnso\Helpers\Exceptions\InCents
• LaravelEnso\Helpers\Exceptions\JsonParse

Depends On

Required Enso packages:

• laravel-enso/enums ↗

Framework and runtime dependencies:

• laravel/framework ↗
• doctrine/dbal ↗

Contributions

are welcome. Pull requests are great, but issues are good too.

Thank you to all the people who already contributed to Enso!