Eloquent Ifrs Laravel Package

Getting Started

Minimal Setup

1. Installation (updated for Laravel 11+ and PHP 8.2+):

   composer require ekmungai/eloquent-ifrs:^6.0
   

   Publish migrations and config:

   php artisan vendor:publish --provider="EkmunGai\EloquentIfrs\EloquentIfrsServiceProvider" --tag="migrations"
   php artisan vendor:publish --provider="EkmunGai\EloquentIfrs\EloquentIfrsServiceProvider" --tag="config"
   

   Run migrations (note: remove_vat_id_column migration now handles modern SQLite drivers):

   php artisan migrate
   

2. First Use Case (unchanged):

   use EkmunGai\EloquentIfrs\Models\Entity;
   use EkmunGai\EloquentIfrs\Models\Account;
   
   $entity = Entity::create(['name' => 'My Company']);
   $cashAccount = Account::create([
       'entity_id' => $entity->id,
       'code' => '1000',
       'name' => 'Cash',
       'type' => 'asset',
   ]);
   

3. Record a Transaction (unchanged):

   use EkmunGai\EloquentIfrs\Models\Transaction;
   
   $transaction = Transaction::create([
       'entity_id' => $entity->id,
       'date' => now(),
       'description' => 'Initial cash deposit',
       'entries' => [
           ['account_id' => $cashAccount->id, 'debit' => 1000.00],
           ['account_id' => $cashAccount->id, 'credit' => 1000.00],
       ],
   ]);
   $transaction->validate()->save();
   

4. Verify Integrity (now with deterministic validation):

   $transaction->validate(); // Throws exception if debits ≠ credits
   

Key Starting Points (updated)

• Config: config/eloquent-ifrs.php (now tested with Laravel 11/12/13)
• Models: EkmunGai\EloquentIfrs\Models\ (PHP 8.2+ compatible)
• Reports: Use EkmunGai\EloquentIfrs\Reports\ (now deterministic due to seeded PRNG)
• Testing: Updated phpunit.xml schema for PHPUnit 10/11

Implementation Patterns

Core Workflows

1. Entity and Account Management (unchanged)

$entity = Entity::find(1);
$accounts = $entity->accounts()->where('type', 'asset')->get();

2. Transaction Processing (updated for PHP 8.2+)

• Batch Transactions (now with guaranteed non-zero values):

  Transaction::createBatch([
      [
          'entity_id' => $entity->id,
          'date' => now(),
          'entries' => [['account_id' => $cashAccount->id, 'debit' => 500.00]], // No zero values
      ],
  ]);
  

3. VAT Handling (fixed for modern Laravel)

$transaction = Transaction::create([
    'entity_id' => $entity->id,
    'date' => now(),
    'entries' => [
        ['account_id' => $cashAccount->id, 'debit' => 1200.00],
        ['account_id' => $vatAccount->id, 'credit' => 200.00],
    ],
    'vat_rate' => config('eloquent-ifrs.default_vat_rate'),
]);

4. Opening Balances (now deterministic)

use EkmunGai\EloquentIfrs\Models\OpeningBalance;

OpeningBalance::create([
    'entity_id' => $entity->id,
    'account_id' => $cashAccount->id,
    'amount' => 5000.00,
    'year' => 2025,
]);

5. Reporting (now reliable)

use EkmunGai\EloquentIfrs\Reports\TrialBalance;

$report = new TrialBalance($entity, 2025);
$data = $report->generate(); // Deterministic output

6. Laravel 11+ Integration

• Service Providers: Updated for Laravel 11's booting system:

  // In AppServiceProvider@boot()
  if ($this->app->runningInConsole()) {
      $this->publishes([
          __DIR__.'/../../vendor/ekmungai/eloquent-ifrs/config/eloquent-ifrs.php' => config_path('eloquent-ifrs.php'),
      ], 'eloquent-ifrs-config');
  }
  

Advanced Patterns

1. Custom Account Types (PHP 8.2+)

class CustomAccount extends Account
{
    protected $casts = [
        'is_tax_deductible' => 'boolean',
        'created_at' => 'datetime:Y-m-d H:i:s', // Explicit casting
    ];
}

2. Audit Trails (Laravel 11+ compatible)

use OwlLabs\Auditing\Contracts\Auditable;

class Transaction extends \EkmunGai\EloquentIfrs\Models\Transaction implements Auditable
{
    use \OwlLabs\Auditing\Auditable;
}

3. Scheduled Reconciliation (Laravel 11+ scheduler)

// app/Console/Kernel.php
protected function schedule(Schedule $schedule)
{
    $schedule->command('eloquent-ifrs:reconcile')->dailyAt('02:00');
}

4. Multi-Currency Support (PHP 8.2+ typed properties)

class Transaction extends \EkmunGai\EloquentIfrs\Models\Transaction
{
    protected float $exchange_rate = 1.0;
    protected array $entries = [];

    public function getTotalDebit(): float
    {
        return array_sum(array_column($this->entries, 'debit'));
    }
}

5. Account Scheduling (fixed Carbon 3 compatibility)

$accountSchedule = AccountSchedule::where('account_id', $account->id)
    ->where('start_date', '<=', now())
    ->where('end_date', '>=', now())
    ->first();

// Age calculation now works for Carbon 3 (returns signed float)
$daysActive = $accountSchedule->age_in_days();

Gotchas and Tips

Pitfalls

1. PHP Version Mismatch:

   • Gotcha: Using PHP 8.1 will fail with Class 'Stringable' not found.
   • Fix: Update to PHP 8.2+:

     # Example .tool-versions file
     php 8.4.0
     

2. Laravel Version Drop:

   • Gotcha: Laravel 10 is no longer supported.
   • Fix: Upgrade to Laravel 11/12/13:

     composer require laravel/framework:^11.0
     

3. Zero-Balance Accounts:

   • Gotcha: Factories now guarantee non-zero values, but existing data may have zeros.
   • Fix: Run a data cleanup:

     Account::where('balance', 0)->whereNotNull('opening_balance')->update([
         'opening_balance' => 1.00, // Minimum non-zero value
     ]);
     

4. SQLite Migration Issues:

   • Gotcha: remove_vat_id_column migration may fail on modern SQLite.
   • Fix: Run manually if needed:

     php artisan db:seed --class=FixVatColumnMigration
     

5. Deterministic Testing:

   • Gotcha: Previous random failures in CI due to shared PRNG.
   • Fix: Tests now seed the PRNG globally:

     // In tests/bootstrap.php
     mt_srand(12345); // Seeded for deterministic results
     

6. Carbon Version Conflicts:

   • Gotcha: diffInDays() returns signed float in Carbon 3.
   • Fix: Use abs() or handle signed values:

     $days = abs($accountSchedule->age_in_days());
     

Tips

1. Laravel 11+ Booting:

   • Register providers in config/app.php under providers array:

     EkmunGai\EloquentIfrs\EloquentIfrsServiceProvider::class,
     

2. PHP 8.2+ Features:

   • Use read-only properties for immutable data:

     class Transaction
     {
         public function __construct(
             public readonly int $entity_id,
             public readonly string $description,
         ) {}
     }