simba/api

API Simba BAZNAS RI Integration Library untuk CodeIgniter 4 dan Laravel 12

Maintainers

Details

github.com/coijiryuna/simbaapi

Source

Issues

Installs: 12

Dependents: 0

Suggesters: 0

Security: 0

Stars: 1

Watchers: 0

Forks: 0

Open Issues: 1

pkg:composer/simba/api

2.1.1 2025-11-13 11:13 UTC

Requires

  • php: ^8.1

Requires (Dev)

MIT 2bb624b4580cab79328ae3c5c98c6ee9acf946da

  • Coiji Ryuna <rifacomputerlampung.woop@gmail.com>

apidonationsimbacodeigniter4zakatbaznasinfaksedekah

This package is auto-updated.

Last update: 2025-11-19 13:34:03 UTC

README

License: MIT PHP: ^8.1 Codeigniter: ^4 Laravel: ^8

Pustaka (library) ini menyediakan cara mudah untuk berinteraksi dengan API Simba BAZNAS RI di dalam aplikasi CodeIgniter 4 dan Laravel.

✨ Latest in v2.1.0: Full Laravel support with auto-detection HTTP client, enhanced error handling, and comprehensive integration guide!

⚡ Quick Start

For CodeIgniter 4.x

1. Install

composer require simba/api

2. Configure .env

SIMBA_BASE_URL=https://demo-simba.baznas.or.id/
SIMBA_ORG_CODE=9977200
SIMBA_API_KEY=your_api_key
SIMBA_ADMIN_EMAIL=admin@example.com

3. Use in Controller

<?php
use simba\api\Libraries\Muzakki;

class DonationController extends BaseController
{
    public function registerDonor()
    {
        $muzakki = new Muzakki();
        
        $data = [
            'nama'      => 'John Doe',
            'handphone' => '08123456789',
            'email'     => 'john@example.com'
        ];
        
        $response = $muzakki->registerDariLokal(1, $data);
        return $this->response->setJSON($response);
    }
}

For Laravel

Quick Method (⭐ Recommended - Simplest)

<?php
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use simba\api\Libraries\Muzakki;

class DonationController extends Controller
{
    public function registerDonor(Request $request)
    {
        // ✅ Direct instantiation - automatically detects Laravel Http Facade!
        $muzakki = new Muzakki();
        
        $data = [
            'nama'      => $request->input('nama'),
            'handphone' => $request->input('handphone'),
            'email'     => $request->input('email')
        ];
        
        $response = $muzakki->registerDariLokal(1, $data);
        return response()->json($response);
    }
}

Setup Steps

# 1. Install
composer require simba/api

# 2. Configure `.env`
SIMBA_BASE_URL=https://demo-simba.baznas.or.id/
SIMBA_ORG_CODE=9977200
SIMBA_API_KEY=your_api_key
SIMBA_ADMIN_EMAIL=admin@example.com

# 3. (Optional) Publish configuration
php artisan vendor:publish --provider="simba\api\Laravel\SimbaServiceProvider"

# 4. Start using!

Alternative Method - Using Service Container

public function registerDonor(Request $request)
{
    // Using Laravel's service container
    $muzakki = app('simba')->muzakki();
    // or using Facade: $muzakki = \Simba::muzakki();
    
    $response = $muzakki->registerDariLokal(1, $data);
    return response()->json($response);
}

📖 Complete Laravel Integration Guide: See LARAVEL_INTEGRATION_GUIDE.md

📚 Available Libraries

Library Purpose
Muzakki Donatur (Muzakki) Management
Mustahik Penerima Manfaat (Mustahik) Management
Pengumpulan Pengumpulan (Inbound Transaction)
Penyaluran Penyaluran (Outbound Transaction)
Upz UPZ (Unit Pengumpul Zakat) Management

✨ Key Features

✅ Auto-Detecting HTTP Client - Automatically selects Laravel Http Facade or CodeIgniter Services
✅ Laravel Integration - Works seamlessly with Laravel 8+
✅ CodeIgniter Support - Full CodeIgniter 4 compatibility
✅ Response Formatter - Consistent response format
✅ Validation Trait - Reusable validation logic
✅ Exception Handling - Custom exception classes
✅ Service Provider - Easy dependency injection
✅ Type Hints - Full type-safe methods
✅ Error Logging - Built-in error tracking
✅ PSR-4 Autoloading - Modern PHP standards

📝 Response Format

{
  "success": true,
  "status_code": 200,
  "message": "Success",
  "data": { /* API response */ }
}

🔒 Validation Available

use simba\api\Traits\ValidationTrait;

$this->validateNik($nik);              // Validate 16-digit NIK
$this->validateEmail($email);           // Validate email format
$this->validatePhone($phone);           // Validate phone number
$this->validateAmount($amount);         // Validate amount
$this->validateDateRange($from, $to);   // Validate date range
$this->validateNokk($nokk);             // Validate 16-digit KK

📚 File Structure

src/
├── Client.php                      # Base HTTP Client (Auto-detecting)
├── ServiceProvider.php             # Service registration
├── Commands/
│   ├── InstallCommand.php         # CLI install command
│   └── PublishCommand.php         # CLI publish command
├── Exceptions/
│   └── SimbaApiException.php      # Custom exceptions
├── Libraries/
│   ├── Muzakki.php                # Donatur management
│   ├── Mustahik.php               # Recipient management
│   ├── Pengumpulan.php            # Inbound transactions
│   ├── Penyaluran.php             # Outbound transactions
│   └── Upz.php                    # UPZ management
├── Services/
│   ├── ResponseFormatter.php      # Response formatting
│   ├── ConfigService.php          # Configuration service
│   └── Laravel/                   # Laravel integration
│       ├── Manager.php            # Service manager
│       ├── Facade.php             # Facade class
│       └── SimbaServiceProvider.php
├── Traits/
│   └── ValidationTrait.php        # Reusable validations
├── Models/
│   └── ApiModel.php               # Database model
└── Config/
    └── Simba.php                  # Main configuration

�️ Available Commands

Publish Configuration & Migrations

php spark simba:publish

This command publishes the configuration and migration files to your application:

  • Copies Config/Simba.php to app/Config/Simba.php
  • Copies migrations to app/Database/Migrations/

Install & Setup Database

php spark simba:install

This command performs complete setup:

  1. Publishes configuration and migration files
  2. Runs all pending migrations
  3. Seeds default configuration data

Output:

  created: Config/Simba.php
  created: Database/Migrations/2024-02-03-081118_create_config_table.php
  Migration complete
  Seeding data...

Step-by-Step Setup with Commands

# 1. Publish files
php spark simba:publish

# 2. Setup database (includes migrations + seeding)
php spark simba:install

�📖 Examples

Register Donatur

use simba\api\Libraries\Muzakki;

$muzakki = new Muzakki();
$response = $muzakki->registerDariLokal(1, [
    'nama'      => 'Andi Wijaya',
    'handphone' => '08123456789',
    'nik'       => '1234567890123456',
    'email'     => 'andi@example.com'
]);

if ($response['success']) {
    echo "NPWZ: " . $response['data']['npwz'];
}

Search Recipient

use simba\api\Libraries\Mustahik;

$mustahik = new Mustahik();
$response = $mustahik->searchMustahik('Budi');

if ($response['success']) {
    foreach ($response['data'] as $item) {
        echo $item['nama'];
    }
}

Get Total Donation

use simba\api\Libraries\Muzakki;

$muzakki = new Muzakki();
$response = $muzakki->getTotalDonasi('NPWZ123', 2024);

if ($response['success']) {
    echo "Total: Rp " . number_format($response['data']['total']);
}

Save Transaction

use simba\api\Libraries\Pengumpulan;

$pengumpulan = new Pengumpulan();
$response = $pengumpulan->transaksiDariLokal(1, [
    'subjek'   => 'NPWZ123',
    'tanggal'  => '2024-01-15',
    'program'  => 'PROGRAM001',
    'via'      => 'VIA001',
    'akun'     => 'AKUN001',
    'jumlah'   => 500000
]);

Distribute Assistance

use simba\api\Libraries\Penyaluran;

$penyaluran = new Penyaluran();
$response = $penyaluran->simpanTransaksi([
    'subjek'   => 'NRM123',        // Mustahik ID
    'tanggal'  => '2024-01-15',
    'program'  => '211010000',     // Konsumtif
    'via'      => '11010101',      // Transfer Bank
    'akun'     => '51010203',      // Zakat
    'jumlah'   => 750000
]);

🚀 Production Checklist

  • ✅ All files syntax validated
  • ✅ Type-safe methods
  • ✅ Error handling implemented
  • ✅ Security best practices
  • ✅ Comprehensive documentation
  • ✅ Extensible architecture

📚 Documentation

For complete documentation and guides:

🔗 HTTP Client Priority

The library automatically detects and selects the appropriate HTTP client:

  1. Laravel Http Facade (Laravel 8+) ← Preferred in Laravel
  2. CodeIgniter Services (CodeIgniter 4) ← Preferred in CodeIgniter
  3. PHP cURL Extension ← Fallback
  4. Custom HTTP Client ← If injected

No manual configuration needed! 🎯

📞 Support

For issues or questions:

📄 License

MIT License - See license.md for details

Version: 2.1.0
Last Updated: November 2025
Status: ✅ Production Ready
Frameworks Tested: CodeIgniter 4 ✅ | Laravel 8+ ✅