keenops/php-nhiftz

PHP wrapper for the NHIF Tanzania ServiceHub and OCS APIs

v0.1.0 2026-05-18 04:27 UTC

Requires

• php: ^8.2
• guzzlehttp/guzzle: ^7.0
• psr/http-client: ^1.0
• psr/simple-cache: ^3.0

Requires (Dev)

• mockery/mockery: ^1.6
• pestphp/pest: ^3.0

MIT

• Kee Nops

• api
• sdk
• healthcare
• claims
• ocs
• tanzania
• nhif
• servicehub

README

A framework-agnostic PHP 8.2+ library for integrating with NHIF Tanzania's ServiceHub and OCS (Online Claims Submission) APIs.

Features

• Full coverage of NHIF ServiceHub API (Verification, Admissions, Approvals, Referrals, etc.)
• Full coverage of NHIF OCS API (Claims, Packages, Facilities, Reference)
• OAuth2 client credentials authentication with automatic token refresh
• PSR-18 HTTP client compatible (Guzzle included by default)
• PSR-16 cache support for token caching
• Laravel and Symfony framework integrations
• Strongly typed DTOs for request/response handling

Requirements

• PHP 8.2 or higher
• Guzzle HTTP client (or any PSR-18 compatible client)

Installation

composer require keenops/php-nhiftz

Quick Start

Basic Usage

use Keenops\PhpNhiftz\NhifClient;
use Keenops\PhpNhiftz\Config\Configuration;
use Keenops\PhpNhiftz\Config\Environment;

$config = new Configuration(
    clientId: 'your_client_id',
    clientSecret: 'your_client_secret',
    facilityCode: 'FAC001',
    environment: Environment::SANDBOX, // or Environment::PRODUCTION
);

$nhif = new NhifClient($config);
$nhif->setUsername('your_username');

// Verify a card
$response = $nhif->serviceHub()->verification()->getCardDetails('12345678');

if ($response->isSuccessful()) {
    $cardDetails = $response->json();
    // Process card details...
}

Card Verification with Biometrics

use Keenops\PhpNhiftz\DTOs\ServiceHub\VerifyCardModel;

$verification = new VerifyCardModel(
    cardNo: '12345678',
    verifierId: 'VER001',
    cardTypeId: '1',
    visitTypeId: 1,
    biometricMethod: 'fingerprint',
    fpCode: 'R1',
);

$response = $nhif->serviceHub()->verification()->verifyCard($verification);

Patient Admission

use Keenops\PhpNhiftz\DTOs\ServiceHub\PatientAdmissionModel;

$admission = new PatientAdmissionModel(
    authorizationNo: 'AUTH123',
    fullName: 'John Doe',
    gender: 'M',
    dateOfBirth: new DateTime('1990-01-15'),
    admissionTypeId: 1,
    wardTypeId: 2,
    roomTypeId: 1,
    chargesPerDay: 50000.00,
    practitionerNo: 'PRAC001',
    dateAdmitted: new DateTime(),
);

$response = $nhif->serviceHub()->admissions()->admitPatient($admission);

Claim Submission

use Keenops\PhpNhiftz\DTOs\OCS\Folio;
use Keenops\PhpNhiftz\DTOs\OCS\FolioItem;
use Keenops\PhpNhiftz\DTOs\OCS\FolioDisease;

$folio = new Folio(
    facilityCode: 'FAC001',
    claimYear: 2026,
    claimMonth: 3,
    folioNo: 1,
    cardNo: '12345678',
    firstName: 'John',
    lastName: 'Doe',
    gender: 'M',
    dateOfBirth: new DateTime('1990-01-15'),
    attendanceDate: new DateTime('2026-03-15'),
    authorizationNo: 'AUTH123',
    amountClaimed: 150000.00,
    folioItems: [
        new FolioItem(
            itemCode: 'ITEM001',
            unitPrice: 50000.00,
            itemQuantity: 3,
            amountClaimed: 150000.00,
        ),
    ],
    folioDiseases: [
        new FolioDisease(diseaseCode: 'A00'),
    ],
);

$response = $nhif->ocs()->claims()->submitFolio($folio);

Laravel Integration

Service Provider Registration

Add the service provider to your config/app.php (Laravel < 11) or it will be auto-discovered:

'providers' => [
    // ...
    Keenops\PhpNhiftz\Integrations\Laravel\NhifServiceProvider::class,
],

'aliases' => [
    // ...
    'Nhif' => Keenops\PhpNhiftz\Integrations\Laravel\NhifFacade::class,
],

Publish Configuration

php artisan vendor:publish --tag=nhif-config

Environment Variables

Add to your .env file:

NHIF_CLIENT_ID=your_client_id
NHIF_CLIENT_SECRET=your_client_secret
NHIF_FACILITY_CODE=FAC001
NHIF_ENVIRONMENT=sandbox
NHIF_SCOPE=onlineServices
NHIF_TIMEOUT=30

Username Resolver

The NHIF API requires a username for token authentication. Instead of calling setUsername() before every request, you can configure a username resolver that dynamically resolves the username (e.g., from the authenticated user).

Option 1: Class-based resolver (recommended, config-cache safe)

Create an invokable class:

// app/Nhif/StaffUsernameResolver.php
namespace App\Nhif;

use Keenops\PhpNhiftz\Contracts\UsernameResolverInterface;

class StaffUsernameResolver implements UsernameResolverInterface
{
    public function __invoke(): ?string
    {
        // Resolve username from your application's context
        return auth()->user()?->nhif_username;
    }
}

Then set it in config/nhif.php:

'username_resolver' => \App\Nhif\StaffUsernameResolver::class,

Option 2: Closure in AppServiceProvider

// app/Providers/AppServiceProvider.php
public function boot(): void
{
    app('nhif')->setUsernameResolver(function () {
        return auth()->user()?->nhif_username;
    });
}

Option 3: Manual (per-request)

Nhif::setUsername('username');

Usage with Facade

use Keenops\PhpNhiftz\Integrations\Laravel\NhifFacade as Nhif;

$response = Nhif::serviceHub()->verification()->getCardDetails('12345678');

Usage with Dependency Injection

use Keenops\PhpNhiftz\NhifClient;

class PatientController extends Controller
{
    public function verify(NhifClient $nhif, string $cardNo)
    {
        return $nhif->serviceHub()->verification()->getCardDetails($cardNo);
    }
}

Symfony Integration

Register the Bundle

// config/bundles.php
return [
    // ...
    Keenops\PhpNhiftz\Integrations\Symfony\NhifBundle::class => ['all' => true],
];

Configuration

# config/packages/nhif.yaml
nhif:
    client_id: '%env(NHIF_CLIENT_ID)%'
    client_secret: '%env(NHIF_CLIENT_SECRET)%'
    facility_code: '%env(NHIF_FACILITY_CODE)%'
    environment: '%env(NHIF_ENVIRONMENT)%'
    username_resolver: App\Nhif\StaffUsernameResolver  # Optional: service ID of an invokable class

Username Resolver

Register your resolver as a service, then reference it in the config:

// src/Nhif/StaffUsernameResolver.php
namespace App\Nhif;

use Keenops\PhpNhiftz\Contracts\UsernameResolverInterface;

class StaffUsernameResolver implements UsernameResolverInterface
{
    public function __invoke(): ?string
    {
        // Resolve username from your application's context
        return $this->security->getUser()?->getNhifUsername();
    }
}

Usage

use Keenops\PhpNhiftz\NhifClient;

class PatientController extends AbstractController
{
    public function __construct(private NhifClient $nhif) {}

    public function verify(string $cardNo): Response
    {
        $response = $this->nhif->serviceHub()->verification()->getCardDetails($cardNo);
        // ...
    }
}

Comprehensive Documentation

For detailed API documentation including all endpoints, parameters, payloads, and expected responses, see:

• ServiceHub API Documentation - Complete guide to all 9 ServiceHub services (~85 endpoints)
• OCS API Documentation - Complete guide to all 4 OCS services (28 endpoints)

Available Services

ServiceHub API

Service	Description	Endpoints
verification()	Card verification, member details, biometrics	18
admissions()	Patient admission, discharge, transfer	15
approvals()	Service authorization and approval requests	31
attendance()	Practitioner login/logout	2
history()	Patient visit history and medical records	3
issues()	Claim issues management	7
preApprovals()	Pre-approval service requests	6
reference()	Reference data (facilities, visit types, etc.)	4
referrals()	Service and treatment referrals	7

OCS API

Service	Description	Endpoints
claims()	Folio submission, signing, claim retrieval	9
facilities()	Facility listing	1
packages()	Price packages, benefit schemes, services	16
reference()	Disease codes, cache management	2

Error Handling

use Keenops\PhpNhiftz\Exceptions\AuthenticationException;
use Keenops\PhpNhiftz\Exceptions\ApiException;
use Keenops\PhpNhiftz\Exceptions\NetworkException;
use Keenops\PhpNhiftz\Exceptions\ValidationException;

try {
    $response = $nhif->serviceHub()->verification()->getCardDetails('12345678');
} catch (AuthenticationException $e) {
    // Handle authentication errors (invalid credentials, expired token)
} catch (ApiException $e) {
    // Handle API errors (4xx, 5xx responses)
    $statusCode = $e->getCode();
    $context = $e->getContext();
} catch (NetworkException $e) {
    // Handle network errors (connection failures, timeouts)
} catch (ValidationException $e) {
    // Handle validation errors
}

Custom HTTP Client

You can provide your own PSR-18 compatible HTTP client:

use GuzzleHttp\Client;

$httpClient = new Client([
    'timeout' => 60,
    'verify' => true,
]);

$nhif = new NhifClient($config, $httpClient);

Token Caching

Provide a PSR-16 compatible cache to persist tokens:

use Symfony\Component\Cache\Psr16Cache;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;

$cache = new Psr16Cache(new FilesystemAdapter());
$nhif = new NhifClient($config, null, $cache);

Testing

composer test

License

The MIT License (MIT). Please see License File for more information.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.