PHP项目Symfony filesystem与mkdir

wen PHP项目 2026-07-23 3

本文目录导读：

基本用法
核心特性
在Symfony项目中的实际应用
与PHP原生 mkdir 的比较
最佳实践
注意事项
示例：处理文件上传目录

在Symfony项目中，mkdir 是一个用于创建目录的方法，它属于 Symfony\Component\Filesystem\Filesystem 类，下面详细说明它的用法、特性以及注意事项。

基本用法

use Symfony\Component\Filesystem\Filesystem;
$fs = new Filesystem();
// 创建单个目录
$fs->mkdir('/path/to/directory');
// 递归创建多级目录
$fs->mkdir('/path/to/nested/directory/structure');
// 创建多个目录
$fs->mkdir([
    '/path/to/first',
    '/path/to/second',
]);

核心特性

自动递归创建

与PHP原生的 mkdir() 不同，Symfony的 mkdir 默认就会递归创建目录，不需要额外设置 $recursive = true 参数：

// Symfony - 自动处理递归
$fs->mkdir('/var/www/project/var/cache/dev');
// 等同于PHP原生写法
mkdir('/var/www/project/var/cache/dev', 0777, true);

权限设置

可以指定目录权限：

// 设置权限为 0755
$fs->mkdir('/path/to/dir', 0755);
// 使用默认权限
$fs->mkdir('/path/to/dir');

注意：默认权限会受到当前 umask 的影响，如果要强制设置精确权限，需要先设置 umask：

$old = umask(0);
$fs->mkdir('/path/to/dir', 0777);
umask($old);

错误处理

如果创建失败,会抛出异常：

try {
    $fs->mkdir('/path/with/no/permission');
} catch (IOException $e) {
    echo '目录创建失败: ' . $e->getMessage();
}

幂等性

如果目录已经存在，mkdir 不会报错,也不会覆盖现有目录：

$fs->mkdir('/existing/dir'); // 安全，不会报错

在Symfony项目中的实际应用

在控制器中使用

// src/Controller/FileController.php
use Symfony\Component\Filesystem\Filesystem;
class FileController extends AbstractController
{
    #[Route('/upload', name: 'file_upload')]
    public function upload(Request $request): Response
    {
        $filesystem = new Filesystem();
        $uploadDir = $this->getParameter('kernel.project_dir') . '/public/uploads/' . date('Y/m/d');
        // 创建按日期组织的目录
        $filesystem->mkdir($uploadDir);
        // ... 处理文件上传
    }
}

在服务中使用

// src/Service/FileManager.php
use Symfony\Component\Filesystem\Filesystem;
class FileManager
{
    private Filesystem $filesystem;
    private string $baseDir;
    public function __construct(Filesystem $filesystem, string $baseDir)
    {
        $this->filesystem = $filesystem;
        $this->baseDir = $baseDir;
    }
    public function ensureDirectoryExists(string $path): void
    {
        $fullPath = $this->baseDir . '/' . $path;
        $this->filesystem->mkdir($fullPath);
    }
}

在Console命令中使用

// src/Command/SetupCommand.php
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Filesystem\Filesystem;
class SetupCommand extends Command
{
    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $fs = new Filesystem();
        $directories = [
            'var/cache/dev',
            'var/cache/prod',
            'var/log',
            'public/uploads/temp',
        ];
        foreach ($directories as $dir) {
            $fs->mkdir($dir);
            $output->writeln("创建目录: $dir");
        }
        return Command::SUCCESS;
    }
}

与PHP原生 mkdir 的比较

特性	Symfony Filesystem::mkdir	PHP mkdir()
递归创建	默认支持	需要 `$recursive = true`
异常处理	抛出 `IOException`	返回 `false` + 警告
幂等性	目录存在时不报错	目录存在时返回 `false` 或警告
多目录	支持数组参数	不支持
权限控制	支持	支持

最佳实践

目录路径规范化

$fs->mkdir($fs->makePathRelative($targetDir, $baseDir));

结合路径检查

if (!$fs->exists($dir)) {
    $fs->mkdir($dir);
}

设置安全的默认权限

// 创建web可访问目录但限制权限
$fs->mkdir($dir, 0755);

清理临时目录

// 创建并确保目录为空
$fs->remove($tempDir);
$fs->mkdir($tempDir);

注意事项

权限问题：确保PHP进程有权限在目标位置创建目录
路径安全问题：注意路径遍历攻击，验证用户输入的路径
并发处理：多个请求同时创建同一目录时，mkdir 是安全的
文件系统类型：某些文件系统（如FAT32）可能有其他限制

示例：处理文件上传目录

// 完整的上传目录管理
class UploadManager
{
    public function __construct(
        private Filesystem $filesystem,
        private string $uploadDir
    ) {}
    public function prepareUploadDirectory(string $subDir): string
    {
        $targetDir = $this->uploadDir . '/' . $subDir;
        // 规范化路径
        $targetDir = realpath($this->uploadDir) . '/' . ltrim($subDir, '/');
        // 安全检查
        if (strpos($targetDir, realpath($this->uploadDir)) !== 0) {
            throw new \InvalidArgumentException('Invalid directory path');
        }
        // 创建目录
        $this->filesystem->mkdir($targetDir, 0755);
        return $targetDir;
    }
}

这样，Symfony的 mkdir 提供了比PHP原生函数更安全、更方便的目录创建方式,特别适合需要递归创建和异常处理的场景。