Manage Many-to-Many Relationships with Pivot Data

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class Role extends Model
{
    use HasFactory;

    protected $fillable = ['name'];

    public function users()
    {
        return $this->belongsToMany(User::class)->withPivot('status', 'notes');
    }
}

class User extends Model
{
    use HasFactory;

    protected $fillable = ['name', 'email', 'password'];

    public function roles()
    {
        return $this->belongsToMany(Role::class)->withPivot('status', 'notes')->withTimestamps();
    }
}

// Example usage in a controller or service:
/*
// Assuming $user is an instance of App\Models\User
// Assuming $roleIds is an array of role IDs, e.g., [1, 2, 3]

// 1. Attach a role with pivot data
$user->roles()->attach(4, ['status' => 'active', 'notes' => 'User manually assigned']);

// 2. Detach a role
$user->roles()->detach(4); // Detach by ID
// $user->roles()->detach([1, 2]); // Detach multiple

// 3. Sync roles (add/remove to match the given array)
// If user has roles 1, 2, 3 and we sync with [2, 4], role 1 and 3 are detached, role 4 is attached.
$user->roles()->sync([
    1 => ['status' => 'pending'],
    2 => ['status' => 'active', 'notes' => 'Re-synced status']
]);

// 4. Update pivot data for an existing relationship
$user->roles()->updateExistingPivot(1, ['status' => 'inactive', 'notes' => 'Temporarily suspended']);

// 5. Toggle a role (attach if not attached, detach if attached)
$user->roles()->toggle(5);
*/