PHP chgrp 函數：變更檔案群組完整教學

chgrp：變更檔案所屬群組的系統管理函數

chgrp() 用於變更檔案或目錄的群組擁有權。配合 chown()、chmod() 組成檔案權限管理鐵三角，常用於多用戶協作環境、部署腳本、共享目錄設定。

函數語法

chgrp(string $filename, string|int $group): bool

參數說明

權限需求

• Root：可變更為任意群組
• 一般用戶：只能變更為自己所屬的群組（需檢查 /etc/group）
• PHP 執行用戶：決定實際權限（如 www-data、php-fpm）

基本範例

<?php
$file = '/var/www/shared/document.pdf';
$group = 'www-data'; // 或 GID：33

if (chgrp($file, $group)) {
    echo "群組變更成功：$group";
} else {
    echo "變更失敗";
}

// 驗證
$stat = stat($file);
$groupInfo = posix_getgrgid($stat['gid']);
echo "目前群組：" . $groupInfo['name'] . " (GID: {$stat['gid']})";
?>

遞迴變更目錄樹群組

<?php
function chgrpRecursive(string $path, string|int $group): array {
    $results = ['success' => 0, 'failed' => []];
    
    $iterator = new RecursiveIteratorIterator(
        new RecursiveDirectoryIterator($path, RecursiveDirectoryIterator::SKIP_DOTS),
        RecursiveIteratorIterator::SELF_FIRST
    );
    
    foreach ($iterator as $file) {
        $filePath = $file->getPathname();
        if (chgrp($filePath, $group)) {
            $results['success']++;
        } else {
            $results['failed'][] = $filePath;
        }
    }
    
    return $results;
}

// 使用
$results = chgrpRecursive('/var/www/shared', 'developers');
echo "成功：{$results['success']}, 失敗：" . count($results['failed']);
?>

搭配 chown + chmod：標準部署權限設定

<?php
function setDeploymentPermissions(string $path, string $user, string $group, int $dirMode = 0755, int $fileMode = 0644): void {
    $iterator = new RecursiveIteratorIterator(
        new RecursiveDirectoryIterator($path, RecursiveDirectoryIterator::SKIP_DOTS),
        RecursiveIteratorIterator::SELF_FIRST
    );
    
    foreach ($iterator as $file) {
        $filePath = $file->getPathname();
        
        // 變更擁有者與群組
        chown($filePath, $user);
        chgrp($filePath, $group);
        
        // 設定權限
        $mode = $file->isDir() ? $dirMode : $fileMode;
        chmod($filePath, $mode);
    }
    
    // 根目錄
    chown($path, $user);
    chgrp($path, $group);
    chmod($path, $dirMode);
}

// 典型 Laravel/專案部署
setDeploymentPermissions(
    '/var/www/myapp',
    'www-data',    // user
    'www-data',    // group
    0755,          // 目錄權限
    0644           // 檔案權限
);

// storage、bootstrap/cache 需寫入權限
setDeploymentPermissions('/var/www/myapp/storage', 'www-data', 'www-data', 0775, 0664);
setDeploymentPermissions('/var/www/myapp/bootstrap/cache', 'www-data', 'www-data', 0775, 0664);
?>

常見錯誤與解決

Windows 環境

• Windows 不支援 chgrp（使用 ACL 機制）
• 函數存在但總回傳 false
• 需用 icacls、PowerShell 設定 ACL

相關函數

• chown() - 變更擁有者
• chmod() - 變更權限
• filegroup() - 取得檔案 GID
• fileowner() - 取得檔案 UID
• posix_getgrgid() - GID 解析群組資訊
• posix_getpwuid() - UID 解析用戶資訊

最佳實務

1. 部署腳本中統一設定群組為 Web 服務群組（如 www-data）
2. 共享目錄設定 setgid 位（chmod g+s）：新建檔案自動繼承群組
3. 使用 GID 而非群組名（避免名稱解析、效能更好）
4. 容器環境在 Dockerfile 用 RUN groupadd -g 1000 app && useradd -u 1000 -g app app 固定 UID/GID
5. 大量操作考慮系統指令 chgrp -R group path
6. 操作記錄日誌：時間、路徑、原群組、新群組、執行用戶

chgrp 是多用戶環境下檔案共享的關鍵工具，正確配合 chown、chmod、setgid，能建立安全且便利的協作檔案系統。