Distribution Financings Laravel Package

Getting Started

Minimal Setup

1. Installation: Require the package via Composer:

   composer require atInisiatifZakat/distribution-financings
   

2. Publish Migrations: Run the migration publisher to set up the database schema:

   php artisan vendor:publish --tag="distribution-financings-migrations"
   php artisan migrate
   

3. Publish Config: Publish the default configuration (if available):

   php artisan vendor:publish --tag="distribution-financings-config"
   

4. Service Provider: Register the package in config/app.php under providers (if not auto-discovered):

   AtInisiatifZakat\DistributionFinancings\DistributionFinancingsServiceProvider::class,
   

First Use Case

Create a Financing Distribution:

use AtInisiatifZakat\DistributionFinancings\Facades\DistributionFinancing;

// Create a new financing distribution
$distribution = DistributionFinancing::create([
    'amount' => 1000.00,
    'currency' => 'USD',
    'description' => 'Q2 2025 Community Support',
    'start_date' => now(),
    'end_date' => now()->addMonth(),
]);

// Attach beneficiaries (assuming a `beneficiaries` relationship exists)
$distribution->beneficiaries()->attach([1, 2, 3], ['share' => 0.5]);

Implementation Patterns

Core Workflows

1. Financing Creation & Management:

   • Use the DistributionFinancing facade to create, update, or retrieve financings.
   • Example: Bulk creation with validation:

     $validated = request()->validate([
         'amount' => 'required|numeric|min:0',
         'currency' => 'required|string|size:3',
         'beneficiary_ids' => 'required|array',
     ]);
     
     $distribution = DistributionFinancing::create($validated);
     $distribution->beneficiaries()->attach($validated['beneficiary_ids']);
     

2. Beneficiary Allocation:

   • Leverage polymorphic relationships to attach beneficiaries (e.g., users, organizations) with custom shares:

     // Attach with dynamic shares
     $beneficiaries = [
         ['beneficiary_id' => 1, 'share' => 0.3],
         ['beneficiary_id' => 2, 'share' => 0.7],
     ];
     $distribution->beneficiaries()->attach($beneficiaries);
     

3. Distribution Processing:

   • Use events (if supported) to trigger actions like notifications or audits:

     // Listen for distribution events (if package emits them)
     event(new \AtInisiatifZakat\DistributionFinancings\Events\DistributionProcessed($distribution));
     

4. Reporting:

   • Query distributions with Eloquent:

     // Get all active distributions for a beneficiary
     $activeDistributions = DistributionFinancing::whereHas('beneficiaries', function($query) {
         $query->where('beneficiaries.id', 1);
     })->where('end_date', '>=', now())->get();
     

Integration Tips

• API Endpoints: Pair with Laravel Sanctum/Passport for secure API access:

  Route::middleware('auth:sanctum')->post('/distributions', function () {
      return DistributionFinancing::create(request()->all());
  });
  

• Frontend: Use Livewire/Inertia for real-time distribution management:

  // Livewire component example
  public function createDistribution() {
      $this->validate([
          'amount' => 'required|numeric',
      ]);
      DistributionFinancing::create($this->input());
  }
  

• Testing: Mock the facade for unit tests:

  $this->mock(AtInisiatifZakat\DistributionFinancings\Facades\DistributionFinancing::class)
       ->shouldReceive('create')
       ->once()
       ->andReturn($mockDistribution);
  

Gotchas and Tips

Pitfalls

1. Database Schema Assumptions:

   • The package may assume tables like financings, beneficiaries, or beneficiary_distribution exist. Verify migrations match your needs.
   • Fix: Override migrations or extend the schema via a custom migration.

2. Currency Handling:

   • Ensure your app supports the currency field (e.g., via laravel-money or similar). Default validation may not cover all cases.
   • Tip: Add custom validation rules:

     use Illuminate\Validation\Rule;
     $request->validate([
         'currency' => ['required', Rule::in(['USD', 'EUR', 'IDR'])],
     ]);
     

3. Polymorphic Relationships:

   • If beneficiaries are polymorphic (e.g., User or Organization), ensure the beneficiaries table has the correct beneficiary_type column.
   • Debug: Check for SQLSTATE[42S22] errors if columns are missing.

4. Share Calculation:

   • The package may not enforce that shares sum to 100%. Add a custom observer or accessor:

     // In DistributionFinancing model
     protected static function booted() {
         static::created(function ($distribution) {
             $totalShare = $distribution->beneficiaries->sum('pivot.share');
             if (!abs($totalShare - 1) < 0.001) {
                 throw new \Exception("Shares must sum to 100%");
             }
         });
     }
     

Debugging

• Log Facade Calls: Temporarily add logging to trace facade interactions:

  \AtInisiatifZakat\DistributionFinancings\Facades\DistributionFinancing::shouldReceive('create')
      ->andReturnUsing(function ($args) {
          \Log::info('Distribution created with:', $args);
          return new \AtInisiatifZakat\DistributionFinancings\Models\DistributionFinancing();
      });
  

• Check Events: If distributions aren’t processing, verify event listeners are registered in EventServiceProvider.

Extension Points

1. Custom Fields:

   • Extend the DistributionFinancing model to add fields (e.g., tax_id, priority):

     php artisan make:model DistributionFinancingExtension -m
     

   • Add to the migration and model:

     // Migration
     $table->string('tax_id')->nullable();
     
     // Model
     protected $casts = [
         'tax_id' => 'string',
     ];
     

2. Validation Rules:

   • Override validation by extending the facade or using form requests:

     // app/Http/Requests/CreateDistributionRequest.php
     public function rules() {
         return [
             'amount' => ['required', 'numeric', 'min:100'], // Custom min amount
         ];
     }
     

3. API Resources:

   • Transform responses with custom resources:

     php artisan make:resource DistributionFinancingResource
     

     // app/Http/Resources/DistributionFinancingResource.php
     public function toArray($request) {
         return [
             'id' => $this->id,
             'formatted_amount' => $this->amount . ' ' . $this->currency,
         ];
     }
     

4. Commands:

   • Add custom Artisan commands for bulk operations:

     php artisan make:command ProcessDistributions
     

     // Handle bulk distribution processing
     $distributions = DistributionFinancing::where('status', 'pending')->get();
     foreach ($distributions as $distribution) {
         $distribution->process();
     }