kiriminaja / kiriminaja-php

2.1.6 2026-10-06 02:48 UTC

Requires

• php: >=8.1
• ext-json: *
• nyholm/psr7: ^1.8
• php-http/curl-client: ^2.4

Requires (Dev)

• brianium/paratest: ^7.3 <7.9
• illuminate/config: ^10.0||^11.0||^12.0
• illuminate/container: ^10.0||^11.0||^12.0
• illuminate/contracts: ^10.0||^11.0||^12.0
• illuminate/support: ^10.0||^11.0||^12.0
• mockery/mockery: ^1.6

Suggests

• codeigniter4/framework: Required for the CodeIgniter 4 cache adapter and bootstrap helper
• illuminate/contracts: Required for Laravel cache store integration
• illuminate/support: Required for Laravel service provider integration

MIT

• Daewu Bintara
• Yanuar Aditia

• fulfillment
• cod
• kiriminaja
• kirimin aja
• shipment aggregator

Published on Packagist.org on 2026-10-06 02:54 UTC

README

Official PHP SDK for the KiriminAja logistics API.

Requirements

• PHP 8.1+
• ext-json

Installation

composer require kiriminaja/kiriminaja-php

Quick Start

Call KiriminAjaConfig once at app startup, then call any service method on the KiriminAja facade.

use KiriminAja\Base\Config\KiriminAjaConfig;
use KiriminAja\Base\Config\Cache\Mode;
use KiriminAja\Services\KiriminAja;

KiriminAjaConfig::setMode(Mode::Staging)::setApiTokenKey('YOUR_API_KEY');

// Use any service
$provinces = KiriminAja::getProvince();

Config Options

Method	Description
KiriminAjaConfig::setMode($mode)	Mode::Staging or Mode::Production
KiriminAjaConfig::setApiTokenKey($key)	Your KiriminAja API key
KiriminAjaConfig::setBaseUrl($url)	Custom base URL (useful for proxy or self-hosted)
KiriminAjaConfig::setCacheDirectory($path)	Custom cache directory (useful if /tmp is not writable)
KiriminAjaConfig::disableCache()	Disable file-based caching entirely

// Custom cache directory
KiriminAjaConfig::setCacheDirectory(__DIR__ . '/kiriminaja-cache');

// Or disable caching entirely
KiriminAjaConfig::disableCache();

KiriminAjaConfig::setMode(Mode::Production)::setApiTokenKey('YOUR_API_KEY');

Custom Base URL

If you need to route requests through a proxy or custom endpoint, set a custom base URL. This overrides the default URL resolved from the mode.

KiriminAjaConfig::setMode(Mode::Production)
    ::setApiTokenKey('YOUR_API_KEY')
    ::setBaseUrl('https://proxy.example.com');

Laravel Integration

The SDK auto-registers via Laravel package discovery — no manual provider registration needed.

1. Add to config/services.php

'kiriminaja' => [
    'mode' => env('KIRIMINAJA_MODE', 'staging'),
    'api_key' => env('KIRIMINAJA_API_KEY', ''),
    'base_url' => env('KIRIMINAJA_BASE_URL'),
    'cache_store' => env('KIRIMINAJA_CACHE_STORE', 'laravel'),
    'cache_prefix' => env('KIRIMINAJA_CACHE_PREFIX', 'kiriminaja:'),
],

2. Add to your .env

KIRIMINAJA_MODE=staging
KIRIMINAJA_API_KEY=your-api-key-here

3. Use the SDK anywhere

use KiriminAja\Services\KiriminAja;

$provinces = KiriminAja::getProvince();

Config Reference (services.kiriminaja)

Key	Env Variable	Default	Description
mode	KIRIMINAJA_MODE	staging	staging or production
api_key	KIRIMINAJA_API_KEY	""	Your KiriminAja API key
base_url	KIRIMINAJA_BASE_URL	null	Custom base URL (overrides mode-based URL)
cache_store	KIRIMINAJA_CACHE_STORE	laravel	laravel (uses Laravel Cache) or file (file-based)
cache_prefix	KIRIMINAJA_CACHE_PREFIX	kiriminaja:	Cache key prefix (Laravel store only)

CodeIgniter 4 Integration

CodeIgniter 4 doesn't auto-discover Composer packages, so you wire the SDK up once during boot.

1. Publish the config

Create app/Config/KiriminAja.php:

<?php

namespace Config;

use CodeIgniter\Config\BaseConfig;
use KiriminAja\Base\Config\Cache\Mode;

class KiriminAja extends BaseConfig
{
    public string $mode = Mode::Staging;          // or Mode::Production
    public string $apiKey = '';
    public ?string $baseUrl = null;
    public string $cacheStore = 'codeigniter';    // or 'file'
    public string $cachePrefix = 'kiriminaja:';
}

2. Bootstrap from app/Config/Events.php

use CodeIgniter\Events\Events;
use KiriminAja\CodeIgniter\KiriminAjaBootstrap;
use Config\Services;

Events::on('pre_system', static function () {
    KiriminAjaBootstrap::boot(config('KiriminAja'), Services::cache());
});

3. Use the SDK anywhere

use KiriminAja\Services\KiriminAja;

$provinces = KiriminAja::getProvince();

Config Reference (Config\KiriminAja)

Property	Default	Description
mode	staging	staging or production
apiKey	""	Your KiriminAja API key
baseUrl	null	Custom base URL (overrides mode-based URL)
cacheStore	codeigniter	codeigniter (uses CI4 cache service) or file (file-based)
cachePrefix	kiriminaja:	Cache key prefix (codeigniter store only)

The bootstrap helper also accepts a plain associative array — handy for tests or non-conventional setups: KiriminAjaBootstrap::boot(['mode' => 'staging', 'api_key' => '...'], $cache);

Services

Address

// List all provinces
KiriminAja::getProvince();

// Cities in a province (province_id)
KiriminAja::getCity(5);

// Districts in a city (city_id)
KiriminAja::getDistrict(12);

// Sub-districts in a district (kecamatan_id)
KiriminAja::getSubDistrict(77);

// Search districts by name
KiriminAja::getDistrictByName("jakarta");

Coverage Area & Pricing

use KiriminAja\Models\ShippingPriceData;
use KiriminAja\Models\ShippingPriceInstantData;
use KiriminAja\Models\ShippingFullPriceData;

// Express shipping rates
$data = new ShippingPriceData();
$data->origin = 1;
$data->destination = 2;
$data->weight = 1000;       // grams
$data->item_value = 50000;
$data->insurance = 0;
$data->courier = ['jne', 'jnt'];

KiriminAja::getPrice($data);

// Instant (same-day) rates
$data = new ShippingPriceInstantData();
$data->service = ['grab_express', 'gosend'];
$data->item_price = 10000;
$data->origin = ['lat' => -6.2, 'long' => 106.8, 'address' => 'Jl. Sudirman No.1'];
$data->destination = ['lat' => -6.21, 'long' => 106.81, 'address' => 'Jl. Thamrin No.5'];
$data->weight = 1000;
$data->vehicle = 'motor';       // 'motor' or 'mobil'
$data->timezone = 'Asia/Jakarta';

KiriminAja::getPriceInstant($data);

// Full shipping price (all available couriers)
$data = new ShippingFullPriceData();
$data->origin = 1;
$data->destination = 2;
$data->weight = 1000;

KiriminAja::fullShippingPrice($data);

Order — Express

use KiriminAja\Models\RequestPickupData;
use KiriminAja\Models\PackageData;
use KiriminAja\Models\PackageItemData;
use KiriminAja\Models\PackageItemMetadata;

// Track by order ID
KiriminAja::getTracking("ORDER123");

// Cancel shipment
KiriminAja::cancelShipment("AWB123456", "Customer request");

// Request pickup
$pickup = new RequestPickupData();
$pickup->address = "Jl. Jodipati No.29";
$pickup->phone = "08133345678";
$pickup->name = "Tokotries";
$pickup->kecamatan_id = 548;
$pickup->schedule = "2024-01-15 17:00:00";
$pickup->platform_name = "mitra";

$package = new PackageData();
$package->order_id = "YGL-000000019";
$package->destination_name = "Flag Test";
$package->destination_phone = "082223323333";
$package->destination_address = "Jl. Magelang KM 11";
$package->destination_kecamatan_id = 548;
$package->weight = 520;
$package->width = 8;
$package->height = 8;
$package->length = 8;
$package->item_value = 275000;
$package->shipping_cost = 65000;
$package->service = "jne";
$package->service_type = "REG";
$package->item_name = "Test item";
$package->package_type_id = 1;
$package->cod = 0;

// `items` is optional. When provided, it lists the individual items
// contained in the package. `item_value` is still required.
$item = new PackageItemData();
$item->name = "Kaos Polos";
$item->price = 125000;
$item->qty = 2;
$item->weight = 260;
$item->width = 4;
$item->length = 4;
$item->height = 4;
$item->metadata = new PackageItemMetadata();
$item->metadata->sku = "KP-001";
$item->metadata->variant_label = "Merah / L";
$package->items = [$item];

$pickup->packages->add($package);
KiriminAja::requestPickup($pickup);

// Pickup schedules
KiriminAja::getSchedules();

Order — Instant

use KiriminAja\Models\RequestPickupInstantData;
use KiriminAja\Models\PackageInstantData;

// Request instant pickup
$pickup = new RequestPickupInstantData();
$pickup->service = "gosend";
$pickup->service_type = "instant";
$pickup->vehicle = "motor";
$pickup->order_prefix = "BDI";

$package = new PackageInstantData();
$package->origin_name = "Rizky";
$package->origin_phone = "081280045616";
$package->origin_lat = -7.854584;
$package->origin_long = 110.331154;
$package->origin_address = "Wirobrajan, Yogyakarta";
$package->origin_address_note = "Dekat Kantor";
$package->destination_name = "Okka";
$package->destination_phone = "081280045616";
$package->destination_lat = -7.776192;
$package->destination_long = 110.325053;
$package->destination_address = "Godean, Sleman";
$package->destination_address_note = "Dekat Pasar";
$package->shipping_price = 34000;
$package->item_name = "Barang 1";
$package->item_description = "Barang 1 Description";
$package->item_price = 20000;
$package->item_weight = 1000;     // grams

KiriminAja::requestPickupInstant($pickup, $package);

// Track instant order
KiriminAja::getTrackingInstant("ORDER123");

// Find a new driver for an existing order
KiriminAja::findNewDriver("ORDER123");

// Cancel instant order
KiriminAja::cancelShipment("ORDER123", "", isInstant: true);

Courier

// List available couriers
KiriminAja::getCouriers();

// Courier groups
KiriminAja::getCourierGroups();

// Courier detail by code
KiriminAja::getCourierDetail("jne");

// Set whitelist expeditions
KiriminAja::setWhiteListExpedition(["jne_reg", "jne_yes"]);

Credit

// Get the current KiriminAja credit balance
$result = KiriminAja::getCreditBalance();
// $result->data['balance'] => int

AWB (Print Waybill)

// Print shipping label / waybill by AWB number(s)
$result = KiriminAja::printAWB(['awb' => ['AWB123', 'AWB456']]);
// $result->data['data']['url'] => PDF download URL

Calculations (COD)

// Calculate COD (Cash on Delivery) fee
$result = KiriminAja::calculateCOD([
    'item_price' => 100000,
    'data' => [
        [
            'courier_code' => 'jne',
            'courier_service_code' => 'reg',
            'shipping_cost' => 10000,
        ],
    ],
]);
// $result->data => array of fee breakdown per courier/service

Profile

// Get member profile and metadata
$result = KiriminAja::getProfile();
// $result->data['id'], $result->data['email'], $result->data['name'], etc.

Utilities — Volumetric

Estimate the smallest bounding box (length / width / height) for a multi-item package by trying three stacking strategies and returning the arrangement with the smallest volume.

use KiriminAja\Utils\Volumetric;

$dim = Volumetric::calculate([
    ['qty' => 2, 'length' => 10, 'width' => 10, 'height' => 2],
    ['qty' => 1, 'length' => 5,  'width' => 5,  'height' => 5],
]);
// $dim['length'], $dim['width'], $dim['height']

Preference

// Set callback URL
KiriminAja::setCallback("https://example.com/webhook");

Pickup Schedules

KiriminAja::getSchedules();

Payment

// Get payment details (express)
KiriminAja::getPayment("PAY123");

// Get payment details (instant)
KiriminAja::getPayment("PAY123", isInstant: true);

Contributing

For any requests, bugs, or comments, please open an issue or submit a pull request.

Development

composer install                                 # install committed dependencies (PHP 8.5)
vendor/bin/paratest --configuration=phpunit.xml    # run tests in parallel
# or `make test`

ParaTest is the test runner. It uses PHPUnit internally, so PHPUnit remains a transitive development dependency and the tests continue to use PHPUnit assertions and phpunit.xml. The ParaTest constraint allows Composer to resolve dependencies for PHP 8.1 and newer without upgrading beyond PHPUnit 11.

composer.lock is committed for reproducible development installs. CI installs and tests that exact lockfile on PHP 8.5 and checks that it remains unchanged. Separate PHP 8.1–8.4 compatibility jobs use composer update to resolve packages for each PHP version instead of attempting to install the newer locked packages.

When developing on an older PHP version, run composer update to resolve compatible development dependencies locally. Do not commit those compatibility-only lockfile changes; intentional dependency updates should regenerate the canonical lockfile on PHP 8.5.

Use --processes=2 to limit the number of parallel workers, or --processes=1 when debugging. File-cache tests use process-specific temporary directories to avoid interference between workers. Process isolation is enabled in phpunit.xml because the existing Mockery class-overload mocks must not leak between tests.

Releasing

From a clean working tree with the committed dependencies installed on PHP 8.5:

make release          # next patch version
make release-minor    # next minor version
make release-major    # next major version

Each command validates Composer metadata, runs ParaTest, bumps the version, refreshes composer.lock without upgrading locked dependencies, and regenerates CHANGELOG.md. It then creates a release commit and an annotated version tag (for example, 2.1.7) and pushes both atomically to origin on the current branch. Use REMOTE=other-remote to override the destination. Releases stop on errors, uncommitted changes, detached HEAD, or an existing release tag.

The push requires permission to update the branch and create tags. If it fails, the release commit and tag remain local; resolve the cause and push those existing refs rather than running another version bump.

Pushing a version tag triggers .github/workflows/release.yml. It verifies the tag matches composer.json, installs the committed lockfile on PHP 8.5, and runs ParaTest before publishing a GitHub Release with automatically generated release notes. Existing releases are left unchanged on reruns.

To publish or retry an existing tag manually, select Release → Run workflow in GitHub Actions and enter the tag (for example, 2.1.7). The workflow only publishes existing tags; it does not bump versions or create commits or tags.