README

ESI employee and employer contributions for any wage.

Computes both contributions and applies the rule most software misses: once a contribution period has begun, wages crossing the limit mid-period do not stop the deduction until the period ends.

One of the CRMLeaf payroll tools. The arithmetic and the dated statutory rate tables live in crmleaf/payroll-core; this package is the thin skin that makes one calculator installable, mountable and embeddable on its own.

Note

A wrong figure or an out-of-date rate is almost always a payroll-core matter, since that is where the tables live. Anything about this tool's routes, views or browser asset belongs here.

Install

Composer - Laravel auto-discovers the service provider, so this is the whole setup:

composer require crmleaf/esi-calculator

npm - the same calculation, re-exported from @crmleaf/payroll-js so you can install this one tool and nothing else:

npm install @crmleaf/esi-calculator

Note

Not on npm yet. The script-tag route below needs no registry and works today. Installing this package straight from git will not resolve @crmleaf/payroll-js, which is not published yet either.

A plain script tag - no build step, no bundler, no server. Build the browser bundle once and serve the file yourself:

<script src="/js/payroll.min.js"></script>
<script>
const result = CrmleafPayroll.esi({ grossWages: 18000, continuingFromPriorPeriod: false });
console.log(result.explain);
</script>

payroll.min.js is the single-file browser build. Get it by running npm run build in @crmleaf/payroll-js and copying dist/payroll.min.js into whatever your site serves as static assets.

A hosted CDN build is coming soon, which will reduce this to a single URL. Serving the file yourself works today and keeps working afterwards - it is the only option that needs no third-party request, so plenty of projects will want to stay on it.

See it working first

demo/index.html in this repository is a working copy of ESI Calculator in one file: the form, the calculation and the working, with no build step and no server. Drop payroll.min.js beside it and open it from disk.

cp /path/to/payroll-js/dist/payroll.min.js demo/
open demo/index.html

Nothing on that page reaches the network, which is the point: it is a calculator people paste salary figures into.

Use it

Plain PHP, no framework and no container:

use Crmleaf\Payroll\Calculators\EsiCalculator;
use Crmleaf\Payroll\Money;

$result = (new EsiCalculator())->calculate(
    grossWages: Money::fromRupees(18_000),
    continuingFromPriorPeriod: false,
);

echo $result->explain();      // the formula with the real operands in it
echo $result->workings();     // every step, one per line, with its citation
print_r($result->toArray());  // snake_case, ready for JSON

Laravel - resolve it from the container, or type-hint it anywhere:

use Crmleaf\Payroll\Calculators\EsiCalculator;

public function show(EsiCalculator $calculator)
{
    return $calculator->calculate(
        grossWages: Money::fromRupees(18_000),
        continuingFromPriorPeriod: false,
    )->toArray();
}

Blade - one component, no controller:

<x-crmleaf::esi-calculator />

HTTP - off by default. Publish the config and turn the route on:

php artisan vendor:publish --tag=esi-calculator-config

// config/esi-calculator.php
'route' => ['enabled' => true, 'prefix' => 'tools'],

curl -X POST https://example.test/tools/esi-calculator \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"gross_wages":18000,"continuing_from_prior_period":false}'

The JSON response carries the figures, the working and the statutory citations:

{
  "tool": "esi-calculator",
  "data": { "…": "every figure, snake_case, with a *_formatted twin" },
  "explain": "the formula with the real operands substituted",
  "working": [{ "label": "…", "amount": 0, "formula": "…", "citation": "…" }],
  "citations": ["…"]
}

JavaScript:

import { esi } from '@crmleaf/esi-calculator';

const result = esi({ grossWages: 18000, continuingFromPriorPeriod: false });

No server needed

The maths here is arithmetic over versioned rate tables, so it runs anywhere. The published asset binds the markup and computes in the browser:

php artisan vendor:publish --tag=esi-calculator-assets

<section data-crmleaf-tool="esi-calculator">
  <form data-crmleaf-form> … </form>
  <div data-crmleaf-output hidden></div>
</section>

<script src="/js/payroll.min.js"></script>
<script src="/vendor/esi-calculator/esi-calculator.js"></script>

If the browser build is absent the script does nothing and the form posts to the server instead, so the page works either way.

Inputs

Field	Type	Required	Default	Notes
`gross_wages`	money (₹)	Yes	`18000`
`disabled`	boolean	No	`false`	Raises the wage limit to ₹25,000.
`average_daily_wage`	money (₹)	No	-	Below the exemption limit the employee share is nil while the employer share continues.
`continuing_from_prior_period`	boolean	No	`false`
`as_of`	date (YYYY-MM-DD)	No	-

Optional fields you leave out are omitted from the call entirely, so the calculator's own documented defaults apply.

Every figure here rests on a statutory rate, so the call takes as_of. Set it and the calculation runs on the rates in force on that date, which is what makes a prior year recomputable rather than merely rememberable.

Statutory basis

Employees' State Insurance Act 1948 with regulation 31 of the ESI (General) Regulations 1950: 0.75% employee and 3.25% employer on wages up to ₹21,000, ₹25,000 for an employee with a disability.

Rates are data, not code: they live in dated tables with a cited source in crmleaf/payroll-core, so a rate change is a new dated entry rather than an edit to a constant.

Important

This package implements our reading of the applicable statutes and is provided without warranty. It is a calculation library, not tax advice. Verify against your own compliance obligations before relying on the output for statutory filing.

Publishing

Tag	Publishes
`esi-calculator-config`	`config/esi-calculator.php`
`esi-calculator-views`	`resources/views/vendor/esi-calculator`
`esi-calculator-assets`	`public/vendor/esi-calculator`

crmleaf / esi-calculator

Maintainers

Package info

Statistics

Security