Getting Started

Minimal Setup

Installation Add the package via Composer:

composer require chill-project/group

Publish the migration and config files:

php artisan vendor:publish --provider="Chill\Group\GroupServiceProvider" --tag="migrations"
php artisan vendor:publish --provider="Chill\Group\GroupServiceProvider" --tag="config"

Run the migrations:

php artisan migrate

Basic Configuration Check config/group.php for default settings (e.g., model bindings, soft deletes, or custom table names). Override as needed:
```
'models' => [
    'group' => \Chill\Group\Models\Group::class,
    'user_group' => \Chill\Group\Models\UserGroup::class,
],
```

First Use Case: Create a Group Define a group model (if not already extended) and create a group via Tinker or a controller:

use Chill\Group\Models\Group;

$group = Group::create([
    'name' => 'Developers',
    'description' => 'Team of backend developers',
]);

Assign Users to a Group Use the addUsers() method on the group model:
```
$group->addUsers([1, 2, 3]); // User IDs
```
Or attach users via the pivot table directly:
```
$group->users()->attach([1, 2, 3]);
```

Implementation Patterns

Common Workflows

Group Management

Create/Update Groups: Use Eloquent methods (create(), update()) on \Chill\Group\Models\Group.

$group = Group::updateOrCreate(
    ['name' => 'Designers'],
    ['description' => 'UI/UX Team']
);

Bulk Operations: Leverage collections for batch assignments:

$group->users()->sync(User::where('role', 'designer')->pluck('id'));

User-Group Relationships

Check Membership:

if ($group->users->contains($user)) {
    // User is in group
}

Dynamic Group Assignment: Use observers or events (e.g., Creating, Saved) to auto-assign users to groups based on rules:

// In UserObserver.php
public function created(User $user) {
    if ($user->role === 'admin') {
        $group = Group::where('name', 'Admins')->first();
        $group->addUsers([$user->id]);
    }
}

API/Controller Integration

Resource Controllers: Extend Laravel’s ResourceController to handle group CRUD:

public function store(Request $request) {
    $validated = $request->validate([
        'name' => 'required|string|max:255',
        'users' => 'sometimes|array',
    ]);
    $group = Group::create($validated);
    if (isset($validated['users'])) {
        $group->addUsers($validated['users']);
    }
    return response()->json($group, 201);
}

API Resources: Customize output with GroupResource:

public function toArray($request) {
    return [
        'id' => $this->id,
        'name' => $this->name,
        'user_count' => $this->users()->count(),
        'created_at' => $this->created_at->format('Y-m-d'),
    ];
}

Policy-Based Access Control Attach policies to groups/users for authorization:

// app/Policies/GroupPolicy.php
public function update(User $user, Group $group) {
    return $user->isAdmin() || $group->owner->is($user);
}

Gate::resources(['group'], 'GroupPolicy');

Event-Driven Extensions Listen for group events to trigger side effects (e.g., notifications, logs):

// In EventServiceProvider
protected $listen = [
    'Chill\Group\Events\GroupCreated' => [
        'App\Listeners\SendGroupWelcomeEmail',
    ],
];

Gotchas and Tips

Pitfalls

Pivot Table Conflicts
- If using a custom pivot table name (e.g., group_user), ensure it’s reflected in:
  - The Group model’s users() relationship.
  - The User model’s groups() relationship.
  - The migration for the pivot table.
- Fix: Update the group_user table name in both models and migrations.
Soft Deletes Misconfiguration
- If softDeletes is enabled in the Group model but the pivot table lacks a deleted_at column, sync operations may fail.
- Fix: Add deleted_at to the pivot table migration or disable soft deletes for the pivot.
Circular Dependencies
- Avoid circular references in group/user relationships (e.g., a group owning another group). Use many-to-many only for user-group ties.
- Tip: Document relationship rules in your architecture docs.
Performance with Large Groups
- Eager-load relationships to avoid N+1 queries:
```
$groups = Group::with('users')->get();
```
- For very large groups (>10k users), consider lazy-loading or pagination:
```
$group->users()->paginate(100);
```
Model Binding Quirks
- If using implicit model binding in routes (e.g., group/{group}), ensure the Group model’s resolveRouteBinding method is not overridden unless necessary.
- Debug Tip: Use php artisan route:list to verify route model binding works.

Debugging Tips

Log Relationship Issues Dump relationships to debug:
```
\Log::debug('Group users:', $group->users->toArray());
```
Or use Laravel Debugbar to inspect queries.
Check for Silent Failures
- Validate pivot table inserts manually:
```
DB::table('group_user')->where('group_id', $group->id)->exists();
```
- Enable query logging in .env:
```
DB_LOG_QUERIES=true
```

Event Debugging

Temporarily add a listener to log events:

Event::listen('Chill\Group\Events\GroupCreated', function ($event) {
    \Log::info('Group created:', $event->group->name);
});

Extension Points

Custom Group Types Extend the Group model to support hierarchical groups or metadata:

class TeamGroup extends Group {
    protected $casts = [
        'is_active' => 'boolean',
    ];
}

'models' => [
    'group' => \App\Models\TeamGroup::class,
],

Validation Rules Add custom validation to the Group model:

public static function boot() {
    parent::boot();
    static::creating(function ($group) {
        $group->validateUniqueName();
    });
}

API Filters Use Laravel Scout or custom filters for group search:

// In GroupController
public function index(Request $request) {
    $query = Group::query();
    if ($request->has('search')) {
        $query->where('name', 'like', "%{$request->search}%");
    }
    return $query->get();
}

Testing Use factories to seed test groups:

// database/factories/GroupFactory.php
$factory->define(Group::class, function (Faker $faker) {
    return [
        'name' => $faker->word,
        'description' => $faker->sentence,
    ];
});

Test relationships with:

$group = create(Group::class);
$group->addUsers(User::factory()->count(3)->create());
$this->assertCount(3, $group->fresh()->users);

Localization Translate group names/descriptions using Laravel’s localization:
```
'name' => __('groups.team'),
```
Add translations to resources/lang/{locale}/groups.php.

Group Laravel Package