PHPackages                             essabu/essabu - 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. [API Development](/categories/api)
4. /
5. essabu/essabu

ActiveLibrary[API Development](/categories/api)

essabu/essabu
=============

Official PHP SDK for the Essabu platform - unified access to HR, Accounting, Identity, Trade, Payment, E-Invoice, Project, and Asset modules.

v0.1.1(3mo ago)00MITPHPPHP ^8.2CI passing

Since Apr 2Pushed 3mo agoCompare

[ Source](https://github.com/essabu/essabu-php)[ Packagist](https://packagist.org/packages/essabu/essabu)[ Docs](https://github.com/essabu/essabu-php)[ RSS](/packages/essabu-essabu/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (5)Versions (5)Used By (0)

Essabu PHP SDK
==============

[](#essabu-php-sdk)

[![Packagist Version](https://camo.githubusercontent.com/0e9c777e716dbb1828d6241c79fc178118658069a74e590ccbf9ec548f53463f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6573736162752f657373616275)](https://packagist.org/packages/essabu/essabu)[![License: MIT](https://camo.githubusercontent.com/08cef40a9105b6526ca22088bc514fbfdbc9aac1ddbf8d4e6c750e3a88a44dca/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d626c75652e737667)](LICENSE)[![PHP 8.2+](https://camo.githubusercontent.com/2795c86d2dea6aba6285347c2adef64310db832ec1d2d634a32e3b51115a5c95/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322532422d373737424234)](https://php.net/)[![PHPStan Level 5](https://camo.githubusercontent.com/3825ef93e62294aa6e3764cb8e5fb58ec5c476dae237b9a21907c8a4857e0717/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d4c6576656c253230352d627269676874677265656e)](https://phpstan.org/)

The official PHP SDK for the [Essabu](https://essabu.com) platform. It provides a single, fluent client that covers every Essabu service: **HR**, **Accounting**, **Identity**, **Trade**, **Payment**, **E-Invoice**, **Project**, and **Asset**. The SDK handles authentication, pagination, error mapping, and automatic retries with exponential backoff so you can focus on building your application. Whether you are working with Laravel, Symfony, or plain PHP, the SDK integrates seamlessly through its straightforward constructor API. Module clients and sub-APIs are accessed as properties, giving you a clean, readable call chain like `$essabu->hr->employees->list()`. The comprehensive exception hierarchy maps every HTTP error to a specific PHP exception, making error handling precise and predictable. Built on Guzzle for HTTP and PSR-3 for logging, the SDK follows modern PHP conventions and supports PHP 8.2+ with strict typing throughout.

---

Table of Contents
-----------------

[](#table-of-contents)

- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Framework Integration](#framework-integration)
- [Modules](#modules)
    - [HR](#hr)
    - [Accounting](#accounting)
    - [Identity](#identity)
    - [Trade](#trade)
    - [Payment](#payment)
    - [E-Invoice](#e-invoice)
    - [Project](#project)
    - [Asset](#asset)
- [Pagination](#pagination)
- [Error Handling](#error-handling)
- [Retry Behavior](#retry-behavior)
- [Webhook Handling](#webhook-handling)
- [Examples](#examples)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#license)

---

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

[](#requirements)

- PHP 8.2+
- Composer
- An Essabu API key ([Dashboard](https://app.essabu.com) > Settings > API Keys)

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

[](#installation)

Install the SDK via Composer. This pulls in Guzzle and all required dependencies automatically. Requires PHP 8.2 or higher.

```
composer require essabu/essabu
```

Quick Start
-----------

[](#quick-start)

The following example demonstrates how to initialize the SDK and perform basic operations across all eight modules. Pass your API key and tenant ID to the constructor. Each module is accessed as a property on the client, and each sub-API is accessed as a property on the module. All create methods return the created resource as an associative array with a generated `id`. Throws `AuthenticationException` if the API key is invalid, or `ValidationException` if required fields are missing.

```
use Essabu\Essabu;
use Essabu\Common\Model\PageRequest;

$essabu = new Essabu('ess_live_xxxxxxxxxxxx', 'your-tenant-uuid');

// ----- HR -----
$employee = $essabu->hr->employees->create([
    'firstName' => 'Jean', 'lastName' => 'Mukendi', 'email' => 'jean@company.com',
]);

// ----- Accounting -----
$invoice = $essabu->accounting->invoices->create([
    'customerId' => 'cust-001',
    'lines' => [['description' => 'Consulting', 'quantity' => 10, 'unitPrice' => 150.00]],
]);
$essabu->accounting->invoices->finalize($invoice['id']);
$essabu->accounting->invoices->send($invoice['id']);

// ----- Identity -----
$tokens = $essabu->identity->auth->login([
    'email' => 'admin@company.com', 'password' => 'password',
]);

// ----- Trade -----
$customer = $essabu->trade->customers->create([
    'name' => 'Acme Corp', 'email' => 'contact@acme.com',
]);

// ----- Payment -----
$intent = $essabu->payment->paymentIntents->create([
    'amount' => 5000, 'currency' => 'USD', 'customerId' => $customer['id'],
]);
$essabu->payment->paymentIntents->confirm($intent['id']);

// ----- E-Invoice -----
$submission = $essabu->eInvoice->submissions->submit([
    'invoiceId' => $invoice['id'], 'buyerTin' => '123456789',
]);

// ----- Project -----
$project = $essabu->project->projects->create([
    'name' => 'Website Redesign', 'startDate' => '2026-04-01',
]);

// ----- Asset -----
$vehicle = $essabu->asset->vehicles->create([
    'make' => 'Toyota', 'model' => 'Hilux', 'year' => 2025, 'licensePlate' => 'ABC-1234',
]);
```

Configuration
-------------

[](#configuration)

Customize the SDK behavior by passing an options array as the third constructor argument. You can override the base URL (useful for staging environments), adjust the request timeout, set the number of automatic retries for transient errors, and specify the API version. All options are optional and default to production-ready values.

```
$essabu = new Essabu('api-key', 'tenant-id', [
    'baseUrl'    => 'https://api.essabu.com',  // default
    'timeout'    => 30,                          // seconds (default: 30)
    'retries'    => 3,                           // retry count for 429/5xx (default: 3)
    'apiVersion' => 'v1',                        // API version (default: v1)
]);
```

OptionTypeDefaultDescription`baseUrl``string``https://api.essabu.com`API base URL`timeout``int``30`Request timeout in seconds`retries``int``3`Max retries for 429/5xx errors`apiVersion``string``v1`API versionFramework Integration
---------------------

[](#framework-integration)

### Laravel

[](#laravel)

Register the Essabu client as a singleton in your `AppServiceProvider`. This ensures a single client instance is reused across all service injections. The API key and tenant ID are read from your `config/services.php` configuration.

```
$this->app->singleton(Essabu::class, fn () => new Essabu(
    config('services.essabu.api_key'),
    config('services.essabu.tenant_id'),
    ['baseUrl' => config('services.essabu.base_url', 'https://api.essabu.com')],
));
```

Add the Essabu service credentials to `config/services.php`. The values are read from environment variables so that secrets are never committed to version control.

```
'essabu' => [
    'api_key'   => env('ESSABU_API_KEY'),
    'tenant_id' => env('ESSABU_TENANT_ID'),
    'base_url'  => env('ESSABU_BASE_URL', 'https://api.essabu.com'),
],
```

Inject the `Essabu` client into any service or controller via constructor injection. Laravel resolves the singleton automatically. All module methods are available through the fluent property chain.

```
class InvoiceService
{
    public function __construct(private Essabu $essabu) {}

    public function create(array $data): array
    {
        return $this->essabu->accounting->invoices->create($data);
    }
}
```

### Symfony

[](#symfony)

Register the Essabu client as a service in `config/services.yaml`. The API key and tenant ID are injected from environment variables. Optional parameters like `baseUrl` and `timeout` can be configured under the `$options` argument.

```
services:
    Essabu\Essabu:
        arguments:
            $apiKey: '%env(ESSABU_API_KEY)%'
            $tenantId: '%env(ESSABU_TENANT_ID)%'
            $options:
                baseUrl: '%env(default::ESSABU_BASE_URL)%'
                timeout: 30
```

Modules
-------

[](#modules)

### HR

[](#hr)

`$essabu->hr` -- Comprehensive human resource management.

Sub-APIAccessorHighlightsEmployees`->employees`CRUD, terminate, reinstateContracts`->contracts`CRUD, renew, terminateLeaves`->leaves`CRUD, approve/reject, balancePayroll`->payrolls`CRUD, calculate, approve, payslipsAttendance`->attendances`CRUD, clockIn/clockOutRecruitment`->recruitments`CRUD, shortlist, hirePerformance`->performances`CRUD, submit reviewTraining`->trainings`CRUD, enroll, completePlus: Shifts, Departments, Documents, Benefits, Loans, Timesheets, Skills, Onboarding, Expenses, Disciplinary, Config, Reports, Webhooks, History.

[Full reference on the Wiki](https://github.com/essabu/essabu-php/wiki/HR-Module)

### Accounting

[](#accounting)

`$essabu->accounting` -- Complete financial management.

Sub-APIAccessorHighlightsInvoices`->invoices`CRUD, finalize, send, void, PDFPayments`->payments`CRUD, reconcileJournals`->journals`CRUD, post, reverseQuotes`->quotes`CRUD, accept, reject, convert to invoiceReports`->reports`Balance sheet, P&L, trial balance, cash flowInventory`->inventory`CRUD, adjustPlus: Accounts, Wallets, Credit Notes, Tax Rates, Currencies, Fiscal Years, Insurance, Coupons, Config, Webhooks.

[Full reference on the Wiki](https://github.com/essabu/essabu-php/wiki/Accounting-Module)

### Identity

[](#identity)

`$essabu->identity` -- Authentication and access control.

Sub-APIAccessorHighlightsAuth`->auth`Login, register, 2FA, password resetUsers`->users`CRUD, assign/remove roles, activate/deactivateRoles`->roles`CRUD, assign permissionsAPI Keys`->apiKeys`CRUD, rotate, revokeProfile`->profile`me, updateMe, changePasswordPlus: Permissions, Tenants, Companies, Branches, Sessions.

[Full reference on the Wiki](https://github.com/essabu/essabu-php/wiki/Identity-Module)

### Trade

[](#trade)

`$essabu->trade` -- CRM, sales, purchasing, and inventory.

Sub-APIAccessorHighlightsCustomers`->customers`CRUDOpportunities`->opportunities`CRUD, won, lostSales Orders`->salesOrders`CRUD, confirm, cancel, fulfillProducts`->products`CRUDStocks`->stocks`CRUD, transfer, adjustContracts`->contracts`CRUD, sign, renewPlus: Contacts, Suppliers, Purchase Orders, Campaigns, Documents, Warehouses, Deliveries, Receipts, Activities, Reports.

[Full reference on the Wiki](https://github.com/essabu/essabu-php/wiki/Trade-Module)

### Payment

[](#payment)

`$essabu->payment` -- Payment processing and lending.

Sub-APIAccessorHighlightsPayment Intents`->paymentIntents`CRUD, confirm, capture, cancelSubscriptions`->subscriptions`CRUD, cancel, resume, change planLoan Applications`->loanApplications`CRUD, approve, reject, disburseKYC`->kyc`CRUD, verify, submit documentsPlus: Transactions, Refunds, Loan Products, Collaterals, Financial Accounts, Reports.

[Full reference on the Wiki](https://github.com/essabu/essabu-php/wiki/Payment-Module)

### E-Invoice

[](#e-invoice)

`$essabu->eInvoice` -- Electronic invoicing and tax compliance.

Sub-APIAccessorHighlightsInvoices`->invoices`CRUD, sign, XML downloadSubmissions`->submissions`CRUD, submit, get statusVerifications`->verifications`CRUD, verifyCompliance`->compliance`Check, get rulesStatistics`->statistics`Overview[Full reference on the Wiki](https://github.com/essabu/essabu-php/wiki/EInvoice-Module)

### Project

[](#project)

`$essabu->project` -- Project and task management.

Sub-APIAccessorHighlightsProjects`->projects`CRUD, archive, timelineTasks`->tasks`CRUD, assign, complete, log timeMilestones`->milestones`CRUD, completeTask Comments`->taskComments`CRUDReports`->reports`BurndownPlus: Resource Allocations.

[Full reference on the Wiki](https://github.com/essabu/essabu-php/wiki/Project-Module)

### Asset

[](#asset)

`$essabu->asset` -- Asset and fleet management.

Sub-APIAccessorHighlightsAssets`->assets`CRUD, assign, disposeVehicles`->vehicles`CRUDMaintenance Logs`->maintenanceLogs`CRUD, completeMaintenance Schedules`->maintenanceSchedules`CRUDDepreciation`->depreciations`Calculate, scheduleFuel Logs`->fuelLogs`CRUDTrip Logs`->tripLogs`CRUD[Full reference on the Wiki](https://github.com/essabu/essabu-php/wiki/Asset-Module)

Pagination
----------

[](#pagination)

Use `PageRequest` to control pagination, filtering, and sorting on any `list` method. Pass the page number, items per page, an optional search string, sort field, sort direction, and key-value filters. The returned `PageResponse` object contains `page`, `totalPages`, `totalItems`, and the `items` array. Throws `BadRequestException` if invalid filter keys are provided.

```
use Essabu\Common\Model\PageRequest;

$request = new PageRequest(
    page: 2,
    itemsPerPage: 50,
    search: 'Kinshasa',
    orderBy: 'createdAt',
    direction: 'desc',
    filters: ['status' => 'active'],
);

$page = $essabu->hr->employees->list($request);

echo "Page {$page->page} of {$page->totalPages}\n";
echo "Total: {$page->totalItems}\n";

foreach ($page->items as $employee) {
    echo "{$employee['firstName']} {$employee['lastName']}\n";
}
```

To iterate through all pages of a paginated result set, increment the page counter in a loop until you reach `totalPages`. Each iteration fetches one page of results. This pattern works with any `list` method across all modules.

```
$page = 1;
do {
    $result = $essabu->hr->employees->list(new PageRequest(page: $page, itemsPerPage: 50));
    foreach ($result->items as $employee) {
        process($employee);
    }
    $page++;
} while ($page totalPages);
```

Error Handling
--------------

[](#error-handling)

The SDK maps every HTTP error status to a specific exception class. Catch them from most specific to most general. `ValidationException` provides field-level errors via `getErrors()`. `RateLimitException` includes a `getRetryAfter()` method indicating how many seconds to wait. The base `EssabuException` exposes `getHttpStatusCode()` and `getContext()` for debugging.

```
use Essabu\Common\Exception\{
    AuthenticationException,
    AuthorizationException,
    ValidationException,
    NotFoundException,
    RateLimitException,
    ServerException,
    EssabuException,
};

try {
    $essabu->hr->employees->create([...]);
} catch (ValidationException $e) {
    // 422 - Business rule violation
    echo $e->getMessage();
    print_r($e->getErrors());  // field-level errors
} catch (AuthenticationException $e) {
    // 401 - Invalid API key
} catch (AuthorizationException $e) {
    // 403 - Insufficient permissions
} catch (NotFoundException $e) {
    // 404 - Resource not found
} catch (RateLimitException $e) {
    // 429 - Rate limit exceeded
    $retryAfter = $e->getRetryAfter(); // seconds
} catch (ServerException $e) {
    // 5xx - Server error (after retries)
} catch (EssabuException $e) {
    // Catch-all
    echo $e->getHttpStatusCode();
    print_r($e->getContext());
}
```

ExceptionHTTP StatusWhen`BadRequestException`400Malformed request`AuthenticationException`401Invalid or expired API key/token`AuthorizationException`403Insufficient permissions`NotFoundException`404Resource not found`ValidationException`422Business rule violation`RateLimitException`429Rate limit exceeded`ServerException`5xxServer-side errorRetry Behavior
--------------

[](#retry-behavior)

The SDK automatically retries **429** (rate limit) and **5xx** (server error) responses with exponential backoff:

- **Max retries**: 3 (configurable via `retries` option)
- **Initial delay**: 500ms, doubling each attempt (500ms, 1s, 2s)
- **4xx errors** (except 429) are **never retried**

Webhook Handling
----------------

[](#webhook-handling)

### Laravel

[](#laravel-1)

Handle incoming Essabu webhooks in a Laravel controller. Verify the request signature using the `X-Essabu-Signature` header and your webhook secret. Parse the payload to extract the event type and data, then route to the appropriate handler. Returns a 401 response if the signature is invalid. The `EssabuWebhook::verify()` method uses HMAC-SHA256 to validate payload integrity.

```
use Essabu\Webhook\EssabuWebhook;

class WebhookController extends Controller
{
    public function handle(Request $request): Response
    {
        $payload = $request->getContent();
        $signature = $request->header('X-Essabu-Signature');

        if (!EssabuWebhook::verify($payload, $signature, config('services.essabu.webhook_secret'))) {
            return response('Invalid signature', 401);
        }

        $event = EssabuWebhook::parse($payload);

        match ($event['type']) {
            'invoice.paid' => $this->handleInvoicePaid($event['data']),
            'employee.created' => $this->handleEmployeeCreated($event['data']),
            'payment_intent.confirmed' => $this->handlePaymentConfirmed($event['data']),
            default => logger()->info("Unhandled event: {$event['type']}"),
        };

        return response('OK', 200);
    }
}
```

### Symfony

[](#symfony-1)

Handle incoming Essabu webhooks in a Symfony controller. The same verification and parsing logic applies. Extract the payload from the `Request` object, verify the signature header against your webhook secret stored in an environment variable, then process the event. Returns a 401 `Response` if verification fails.

```
#[Route('/webhooks/essabu', methods: ['POST'])]
public function handle(Request $request): Response
{
    $payload = $request->getContent();
    $signature = $request->headers->get('X-Essabu-Signature');

    if (!EssabuWebhook::verify($payload, $signature, $_ENV['ESSABU_WEBHOOK_SECRET'])) {
        return new Response('Invalid signature', 401);
    }

    $event = EssabuWebhook::parse($payload);
    // Process event...

    return new Response('OK', 200);
}
```

Examples
--------

[](#examples)

ExampleFileDescriptionBasic Usage[`01-basic-usage.php`](examples/01-basic-usage.php)Client init, basic CRUDAuthentication[`02-authentication.php`](examples/02-authentication.php)Login, tokens, 2FAInvoicing[`03-invoicing.php`](examples/03-invoicing.php)Create, finalize, send invoicesPayroll[`04-payroll.php`](examples/04-payroll.php)Payroll runs and payslipsTrade / CRM[`05-trade-crm.php`](examples/05-trade-crm.php)Customers, opportunities, ordersPayments[`06-payments.php`](examples/06-payments.php)Payment intents, subscriptionsError Handling[`07-error-handling.php`](examples/07-error-handling.php)Exception handling patternsProject Management[`08-project-management.php`](examples/08-project-management.php)Projects, tasks, milestonesSee the full [examples/](examples/) directory and the [Wiki Examples page](https://github.com/essabu/essabu-php/wiki/Examples) for more.

Testing
-------

[](#testing)

Run the test suite using PHPUnit. All tests are located in the `tests/` directory and cover unit, integration, and mock-based HTTP scenarios.

```
composer install
./vendor/bin/phpunit
```

Run PHPStan static analysis at level 5 to check for type errors, undefined methods, and other code quality issues across the `src/` directory.

```
./vendor/bin/phpstan analyse src --level 5
```

Contributing
------------

[](#contributing)

1. Fork the repository
2. Create a feature branch (`git checkout -b feat/my-feature`)
3. Commit your changes (`git commit -m 'feat: add my feature'`)
4. Push to the branch (`git push origin feat/my-feature`)
5. Open a Pull Request

Please follow [Conventional Commits](https://www.conventionalcommits.org/) for commit messages.

License
-------

[](#license)

MIT -- see [LICENSE](LICENSE) for details.

###  Health Score

33

—

LowBetter than 72% of packages

Maintenance82

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity39

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% 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

Every ~0 days

Total

3

Last Release

91d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/843d5df83989b3984d8152f919ad4936fc3b3a4c997934a915dfcc741059a5e4?d=identicon)[cmukanisa](/maintainers/cmukanisa)

---

Top Contributors

[![cmukanisa](https://avatars.githubusercontent.com/u/26385000?v=4)](https://github.com/cmukanisa "cmukanisa (14 commits)")

---

Tags

apisdkbillinghrsaasAccountingessabu

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/essabu-essabu/health.svg)

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

###  Alternatives

[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k14](/packages/tempest-framework)[avalara/avataxclient

Client library for Avalara's AvaTax suite of business tax calculation and processing services. Uses the REST v2 API.

528.5M7](/packages/avalara-avataxclient)[theodo-group/llphant

LLPhant is a library to help you build Generative AI applications.

1.7k409.0k6](/packages/theodo-group-llphant)[resend/resend-php

Resend PHP library.

617.2M42](/packages/resend-resend-php)[keboola/storage-api-client

Keboola Storage API PHP Client

10405.9k38](/packages/keboola-storage-api-client)[bushlanov-dev/max-bot-api-client-php

Max Bot API Client library

486.3k](/packages/bushlanov-dev-max-bot-api-client-php)

PHPackages © 2026

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