README

Break down CTC into basic, HRA, PF, ESI, gratuity and net in-hand.

Splits an annual cost to company into its earnings heads, applies every statutory deduction that bites on the way down, and lands on a monthly in-hand figure you can defend line by line.

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/ctc-calculator

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

npm install @crmleaf/ctc-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.ctc({ annualCtc: 1200000, state: "Karnataka" });
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 CTC 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\CtcCalculator;
use Crmleaf\Payroll\Money;

$result = (new CtcCalculator())->calculate(
    annualCtc: Money::fromRupees(1_200_000),
    state: 'Karnataka',
);

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\CtcCalculator;

public function show(CtcCalculator $calculator)
{
    return $calculator->calculate(
        annualCtc: Money::fromRupees(1_200_000),
        state: 'Karnataka',
    )->toArray();
}

Blade - one component, no controller:

<x-crmleaf::ctc-calculator />

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

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

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

curl -X POST https://example.test/tools/ctc-calculator \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"annual_ctc":1200000,"state":"Karnataka"}'

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

{
  "tool": "ctc-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 { ctc } from '@crmleaf/ctc-calculator';

const result = ctc({ annualCtc: 1200000, state: "Karnataka" });

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=ctc-calculator-assets

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

<script src="/js/payroll.min.js"></script>
<script src="/vendor/ctc-calculator/ctc-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
`annual_ctc`	money (₹)	Yes	`1200000`
`state`	string	No	`"Karnataka"`	Professional tax is a state levy, so the state changes the net.
`basic_percent`	number	No	`40`
`hra_percent`	number	No	`50`
`include_bonus`	boolean	No	`false`
`include_leave_encashment`	boolean	No	`false`
`employer_pf_restricted_to_ceiling`	boolean	No	`true`
`regime`	one of `new`, `old`	No	`"new"`
`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' Provident Funds and Miscellaneous Provisions Act 1952; Employees' State Insurance Act 1948; Payment of Gratuity Act 1972; Income-tax Act 1961 including section 115BAC for the new regime; state professional tax enactments under Article 276 of the Constitution.

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
`ctc-calculator-config`	`config/ctc-calculator.php`
`ctc-calculator-views`	`resources/views/vendor/ctc-calculator`
`ctc-calculator-assets`	`public/vendor/ctc-calculator`

crmleaf / ctc-calculator

Maintainers

Package info

Statistics

Security