Distribution Financings Laravel Package

Getting Started

This is an internal share package for "distribution financing" — most likely the financing/distribution domain of an amil/zakat or charity platform (programs, donations, fund types, uploads). The README is still the Spatie package-skeleton template, so treat it as unreliable: the echoPhrase() usage example is placeholder text, and the config file published is empty. Start from the code, not the docs.

Minimal setup:

composer require inisiatif/distribution-financings
php artisan vendor:publish --tag="distribution-financings-migrations"
php artisan migrate
php artisan vendor:publish --tag="distribution-financings-config"   # currently returns []

Optionally publish views if you intend to override the package's UI:

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

Where to look first, in order:

1. composer.json and the package service provider — confirm what is auto-registered (migrations, routes, config, views, commands).
2. database/migrations — the schema is the real documentation here. The changelog shows the model has evolved a lot (type column on donations, funding_type_id and program_id added in 1.6.1, donor table adjustments in 1.5.3).
3. src/Models — primarily Financing and Donation, plus Program/funding-type relations added across 1.2.0 and 1.7.x.
4. routes/ — API routes exist (fixed in 1.0.1, updated in 1.1.0), so check for a route file registered by the provider before building your own controllers.
5. Repository classes — changelog references DonationRepository.php (1.3.0), so queries are likely encapsulated there rather than in controllers.

First realistic use case: list and paginate financings for a back-office screen, then create a financing tied to a program and funding type. Since the package had an explicit "Fix List Financing Pagination" fix in 1.2.4, use the package's list/pagination path rather than writing a fresh Financing::paginate() until you've verified the scoping (tenant, program, status) it applies.

Implementation Patterns

Treat the package as a domain module, not a utility library. There is no meaningful config surface (return [];), so customization happens at the edges: your own controllers, resources, and views wrapping the package models and repositories.

Read-through for list screens. Prefer the package's own repository/query methods for index endpoints. The changelog's repeated "Adjustment fetch Donation Query" (1.5.2), "Adjustment Donation List Filter" (1.3.1), and "error filter donor" fix (1.7.2) suggest the filtering logic is non-trivial — donor filters, type filters, and pagination have all been patched. Reimplementing them is a good way to reintroduce old bugs.

// Prefer delegating to the package's repository/query layer if exposed
$financings = app(FinancingRepository::class)->paginate($request->validated());

Model the program and funding relations explicitly. From 1.6.1 (funding_type_id, program_id on donations) and 1.7.0/1.7.1 ("donation detail funding & program", "penyesuaian relasi pada model financing"), the current shape is roughly: a Financing belongs to a Program and a funding type, and donations hang off the financing/donation detail. When you build forms, eager-load these:

$financing = Financing::with(['program', 'fundingType', 'donations'])->findOrFail($id);

Uploads are first-class. 1.4.0 added donation upload, 1.5.0 added financing upload, 1.4.1 adjusted "get payload data from model upload", and 1.7.12 fixed the upload donation error message. So there is an upload model/payload convention in the package. Don't hand-roll file storage for these flows — reuse the package's upload model so payload shape, validation, and error messaging stay consistent with what 1.7.12 fixed.

// Reuse the package upload flow rather than Storage::put() directly
$upload->store($request->file('file'), $payload);

Deletion has financial side effects. 1.2.2 introduced "Refund donation amount while deleting financing". Any delete path you expose in your admin UI must go through the package's delete logic, not $financing->delete(), or you will silently lose the refund behavior:

// Correct: package-aware deletion (refunds donation amounts)
app(FinancingService::class)->delete($financing);

// Risky: bypasses refund logic introduced in 1.2.2
// $financing->delete();

Wrap destructive operations in a DB transaction and log who deleted what — refunding donation amounts is exactly the kind of operation you want auditable.

Integration tips for a host app:

• Register the package's API routes under your existing auth middleware group rather than exposing them raw; the changelog's "Fixing Route API" implies routes ship with the package.
• If you need additional fields, add a separate migration in your app rather than editing the published package migrations — otherwise upgrading past 1.7.x becomes painful.
• Use API Resources at your boundary. The package models carry a lot of columns that have churned (donation_type → type in 1.5.4), and you don't want that churn leaking into your public JSON contract.
• Add feature tests around the flows you depend on (create financing, upload, delete-with-refund) so package upgrades surface regressions early. There's a PHPUnit workflow in CI, but that only covers the package, not your integration.

Gotchas and Tips

• The README will mislead you. The Financing::echoPhrase() example is unchanged skeleton code. Nothing in the changelog suggests echoPhrase is real domain API. Ignore it and read src/ instead.
• Empty config file. distribution-financings-config publishes an empty array. Don't assume tunables exist; if you need behavior switches, you'll be forking or decorating.
• Column names have changed repeatedly. donation_type became type (1.5.4), funding_type_id and program_id were added later (1.6.1), and the donor table was adjusted in 1.5.3. If you're upgrading from an early 1.x, diff the migrations and don't trust old blog posts or your own earlier queries.
• Deleting a financing refunds donations. This is a feature, but it's also a surprise in tests — a delete() in a test factory teardown can mutate donation balances. Assert on the refund explicitly.
• Pagination and filters are historically fragile. 1.2.3 fixed remaining-amount calculation, 1.2.4 fixed pagination, 1.3.1 and 1.7.2 fixed filters. Pin a version and check your list endpoint's totals after every bump — remaining/outstanding amounts are the most likely place for silent numeric drift.
• Program Sector Not Found (1.2.1) indicates program→sector lookups can fail when relations aren't loaded or seeded. Seed programs, sectors, and funding types in your test suite before exercising financing creation.
• Zero stars and zero dependents means no community safety net: no Stack Overflow answers, no third-party usage to crib from. Budget time to read the source, and consider pinning with a conservative constraint ("inisiatif/distribution-financings": "~1.7.0") plus a changelog review before each upgrade.
• Release dates look anomalous (latest listed as 2026-10-08). Verify the actual installed version via composer show inisiatif/distribution-financings rather than trusting the badge or changelog metadata.
• Extension points to prefer, in order: your own service classes wrapping the package, model event listeners/observers registered in your AppServiceProvider, published views for UI changes, and only then source forks. With no config hooks and no dependents, a fork is expensive — keep your customizations outside the vendor tree so composer update stays viable.