Model Shared Laravel Package

Technical Evaluation

Architecture Fit

• Domain-Driven Design (DDD) Alignment: The package adheres to a shared kernel pattern, offering pre-built entities (e.g., Donor, Degree, Region) and value objects (e.g., geographic hierarchies) that map directly to Inisiatif Zakat’s domain. Ideal for a Laravel monolith or microservices where core models are reused across modules (e.g., donor management, distribution workflows).
• Eloquent-Centric: Leverages Laravel’s Eloquent ORM with dynamic relations (e.g., Donor::resolveRelationUsing), reducing boilerplate for polymorphic associations. Risk: Tight coupling to Eloquent may complicate adoption in non-Laravel PHP projects.
• Geographic Granularity: Provides Indonesia-specific administrative boundaries (country → province → district → village), critical for zakat distribution compliance. Limitation: Not global; requires customization for other regions.
• Extensibility: Models include hooks (e.g., boot in service providers) for extending relations or adding custom logic. Example:

  Donor::resolveRelationUsing('custom_tag', fn($model) => $model->morphTo());
  

  Tradeoff: Extensions may diverge from the shared model’s intent over time.

Integration Feasibility

• Composer Dependency: Lightweight (~5MB) with no hard dependencies beyond Laravel/Eloquent. Feasibility: High for Laravel 8+ projects.
• Migration Strategy:
  • Shared Migrations: Includes migrations for all models (e.g., donors_table, degrees_table). Risk: Schema conflicts if your app already defines these tables.
  • Dynamic Relations: Requires runtime binding (e.g., Donor::resolveRelationUsing) to link to your Branch/Employee models. Complexity: Low for simple relations; higher for complex polymorphic setups.
• API Compatibility:
  • Laravel 10+: Tested with recent releases (e.g., ramsey/composer-install@4). Action Item: Verify compatibility with your Laravel version via composer why-not inisiatif/model-shared.
  • PHP 8.1+: Assumes modern PHP features (e.g., named arguments, attributes). Risk: May fail on older stacks.

Technical Risk

Key Questions for the TPM

1. Domain Scope:
   • Are we only operating in Indonesia, or do we need global geographic support? If global, how will we extend the Region models?
2. Customization Needs:
   • Do we need to override any shared models (e.g., Donor) with custom fields? If so, what’s the strategy for keeping changes in sync with upstream?
3. Migration Strategy:
   • Should we merge these migrations into our existing schema or wrap them in feature flags for phased adoption?
4. Testing:
   • How will we test dynamic relations (e.g., Donor::branch()) in CI? Mock the resolved classes or use a test database with stubbed models.
5. Long-Term Maintenance:
   • Will we fork this repo to ensure it stays compatible with our Laravel version, or treat it as a temporary scaffold?
6. Performance:
   • The Region models (country → village) could bloat queries. Are we using query scopes or caching (e.g., Region::where('province_id', ...)->with('districts'))?
7. Security:
   • Are there sensitive fields (e.g., donor phone numbers) that need additional encryption or access controls beyond the package’s defaults?

Integration Approach

Stack Fit

• Primary Fit: Laravel 8+ applications with Eloquent ORM, targeting nonprofit/financial inclusion domains (e.g., zakat platforms, microfinance).
• Secondary Fit:
  • Lumen: Possible with minor adjustments (e.g., manual service provider booting).
  • Non-Laravel PHP: Not recommended due to Eloquent dependencies.
• Anti-Patterns:
  • Global Projects: Avoid if geographic data isn’t Indonesia-specific.
  • Microservices: Only use for shared libraries (e.g., a models service); not for standalone APIs.

Migration Path

1. Assessment Phase (1–2 days):

   • Audit existing models for conflicts (e.g., overlapping donors table).
   • Test dynamic relations in a sandbox project:

     composer create-project laravel/laravel sandbox
     cd sandbox
     composer require inisiatif/model-shared
     

   • Verify migrations with php artisan migrate:status.

2. Pilot Integration (3–5 days):

   • Step 1: Install as a dev dependency and test models in isolation.
   • Step 2: Implement dynamic relations for critical paths (e.g., Donor::branch()).
   • Step 3: Run schema diffs to identify merge conflicts:

     php artisan schema:dump --path=/tmp/baseline
     composer require inisiatif/model-shared
     php artisan schema:dump --path=/tmp/with-package
     diff -u /tmp/baseline /tmp/with-package
     

3. Phased Rollout:

   • Phase 1: Core models (Donor, Degree, Region) with read-only access.
   • Phase 2: Extend relations (e.g., Donor::employee()) and add custom fields.
   • Phase 3: Replace legacy models with shared versions (e.g., swap App\Models\Donor for Inisiatif\ModelShared\Models\Donor).

Compatibility

Sequencing

1. Pre-Integration:
   • Fork the repo to patch critical issues (e.g., typos in PRs 28–30).
   • Add a composer.json extra to document relation mappings:

     "extra": {
       "model-shared": {
         "relations": {
           "Donor": {
             "branch": "App\Models\Branch",
             "employee": "App\Models\Employee"
           }
         }
       }
     }
     

2. During Integration:
   • Order of Operations:
     1. Install package.
     2. Publish migrations (if using Laravel’s publish:migrations).
     3. Bind dynamic relations in AppServiceProvider@boot.
     4. Update config/app.php to alias models (optional):

        'aliases' => [
          'Donor' => Inisiatif\ModelShared\Models\Donor::class,
        ],
        

3. Post-Integration:
   • Deprecate legacy models via trait-based fallbacks:

     class LegacyDonor extends Inisiatif\ModelShared\Models\Donor {
         // Fallback methods for backward compatibility
     }
     

   • Document extensions in a CUSTOMIZATIONS.md file.

Operational Impact

Maintenance