PHP 建立目錄：mkdir() 函數完整用法、遞迴建立與權限設定

前言

mkdir() 可建立單層或多層目錄。本文詳細說明參數、遞迴模式、權限位元遮罩、競態條件處理與現代替代方案。

函數簽名

mkdir(
    string $directory,
    int $permissions = 0777,
    bool $recursive = false,
    ?resource $context = null
): bool

基本範例

<?php
$dir = '/tmp/my_project/data/logs';

// 遞迴建立多層目錄
if (!file_exists($dir)) {
    if (mkdir($dir, 0755, true)) {
        echo "目錄建立成功: $dir\n";
    } else {
        echo "建立失敗\n";
    }
} else {
    echo "目錄已存在\n";
}
?>

權限位元遮罩詳細說明

• 0755：擁有者 rwx，群組 rx，其他 rx（目錄標準權限）。
• 0777：所有人 rwx（預設，受 umask 影響）。
• 實際權限 = 權限 & ~umask。預設 umask 通常為 0022，故 0777 實際為 0755。
• Windows 忽略權限參數，但參數必須提供。

競態條件與原子性

<?php
// 錯誤寫法：TOCTOU (Time-of-check to time-of-use)
if (!file_exists($dir)) {
    mkdir($dir, 0755, true); // 此處可能另一進程已建立
}

// 正確寫法：直接嘗試建立，忽略 EEXIST 錯誤
$success = @mkdir($dir, 0755, true);
if ($success || (file_exists($dir) && is_dir($dir))) {
    // 目錄確保存在
}
?>

現代替代：Symfony Filesystem

<?php
use Symfony\Component\Filesystem\Filesystem;

$fs = new Filesystem();
$fs->mkdir('/tmp/my_project/data/logs', 0755);
// 自動處理遞迴、存在檢查、權限、例外拋出
?>

總結

mkdir($dir, 0755, true) 是建立多層目錄的標準寫法。理解 umask 對權限的影響、避免 TOCTOU 競態條件，生產環境可引入 Symfony Filesystem 簡化錯誤處理。希望本文對您的 PHP 程式設計有所幫助。