Model Shared Laravel Package

Technical Evaluation

Assessment basis: releases through 2.10.6 (adds several new models).

Architecture fit

The package remains a thin Eloquent-model distribution layer, not a framework or service. It ships domain reference models (occupation, education degree, marital status, country→province→regency→district→village hierarchy) plus transactional-ish models accreted over time (Donor, DonorPhone, Bank, Partner, Donation, DonationDetail, FundingCategory/Type, Outflow, Account, FundingSource, SubProgramCategory). 2.10.6 adds another unspecified batch of models, confirming the accretion pattern is the operating model rather than a one-off. Architecturally it assumes a Laravel monolith or modular monolith with a shared database schema — it registers migrations via a service provider rather than exposing a clean schema contract.

The one genuinely reusable design decision is resolveRelationUsing() for Donor → Branch and Donor → Employee. That defers host-app coupling to boot time and is the right pattern for cross-application model sharing; it is also the only extension seam. Everything else is opinionated schema that the host app inherits wholesale.

Fit assessment: narrow, and narrowing slightly with each release. This is fit-for-purpose for Indonesian zakat/charity workflows inside the Inisiatif Zakat ecosystem. It is not a general-purpose package, and treating it as one is the primary architectural mistake to avoid. The 2.10.6 additions do not widen the addressable use case — they deepen the package's investment in its own domain.

Integration feasibility

Low technical effort, moderate governance effort. composer require inisiatif/model-shared plus a service provider is a half-day spike. The real cost is confirming what the package does on boot — migrations are registered automatically, and 2.5.0 added a "region search API," which implies route or controller registration. Both are side effects a TPM must have scoped before a single feature depends on it.

2.10.6 changes the scoping arithmetic modestly: the release note ("menambahkan beberapa model baru" — several new models) does not name them. Consuming the tag means inheriting an unenumerated set of tables and relationships, each with its own migration and its own collision surface. The feasibility verdict holds, but the pre-commitment inventory (question 1 and 2 below) now has to cover models that did not exist when the previous assessment was written. Feasible if the team's spike enumerates 2.10.6 explicitly rather than assuming the prior model list.

Integration is feasible if: (a) the target app's schema can be shaped by the package's migrations rather than the reverse; (b) the team accepts Indonesian-language, README-only documentation; (c) someone owns reading the source as the specification.

Technical risk

Key questions to resolve before commitment

1. What exactly does the service provider register on boot — migrations only, or routes, config, and commands?
2. Are migrations idempotent/guarded (the 2.1.0 "migration check" fix implies conditional table creation) and safe under migrate on an existing database?
3. Do columns added in 2.10.1/2.10.2 ship as new migration files, or as edits to the original create migration? This determines whether upgrades are viable at all.
4. What models, tables, and migrations does 2.10.6 actually add — by name — and do any of them collide with tables we already own?
5. Do the 2.10.6 models follow the integer-key or UUID convention, and do they introduce new foreign keys into donor or other tables we already depend on?
6. What are the stated PHP and Laravel version constraints, and is our target version inside them?
7. Is there any license file, and does it permit our intended use (including forking)?
8. Who inside Inisiatif owns this package, and what is the informal support commitment?
9. What is the intended upgrade contract for Donor schema changes that downstream apps depend on?
10. Is the region dataset static seed data or app-populated? Who refreshes village-level boundaries, and how often do Indonesian administrative divisions change?

Integration Approach

Stack fit

Requires Laravel + Eloquent. Non-Laravel PHP, or any project using Doctrine/other ORMs, is out of scope — resolveRelationUsing is Eloquent-only, and the value proposition collapses without it. Best fit: a Laravel app whose domain is Indonesian charitable giving and whose team is comfortable with package-level model sharing.

Recommended posture: adopt as a vendor fork, not as an upstream dependency

Given 0 stars / 0 dependents / single-org ownership, the TPM call is to consume the package but own the code path:

1. Fork into our VCS and publish to a private Composer registry (Satis, Private Packagist, or a VCS repository entry). Pin to an exact tag; never float a constraint. 2.10.6 is a candidate fork point only after its new models are enumerated.
2. Freeze the schema inside the fork. Convert any edited-in-place create migrations into additive migrations before first production deploy. Treat the fork's migration history as our own.
3. Wrap package models. Domain code should not use Inisiatif\ModelShared\Models\Donor directly. Introduce our own Donor extending or composing the package model, so an upstream swap or abandonment is a one-file change.
4. Adopt new models selectively, not wholesale. 2.10.6's additions are not a bundle to accept or reject as a unit. Take the ones the roadmap needs; leave the rest uncalled-for in the fork rather than registering migrations for tables we will never populate.
5. Pull reference data in as seeders, not runtime dependency. If region data is seed-driven, snapshot it into our repo so a package abandonment does not orphan the data.

Migration path (brownfield)

• Inventory existing tables the package would own (donors, banks, partners, regions, etc.) — and extend that inventory to whatever 2.10.6 introduces before the diff is run.
• Diff package schema against incumbent schema; the package's migrations assume it creates these tables. Rename-on-conflict or pre-adopt one or the other — do not let both run.
• Backfill: map existing donor rows to the package's column set, including donor_phone_id and email; run dual-write only if a cutover window is unavoidable.
• For region data specifically, plan a full replace of any homegrown administrative tables — partial merges create duplicate village records that are painful to unwind later.
• Do not treat "2.10.5 → 2.10.6 is a patch" as evidence of small blast radius. Diff the tag; new tables are cheap to add and cheap to skip, but only if you know what they are.

Greenfield is materially cheaper and is where I would spend the political capital: the package becomes the schema, and there is nothing to reconcile.

Compatibility and sequencing

Sequence by model family, not by release: reference data first (read-only, reversible), then Donor, then financial/Outflow models last. Financial models carry the highest blast radius if the schema shifts upstream. 2.10.6 is not a sequencing event — it is a supply of optional models whose placement on this ladder is decided by what each one relates to, not by the fact that it shipped.

Explicit non-fit

Do not adopt if the product needs non-Indonesian geography, if the roadmap requires a schema meaningfully divergent from the package's donor/donation shape, or if the team cannot absorb maintaining a fork. For a global or highly customized donor model, the package becomes a drag, not an accelerator. The 2.10.6 additions make the package broader within its domain, not broader across domains.

Operational Impact

Maintenance

Ongoing maintenance is effectively ours. Upstream ships frequently — patch releases for typos, minor releases adding models, and now a patch release adding models — which reads as active but low-ceremony development. That cadence is not a support guarantee: no issue triage, no changelog discipline beyond auto-generated PR lists, no deprecation policy, and release notes that occasionally do not name what shipped. Budget a named owner (one backend engineer at ~10–15% time) for fork upkeep, upstream diff review, and region data refresh. Track upstream tags monthly; merge selectively, never automatically. Review the 2.10.6 diff before it enters the fork, and record what was taken versus skipped so the next merge is a comparison rather than a re-discovery.

Support

There is no external support channel. Escalation is a direct message to the Inisiatif contributors. For a TPM, that means the dependency must not sit on any critical path the team cannot patch itself. The adapter layer is the operational mitigation: it caps the blast radius of abandonment at one directory. The 2.10.6 release note style — a single PR line, model names omitted — is a concrete illustration of why that mitigation is not optional.

Scaling

• Read-heavy reference data (region hierarchy, education/occupation/marital lookup) is cache-friendly and low risk. Indonesian village-level data is roughly 80k+ rows; verify it is served from a cached/indexed path, not an unindexed LIKE scan behind the region search API.
• Write paths (Donor, Donation, Outflow) scale with the host app's schema choices, not with the package. The package contributes no indexing strategy — that is on us, and should be reviewed before volume grows, including for any 2.10.6 model we adopt.
• Migration runtime grows with table count on each deploy; the auto-registration means every deploy pays the migration check cost. Each new model added upstream increases that set even if we never query it — another reason to trim unused models in the fork.
• Multi-app reuse is the package's stated purpose. Expect schema divergence across apps over time; without a versioned schema contract, apps will drift and the "shared" benefit erodes. An expanding model set with no contract accelerates that drift, because each app adopts a different subset.

Failure modes

Ramp-up

• Onboarding cost is low-to-moderate: Laravel developers read the models in an hour, but the documentation is Indonesian-only and README-level, so the source is the spec — and the spec grew again in 2.10.6. Plan a short internal write-up of the models we use and the relations we override; that document becomes the real onboarding artifact and must be re-checked after each upstream merge.
• The resolveRelationUsing pattern is non-obvious to developers who have not used it; include it in onboarding explicitly, since debugging a misconfigured dynamic relation is slow and produces confusing null relations rather than errors.
• Cross-team ramp-up depends on the adapter layer existing first. If three apps adopt the raw package, three teams learn three different subsets and drift immediately — sequence the adapter before broadening adoption, and document which subset each app took.
• Expected time-to-first-value in a greenfield Laravel app: roughly one to two weeks including the fork, pinning, adapter, and the 2.10.6 delta review, with a working region/reference data flow at the end. Brownfield depends entirely on reconciliation with existing tables and should be scoped per-domain.