README

Statutory bonus under the Payment of Bonus Act, 8.33% to 20%.

Computes statutory bonus on the capped wage rather than the actual wage, which is the distinction between the bonus an employer owes and the bonus a spreadsheet usually produces.

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

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

npm install @crmleaf/bonus-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.bonus({ monthlyWages: 18000, bonusRate: 8.33 });
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 Bonus 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\BonusCalculator;
use Crmleaf\Payroll\Money;

$result = (new BonusCalculator())->calculate(
    monthlyWages: Money::fromRupees(18_000),
    bonusRate: 8.33,
);

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

public function show(BonusCalculator $calculator)
{
    return $calculator->calculate(
        monthlyWages: Money::fromRupees(18_000),
        bonusRate: 8.33,
    )->toArray();
}

Blade - one component, no controller:

<x-crmleaf::bonus-calculator />

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

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

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

curl -X POST https://example.test/tools/bonus-calculator \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"monthly_wages":18000,"bonus_rate":8.33}'

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

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

const result = bonus({ monthlyWages: 18000, bonusRate: 8.33 });

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

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

<script src="/js/payroll.min.js"></script>
<script src="/vendor/bonus-calculator/bonus-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
`monthly_wages`	money (₹)	Yes	`18000`
`bonus_rate`	number	No	`8.33`
`months_worked`	integer	No	`12`
`days_worked`	integer	No	`30`	Thirty working days in the year is the eligibility threshold under section 8.
`minimum_wage`	money (₹)	No	-	Where the state minimum wage exceeds ₹7,000, it becomes the calculation ceiling.
`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

Payment of Bonus Act 1965, sections 10 and 11 - a minimum of 8.33% and a maximum of 20% - with the ₹21,000 eligibility limit and the ₹7,000 or minimum-wage calculation ceiling of section 12.

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

crmleaf / bonus-calculator

Maintainers

Package info

Statistics

Security