PHPackages                             azaharizaman/nexus-payroll - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. azaharizaman/nexus-payroll

ActiveLibrary[Utility & Helpers](/categories/utility)

azaharizaman/nexus-payroll
==========================

Country-agnostic atomic payroll engine for Nexus ERP

v0.1.0-alpha1(2mo ago)012MITPHPPHP ^8.3

Since May 5Pushed 2mo agoCompare

[ Source](https://github.com/azaharizaman/nexus-payroll)[ Packagist](https://packagist.org/packages/azaharizaman/nexus-payroll)[ RSS](/packages/azaharizaman-nexus-payroll/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependenciesVersions (2)Used By (2)

Nexus Payroll Package
=====================

[](#nexus-payroll-package)

Country-agnostic atomic payroll engine for Nexus ERP.

Features
--------

[](#features)

- **Country-Agnostic Core**: No statutory logic in core package
- **Plug-and-Play Statutory Modules**: Country-specific calculations via `StatutoryCalculatorInterface`
- **Flexible Component System**: Configurable earnings, deductions, and contributions
- **Bulk Processing**: Efficient payroll runs for entire departments or companies
- **Comprehensive Payslip Generation**: Detailed breakdown with audit trails
- **Framework-Agnostic Design**: Pure PHP business logic

Architecture
------------

[](#architecture)

This package is designed to be **completely country-agnostic**. All statutory calculations (tax, social security, pension contributions, etc.) are delegated to external implementations of `StatutoryCalculatorInterface`.

### Example: Malaysia Statutory Package

[](#example-malaysia-statutory-package)

```
// Separate package: azaharizaman/nexus-payroll-mys-statutory
class MalaysiaStatutoryCalculator implements StatutoryCalculatorInterface
{
    public function calculate(PayloadInterface $payload): DeductionResultInterface
    {
        // EPF, SOCSO, EIS, PCB tax calculations specific to Malaysia
    }
}
```

### Package Structure

[](#package-structure)

```
src/
├── Contracts/              # Interfaces for all payroll entities
├── Services/               # Country-agnostic business logic
├── ValueObjects/           # Immutable domain value objects
└── Exceptions/             # Domain-specific exceptions

```

Installation
------------

[](#installation)

```
composer require azaharizaman/nexus-payroll
```

For country-specific statutory calculations:

```
# Malaysia
composer require azaharizaman/nexus-payroll-mys-statutory

# Singapore
composer require azaharizaman/nexus-payroll-sgp-statutory
```

Usage
-----

[](#usage)

### Payroll Processing

[](#payroll-processing)

```
use Nexus\Payroll\Services\PayrollEngine;

$payrollEngine = app(PayrollEngine::class);

// Process payroll for specific period
$payslips = $payrollEngine->processPeriod(
    tenantId: $tenantId,
    periodStart: '2025-01-01',
    periodEnd: '2025-01-31',
    filters: ['department_id' => $departmentId]
);
```

### Component Management

[](#component-management)

```
use Nexus\Payroll\Services\ComponentManager;

$componentManager = app(ComponentManager::class);

// Create earnings component
$basicSalaryComponent = $componentManager->createComponent([
    'name' => 'Basic Salary',
    'code' => 'BASIC',
    'type' => 'earning',
    'calculation_method' => 'fixed',
]);

// Create deduction component
$loanDeduction = $componentManager->createComponent([
    'name' => 'Loan Deduction',
    'code' => 'LOAN',
    'type' => 'deduction',
    'calculation_method' => 'fixed_amount',
]);
```

### Statutory Calculator Registration

[](#statutory-calculator-registration)

```
// In your application service provider
use Nexus\Payroll\Contracts\StatutoryCalculatorInterface;
use App\Payroll\MalaysiaStatutoryCalculator;

$this->app->singleton(StatutoryCalculatorInterface::class, function ($app) {
    return new MalaysiaStatutoryCalculator(
        epfRate: 0.11,
        employerEpfRate: 0.13,
        // ... other Malaysian statutory rates
    );
});
```

Key Contracts
-------------

[](#key-contracts)

### StatutoryCalculatorInterface

[](#statutorycalculatorinterface)

The core interface for country-specific implementations:

```
interface StatutoryCalculatorInterface
{
    public function calculate(PayloadInterface $payload): DeductionResultInterface;
    public function getSupportedCountryCode(): string;
    public function getRequiredEmployeeFields(): array;
}
```

### PayloadInterface

[](#payloadinterface)

Input data structure for statutory calculations:

```
interface PayloadInterface
{
    public function getEmployeeId(): string;
    public function getGrossPay(): float;
    public function getTaxableIncome(): float;
    public function getMetadata(): array;
}
```

### DeductionResultInterface

[](#deductionresultinterface)

Output structure from statutory calculations:

```
interface DeductionResultInterface
{
    public function getTotalDeductions(): float;
    public function getBreakdown(): array;
    public function getEmployerContributions(): array;
}
```

Requirements
------------

[](#requirements)

- PHP 8.3 or higher
- Integration with `Nexus\Hrm` for employee data
- Integration with `Nexus\Accounting` for GL posting

---

📖 Documentation
---------------

[](#-documentation)

### Package Documentation

[](#package-documentation)

- **[Getting Started Guide](docs/getting-started.md)** - Quick start guide with prerequisites, concepts, and first integration
- **[API Reference](docs/api-reference.md)** - Complete documentation of all interfaces, value objects, and exceptions
- **[Integration Guide](docs/integration-guide.md)** - Laravel and Symfony integration examples
- **[Basic Usage Example](docs/examples/basic-usage.php)** - Simple usage patterns
- **[Advanced Usage Example](docs/examples/advanced-usage.php)** - Advanced scenarios and patterns

### Additional Resources

[](#additional-resources)

- `IMPLEMENTATION_SUMMARY.md` - Implementation progress and metrics
- `REQUIREMENTS.md` - Detailed requirements
- `TEST_SUITE_SUMMARY.md` - Test coverage and results
- `VALUATION_MATRIX.md` - Package valuation metrics
- See root `ARCHITECTURE.md` for overall system architecture

---

License
-------

[](#license)

MIT License - see LICENSE file for details.

###  Health Score

34

—

LowBetter than 75% of packages

Maintenance84

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity35

Early-stage or recently created project

 Bus Factor1

Top contributor holds 76.6% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

81d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/117408?v=4)[Azahari Zaman](/maintainers/azaharizaman)[@azaharizaman](https://github.com/azaharizaman)

---

Top Contributors

[![azaharizaman](https://avatars.githubusercontent.com/u/117408?v=4)](https://github.com/azaharizaman "azaharizaman (461 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (139 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 commits)")

### Embed Badge

![Health badge](/badges/azaharizaman-nexus-payroll/health.svg)

```
[![Health](https://phpackages.com/badges/azaharizaman-nexus-payroll/health.svg)](https://phpackages.com/packages/azaharizaman-nexus-payroll)
```

###  Alternatives

[xxh/think-wxminihelper

weixin mini program helper

1561.2k](/packages/xxh-think-wxminihelper)[aryelds/yii2-sweet-alert

A widget to flash sweet alert messages using SweetAlert plugin

3017.5k](/packages/aryelds-yii2-sweet-alert)[barrelstrength/sprout-seo

1133.8k1](/packages/barrelstrength-sprout-seo)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)