README

RajaOngkir Komerce Laravel adalah package PHP yang menyediakan integrasi mudah dan lengkap dengan API RajaOngkir V2 by Komerce. Package ini dirancang khusus untuk aplikasi Laravel dengan fitur-fitur modern seperti caching, validasi, dan dukungan multi-bahasa.

✨ Fitur Utama

• 🚀 Perhitungan Ongkos Kirim: Mendukung perhitungan ongkir domestik dengan multiple kurir
• 📍 Data Lokasi Lengkap: Akses data provinsi, kota, kecamatan, dan kelurahan
• 🏷️ Validasi Terintegrasi: Form Request validation dengan CourierRule yang robust
• 💾 Caching Pintar: Sistem cache dengan tags untuk performa optimal
• 🌐 Multi-bahasa: Dukungan bahasa Indonesia dan Inggris
• 🛡️ Exception Handling: Penanganan error yang komprehensif
• 📦 Laravel Ready: Dibuat khusus untuk ekosistem Laravel

📋 Kurir yang Didukung

Mendukung 13+ kurir populer di Indonesia:

• JNE (Jalur Nugraha Ekakurir)
• TIKI (Citra Van Titipan Kilat)
• POS Indonesia
• SiCepat Express
• J&T Express
• Ninja Xpress
• ID Express
• SAP Express
• Wahana Express
• Lion Parcel
• Royal Express Indonesia (REX)
• Sentral Cargo
• Dan lainnya...

Installation

You can install the package via composer:

composer require manh21/rajaongkir-laravel

You can publish the config file with:

php artisan vendor:publish --tag="rajaongkir-laravel-config"

This is the contents of the published config file:

return [
    'api_key' => env('RAJAONGKIR_API_KEY'),
    'base_url' => env('RAJAONGKIR_BASE_URL', 'https://rajaongkir.komerce.id/api/v1'),
    'cost_cache_duration' => env('RAJAONGKIR_COST_CACHE_DURATION', 60), // in minutes
    'location_cache_duration' => env('RAJAONGKIR_LOCATION_CACHE_DURATION', 1440), // in minutes (1 day
];

🚀 Usage

Basic Usage

use Komodo\RajaOngkir\Rajaongkir;
use Komodo\RajaOngkir\Constants\Courier;

$rajaongkir = new Rajaongkir();

Mendapatkan Data Lokasi

// Ambil semua provinsi
$provinces = $rajaongkir->getProvinces();

// Ambil kota berdasarkan provinsi
$cities = $rajaongkir->getCities(11); // DKI Jakarta

// Ambil kecamatan berdasarkan kota
$districts = $rajaongkir->getDistricts(152); // Jakarta Pusat

// Ambil kelurahan berdasarkan kecamatan  
$subdistricts = $rajaongkir->getSubdistricts(1234);

Perhitungan Ongkos Kirim

Menggunakan Individual Parameters

// Menggunakan Courier Enum (Recommended)
$cost = $rajaongkir->calculateDistrictCost(
    originId: 152,           // ID Kecamatan asal
    destinationId: 153,      // ID Kecamatan tujuan
    weight: 1000,           // Berat dalam gram (1kg)
    courier: [              // Array kurir enum
        Courier::JNE,
        Courier::TIKI,
        Courier::SICEPAT
    ],
    sortBy: 'lowest'        // Urutkan berdasarkan harga terendah
);

// Atau menggunakan string values
$cost = $rajaongkir->calculateDistrictCost(
    originId: 152,
    destinationId: 153,
    weight: 1000,
    courier: ['jne', 'tiki', 'sicepat'], // Array string
    sortBy: 'lowest'
);

// Mix enum dan string juga didukung
$cost = $rajaongkir->calculateDistrictCost(
    originId: 152,
    destinationId: 153,
    weight: 1000,
    courier: [
        Courier::JNE,      // Enum
        'tiki',            // String
        Courier::SICEPAT   // Enum
    ],
    sortBy: 'lowest'
);

Menggunakan Courier Enum & Validasi

use Komodo\RajaOngkir\Constants\Courier;
use Komodo\RajaOngkir\Rules\CourierRule;

// Menggunakan enum untuk type safety
$courierCode = Courier::JNE->value; // 'jne'

// Cek kemampuan kurir
if (CourierRule::supportsInternationalCost('jne')) {
    // JNE mendukung ongkir internasional
}

if (CourierRule::supportsAwb('sicepat')) {
    // SiCepat mendukung pelacakan resi
}

// Validasi array kurir (mixed enum & string)
$couriers = [Courier::JNE, 'tiki', Courier::SICEPAT];

if (CourierRule::validateCouriers($couriers)) {
    // Semua kurir valid
    $courierValues = CourierRule::convertCouriersToValues($couriers);
    // Result: ['jne', 'tiki', 'sicepat']
}

// Cek kurir yang tidak valid
$invalidCouriers = CourierRule::getInvalidCouriers(['jne', 'invalid', 'tiki']);
// Result: ['invalid']

Pelacakan Resi (AWB Tracking)

// Menggunakan Courier enum
$tracking = $rajaongkir->trackAWB(
    waybill: 'JNE123456789',
    courier: Courier::JNE
);

// Menggunakan string
$tracking = $rajaongkir->trackAWB(
    waybill: 'TIKI987654321',
    courier: 'tiki'
);

// Dengan nomor telepon (untuk kurir tertentu)
$tracking = $rajaongkir->trackAWB(
    waybill: 'SICEPAT123456',
    courier: Courier::SICEPAT,
    last_phone_number: '12345' // 5 digit terakhir nomor penerima
);

Pencarian Destinasi

// Pencarian destinasi domestik
$destinations = $rajaongkir->searchDomesticDestinations(
    search: 'Jakarta',
    limit: 10,
    offset: 0
);

// Pencarian destinasi internasional
$intlDestinations = $rajaongkir->searchInternationalDestinations(
    search: 'Singapore',
    limit: 10,
    offset: 0
);

Cache Management

// Set custom cache duration
$rajaongkir->setLocationCacheDuration(7200)  // 2 jam untuk data lokasi
          ->setCostCacheDuration(1800);      // 30 menit untuk ongkir

// Clear cache
$rajaongkir->clearLocationCache();           // Hapus cache lokasi
$rajaongkir->clearCostCache();              // Hapus cache ongkir
$rajaongkir->clearCache();                  // Hapus semua cache

Exception Handling

use Komodo\RajaOngkir\Exceptions\ApiException;
use Illuminate\Validation\ValidationException;

try {
    $cost = $rajaongkir->calculateDistrictCost(
        originId: 152,
        destinationId: 152, // Error: sama dengan origin
        weight: 50000,      // Error: melebihi batas
        courier: ['invalid'] // Error: kurir tidak valid
    );
} catch (ValidationException $e) {
    // Handle validation errors
    $errors = $e->validator->errors();
    
} catch (ApiException $e) {
    // Handle API errors
    $message = $e->getMessage();
    $statusCode = $e->getStatusCode();
    $response = $e->getResponse();
}

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

🧪 Testing

The package includes comprehensive tests covering all major functionality:

Running Tests

composer test

Test Coverage

• BasicFunctionalityTest - Core components and validation ✅
• CourierEnumTest - Courier enum validation ✅
• CourierRuleTest - Laravel validation rules ✅
• CostCalculationTest - API cost calculations with mocking ✅
• IntegrationTest - Complete workflow testing ✅
• ServiceProviderTest - Laravel service provider integration ✅

Test Structure

// Example test usage
use Komodo\RajaOngkir\Constants\Courier;
use Komodo\RajaOngkir\Rules\CourierRule;

// Test courier validation
$validator = validator(['courier' => Courier::JNE], [
    'courier' => new CourierRule()
]);
expect($validator->passes())->toBeTrue();

// Test courier conversion
$converted = CourierRule::convertCouriersToValues([Courier::JNE, 'tiki']);
expect($converted)->toBe(['jne', 'tiki']);

Cache Driver Testing

The package automatically detects and adapts to your cache driver:

• Redis/Memcached: Full tagging support for granular cache management
• File/Database/Array: Basic caching with fallback mechanisms

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Naufal Hakim
• All Contributors

License

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