Formulas

Formulas

Formula Guides

This directory contains guides for the three formula categories in the NSGI Builder payroll engine. Each guide explains what the formulas calculate, lists all available options with descriptions, provides worked examples, and suggests appropriate use cases.


Guides

Guide
Formula Category
Purpose
GROSS_FORMULAS.md
Gross Salary
Taxable earnings — basic pay, overtime, day rates, bonuses, and gross reductions
DEDUCTION_FORMULAS.md
Taxable Income Deductions
Amounts subtracted from gross: loans, pension, withholding tax, loss-time pro-rating
ALLOWANCE_FORMULAS.md
Non-Taxable Allowances
Tax-exempt benefits: travel, meals, housing, NIS/PAYE refunds, overtime allowances


Quick Orientation

How Formulas Fit Into Payroll

Builder
  1. EmployeeTotalGrossSalary   →  uses Gross Salary Formulas
  2. EmployeeTaxableIncomeDeduction  →  uses Deduction Formulas
  3. EmployeeNetSalaryAfterDeduction (computed)
  4. EmployeeNontaxableSalary   →  uses Allowance Formulas
  5. EmployeeTotalNetSalary (computed)

The Formula Pattern

All three categories use the same strategy pattern:
    A database record holds input (amount, days, hours, or percentage) and options (including formula_name).
    The relevant class (CustomizeSalary, CustomizeDeduction, or CustomizableAllowanceSalary) reads formula_name and calls FormulaRegistry::resolve*($formulaName).
    The resolved formula class runs calculate(string $input, Collection $options, FormulaContext $context) and returns a Money value.
    FormulaContext provides access to basic salary, overtime, no-pay days, NIS, PAYE, and other computed values so formulas can cross-reference related data.

Adding a New Formula

The process is identical across all three categories:
    Create a class implementing the relevant interface (SalaryFormula, DeductionFormula, or AllowanceFormula).
    Add a name constant in FormulaRegistry.
    Register the class in the appropriate boot*Formulas() method in FormulaRegistry.
    Set formula_name on the database record.
See the individual guides for full step-by-step instructions and code templates.


Key Source Files

File
Description
src/Formulas/FormulaRegistry.php
Central registry — all formula name constants and registrations
src/Formulas/FormulaContext.php
Shared helper object passed to every formula's calculate() method
src/Formulas/Contracts/SalaryFormula.php
Interface for gross salary formulas
src/Formulas/Contracts/DeductionFormula.php
Interface for deduction formulas
src/Formulas/Contracts/AllowanceFormula.php
Interface for allowance formulas
src/Formulas/GrossSalary/
Standard gross salary formula implementations
src/Formulas/GrossSalary/Custom/
Client-specific gross salary formulas
src/Formulas/Deduction/
Deduction formula implementations
src/Formulas/Allowance/
Standard allowance formula implementations
src/Formulas/Allowance/Custom/
Client-specific allowance formulas