Family Members Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require chill-project/family-members
   

   Publish the migration and config:

   php artisan vendor:publish --provider="Chill\FamilyMembers\FamilyMembersServiceProvider" --tag="migrations"
   php artisan vendor:publish --provider="Chill\FamilyMembers\FamilyMembersServiceProvider" --tag="config"
   

2. Run Migration

   php artisan migrate
   

3. First Use Case Register a family member via the FamilyMember model:

   use Chill\FamilyMembers\Models\FamilyMember;
   
   $member = FamilyMember::create([
       'first_name' => 'John',
       'last_name'  => 'Doe',
       'relationship' => 'parent',
       'birth_date' => '1980-01-01',
       'file_id'    => 1, // ID of the associated Chill file
   ]);
   

4. Key Files to Explore

   • config/family-members.php (for configuration options)
   • app/Models/FamilyMember.php (model logic)
   • database/migrations/..._create_family_members_table.php (schema)

Implementation Patterns

Core Workflows

1. CRUD Operations Use Eloquent for standard operations:

   // Fetch all members for a file
   $members = FamilyMember::where('file_id', 1)->get();
   
   // Update a member
   $member->update(['relationship' => 'guardian']);
   

2. Relationships Define polymorphic relationships with Chill files:

   // In File model (if extending Chill)
   public function familyMembers()
   {
       return $this->hasMany(FamilyMember::class);
   }
   

3. Validation Leverage Laravel’s validation rules (e.g., required|date for birth_date):

   use Illuminate\Support\Facades\Validator;
   
   $validator = Validator::make($data, [
       'first_name' => 'required|string|max:255',
       'birth_date' => 'required|date',
   ]);
   

4. API Integration Use Laravel’s API resources:

   php artisan make:resource FamilyMemberResource
   

   // FamilyMemberResource.php
   public function toArray($request)
   {
       return [
           'name' => $this->first_name . ' ' . $this->last_name,
           'relationship' => $this->relationship,
       ];
   }
   

5. Events & Listeners Trigger events for lifecycle hooks (e.g., Creating, Deleted):

   // Example listener for file deletion
   FamilyMember::observe(FileDeletedObserver::class);
   

Gotchas and Tips

Pitfalls

1. File Association

   • Issue: Forgetting to link file_id will orphan records.
   • Fix: Use belongsTo in FamilyMember model:

     public function file()
     {
         return $this->belongsTo(Chill\Files\Models\File::class);
     }
     

2. Data Validation

   • Issue: Missing validation for relationship field (e.g., custom enum values).
   • Fix: Add a custom rule or use Laravel’s in: rule:

     'relationship' => 'required|in:parent,child,guardian,spouse',
     

3. Migration Conflicts

   • Issue: Schema changes in future updates may conflict with existing data.
   • Fix: Use Schema::table() for safe alterations or document migration steps.

4. Performance

   • Issue: N+1 queries when eager-loading relationships.
   • Fix: Use with():

     $file = File::with('familyMembers')->find(1);
     

Debugging Tips

1. Log Family Members Enable query logging in config/database.php:

   'log' => env('DB_LOG', false),
   

   Then check storage/logs/laravel.log.

2. Check Config Verify config/family-members.php for custom settings (e.g., default relationships).

3. Seeding Use Laravel’s seeder to populate test data:

   php artisan make:seeder FamilyMembersTableSeeder
   

Extension Points

1. Custom Fields Extend the family_members table via migrations:

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

2. Observers Add custom logic to app/Observers/FamilyMemberObserver.php:

   public function saving(FamilyMember $member)
   {
       $member->normalizeNames();
   }
   

3. API Filters Use Laravel Scout or custom filters for search:

   // Example: Filter by relationship
   $members = FamilyMember::where('relationship', 'parent')->get();
   

4. Localization Translate fields (e.g., relationship) via Laravel’s localization:

   // config/app.php
   'locale' => 'fr',