Model Shared Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require inisiatif/model-shared
   

   Publish migrations (if needed):

   php artisan vendor:publish --provider="Inisiatif\ModelShared\ModelSharedServiceProvider" --tag="migrations"
   

2. Run Migrations:

   php artisan migrate
   

3. First Use Case: Use the Donor model to fetch or create donor records:

   use Inisiatif\ModelShared\Models\Donor;
   
   $donor = Donor::find(1);
   $donor->degree; // Access education level
   $donor->maritalStatus; // Access marital status
   

4. Dynamic Relations Setup: Add dynamic relations in your AppServiceProvider:

   public function boot()
   {
       Donor::resolveRelationUsing('branch', function ($model) {
           return $model->belongsTo(\App\Models\Branch::class, 'branch_id');
       });
   }
   

Where to Look First

• Models Directory: vendor/inisiatif/model-shared/src/Models/ for all available models.
• Migrations: vendor/inisiatif/model-shared/database/migrations/ for schema details.
• Service Provider: vendor/inisiatif/model-shared/src/ModelSharedServiceProvider.php for bootstrapping.

Implementation Patterns

Usage Patterns

1. Model Extensions: Extend shared models with custom attributes or relations:

   // In AppServiceProvider
   Donor::extend('customAttribute', function ($model) {
       return $model->hasOne(CustomAttribute::class);
   });
   

2. Geographic Hierarchy: Use nested relations for location-based queries:

   $village = \Inisiatif\ModelShared\Models\Village::with(['district.province.country'])->find(1);
   

3. Dynamic Relations: Define polymorphic relations dynamically (as shown in the README) to avoid hardcoding foreign keys.

4. Query Scoping: Leverage built-in scopes (e.g., activeDonors() if added in future versions):

   $activeDonors = Donor::active()->get();
   

5. Migrations: Run migrations for shared tables:

   php artisan migrate --path=vendor/inisiatif/model-shared/database/migrations
   

Workflows

1. Donor Management:

   • Create a donor with associated data:

     $donor = Donor::create([
         'name' => 'John Doe',
         'degree_id' => \Inisiatif\ModelShared\Models\Degree::where('name', 'S1')->first()->id,
         'marital_status_id' => \Inisiatif\ModelShared\Models\MaritalStatus::where('name', 'Married')->first()->id,
     ]);
     

   • Attach dynamic relations:

     $donor->branch()->associate(\App\Models\Branch::find(1));
     $donor->save();
     

2. Geographic Data:

   • Fetch a village with its full hierarchy:

     $village = \Inisiatif\ModelShared\Models\Village::withPath()->find(1);
     

   • Search for regions (if API is implemented):

     $regions = \Inisiatif\ModelShared\Models\Region::search('Jakarta')->get();
     

3. Outflows and Donations:

   • Track zakat distributions:

     $outflow = \Inisiatif\ModelShared\Models\Outflow::create([
         'donor_id' => $donor->id,
         'amount' => 1000000,
         'purpose' => 'Education',
     ]);
     

Integration Tips

1. Customize Migrations: Override shared migrations in your app’s database/migrations to add custom columns:

   Schema::table('donors', function (Blueprint $table) {
       $table->string('custom_field')->nullable();
   });
   

2. Use Traits: Reuse traits from the package (e.g., HasDynamicRelations) in your models:

   use Inisiatif\ModelShared\Traits\HasDynamicRelations;
   

3. API Endpoints: Build API routes for shared models (e.g., /api/degrees):

   Route::apiResource('degrees', \Inisiatif\ModelShared\Models\Degree::class);
   

4. Testing: Mock shared models in tests:

   $this->partialMock(Donor::class, function ($mock) {
       $mock->shouldReceive('degree')->andReturn(new Degree());
   });
   

Gotchas and Tips

Pitfalls

1. Indonesia-Specific Data:

   • Geographic models (e.g., Village, District) are Indonesia-only. Avoid using them for global projects.
   • Example: Village tables may not align with non-Indonesian administrative divisions.

2. Dynamic Relations:

   • Dynamic relations (e.g., branch, employee) require manual setup in boot() of a service provider. Forgetting this will cause Call to undefined method errors.
   • Example:

     // ❌ Will fail if not resolved
     $donor->branch; // Throws error
     

3. Migration Conflicts:

   • Shared migrations may conflict with existing tables. Run them last or override them in your app.
   • Example: If you already have a donors table, skip or modify the shared migration.

4. UUIDs:

   • Some models (e.g., Partner) use UUIDs. Ensure your Laravel app supports UUIDs (e.g., laravel/breeze or webpatser/laravel-uuid).

5. Typo Fixes:

   • Some migrations have typos (e.g., PR #28, #30). Review the changelog for fixes and apply them if needed.

6. Unmaintained Package:

   • Last release in 2026 with no recent commits. Test thoroughly with your Laravel version (e.g., 10.x).
   • Example: If using Laravel 10, check for compatibility with Illuminate\Database changes.

7. Dynamic Relation Performance:

   • Dynamic relations are resolved lazily, which can impact performance in complex queries. Use with() to eager-load them:

     $donor = Donor::with(['branch', 'employee'])->find(1);
     

Debugging

1. Dynamic Relation Errors:

   • If Donor::branch fails, check if the relation was resolved in boot():

     // Debug: Check if relation exists
     dd(Donor::relations());
     

2. Migration Errors:

   • If migrations fail, check for:
     • Duplicate columns (e.g., PR #20 fixed double-column issues).
     • Table name typos (e.g., PR #17, #18 fixed table key typos).

3. UUID Issues:

   • If using UUIDs, ensure your AppServiceProvider has:

     use Illuminate\Database\Eloquent\Concerns\HasUuids;
     

   • And your model uses the trait:

     class Partner extends Model
     {
         use HasUuids;
     }
     

4. Geographic Data Mismatches:

   • Verify village/district data matches Indonesian administrative boundaries. Use the search API (if implemented) to validate:

     $regions = \Inisiatif\ModelShared\Models\Region::search('Jakarta')->get();
     

Tips

1. Extend Models Safely:

   • Use extend() to add custom attributes without modifying the package:

     Donor::extend('customField', function ($model) {
         return $model->hasOne(CustomField::class);
     });
     

2. Customize Migrations:

   • Override shared migrations in your app to add custom columns:

     // In your migration
     Schema::table('donors', function (Blueprint $table) {
         $table->string('custom_column')->nullable();
     });
     

3. Use Traits:

   • Reuse traits from the package (e.g., HasDynamicRelations) in your models:

     use Inisiatif\ModelShared\Traits\HasDynamicRelations;
     
     class CustomDonor extends Donor
     {
         use HasDynamicRelations;
     }
     

4. Leverage Dynamic Relations:

   • Define dynamic relations for polymorphic associations (e.g., branch, employee) to avoid hardcoding foreign keys:

     Donor::resolveRelationUsing('branch', function ($model) {
         return $model->belongsTo(\App\Models\Branch::class, 'branch_id');
     });
     

5. Test Thoroughly:

   • Test shared models with edge cases (e.g., UUIDs, dynamic relations, geographic data).
   • Example test for dynamic relations:

     public function test_dynamic_relation()
     {
         $donor