# Payroll Module — Installation & Guide

## 1. Install

**File placement matters** — a previous upload had `Mailer.php` and `PayrollEngine.php` sitting in `hr_payroll/` directly instead of `hr_payroll/includes/`, which breaks every `require`. Your folder must look exactly like this:

```
hr_payroll/
  cycles.php, components.php, settings.php, employee_payroll.php, group_payroll.php,
  run_cycle.php, approval_settings.php, cycle_approve.php, payslip.php,
  send_payslips.php, send_payslips_ajax.php, reports.php, email_settings.php, cron_send_payslips.php, README.md
  includes/
    auth_init.php, helpers.php, layout_header.php, layout_footer.php,
    PayrollEngine.php, Mailer.php
  sql/
    payroll_schema.sql
```

1. Copy the whole `payroll/` folder into your app root as `hr_payroll/` (or whatever you've named it), alongside `dashboard.php`, `login.php`, `config.php`, and `components/`.
2. Run the schema once against your existing database:
   ```
   mysql -u youruser -p bestwest_ivm < payroll/sql/payroll_schema.sql
   ```
   It only creates *new* tables (`payroll_pay_components`, `payroll_cycles`, `payroll_payslip_runs`, `employee_tax_profile`, etc.) — it does not touch `employees`, `groups`, `users`, `payroll_adjustments`, `load_deductions`, or `attendance_monthly_summaries`.
3. Install PHPMailer (needed for Mailtrap emails):
   ```
   composer require phpmailer/phpmailer
   ```
   from your app root, so `vendor/autoload.php` exists one level above `hr_payroll/`.
4. Add a "Payroll" section to your `components/sidebar.php` linking to the pages below.
5. Visit `payroll/email_settings.php` and paste your Mailtrap SMTP credentials (Mailtrap dashboard → Sending Domains or your sandbox inbox → SMTP Settings).
6. (Optional, for fully automatic payday emails) add a daily cron job:
   ```
   0 8 * * * php /full/path/to/hr_payroll/cron_send_payslips.php
   ```

## 2. How each of your requirements maps to a page

| Requirement | Page |
|---|---|
| Set payroll cycle with start/end | `cycles.php` |
| Set salary and rent per employee | `employee_payroll.php` (Basic Salary + Rent Allowance are pre-seeded components) |
| Nigeria Tax Act 2025 PAYE bands | `includes/PayrollEngine.php` + `settings.php` (bands stored in `tax_bands`, editable) |
| Add/remove any component from an individual payslip | `employee_payroll.php` — uncheck "Active" or change amount |
| Add/remove components at pay-group level | `group_payroll.php` |
| Configurable approval flow | `approval_settings.php` (define any number of stages) + `cycle_approve.php` (act on a cycle's stages) |
| Auto email payslips on payday | `send_payslips.php` (AJAX-driven, live progress bar, skips employees with no email) + `cron_send_payslips.php` (fully automatic on `end_date`) |
| Mailtrap integration | `includes/Mailer.php` + `email_settings.php` |
| Reports by pay group | `reports.php` |
| Default statutory deductions for all employees | `settings.php` — toggle Pension / NHF / NHIS / PAYE on or off globally |
| Edit and reorder pay components | `components.php` — "Edit" link opens an inline edit form; ↑/↓ arrows reorder (statutory components: only the name is editable) |
| Capture each employee's annual rent paid (for tax relief) | `employee_payroll.php` — "Annual Rent Paid" form, stored in `employee_tax_profile`, used by the engine instead of any Rent Allowance salary component |

## 3. How the numbers are calculated (`PayrollEngine.php`)

For each employee, per cycle:
1. Resolve every non-statutory component: **employee-level override → pay-group default → component default** (in that precedence order).
2. Pull in any one-off entries from your existing `payroll_adjustments` table (bonuses, late fees, etc.) and `load_deductions`/`loans` if present.
3. Compute annual rent relief: 20% of annual rent paid, capped at ₦500,000 (Nigeria Tax Act 2025).
4. Compute Pension (8% employee / 10% employer of Basic Salary), NHF (2.5%), NHIS — each individually toggleable in `settings.php`.
5. Chargeable income = annual taxable earnings − rent relief − pension − NHF − NHIS.
6. Apply the progressive PAYE bands from `tax_bands` (0% to ₦800k, 15% to ₦3m, 18% to ₦12m, 21% to ₦25m, 23% to ₦50m, 25% above) to get annual PAYE, divided by 12 for the monthly deduction.
7. Net pay = gross earnings − (PAYE + Pension + NHF + NHIS + other deductions + loan deductions).

Everything (rates, thresholds, bands) lives in the database, not hardcoded — if the law changes again, update `settings.php` / add a new tax band year, no code changes needed.

## 4. Permissions

Pages check `$isAdmin` (defined in `includes/layout_header.php` as roles `admin`/`hr`/`finance` — **adjust this list to match your actual role names**). Managers (`$isManager`) can view reports scoped to their department. Employees can view only their own payslip via `payslip.php` (matched by `employees.user_id = $_SESSION['user_id']` — make sure that column is populated for every employee tied to a login).

## 5. Things you'll want to double check before going live

- `employees.user_id`: `payslip.php` uses this to let a logged-in employee see only their own slip. If this column doesn't exist/isn't populated yet, add it and back-fill it.
- Role names in `includes/layout_header.php` (`$isAdmin` list) — set to whatever your `users.role` values actually are.
- The `loans` table referenced in `PayrollEngine.php` is optional — if you don't have one yet, loan deductions are simply skipped (only `load_deductions` linked to a `loan_id` is used).
- Test one full cycle end-to-end in Mailtrap sandbox before switching to a live sending domain.
