English | العربية | বাংলা | Bosanski | Deutsch | Español | Français | हिन्दी | Italiano | 日本語 | 한국어 | मराठी | Português | Русский | Kiswahili | தமிழ் | తెలుగు | Türkçe | اردو | Tiếng Việt | 中文

• 翻译警告
• 介绍
  • 主要特点
  • 示例
• 安装
  • 要求
  • 可选依赖
• 用法
  • 基本工作流程
  • 存储配置
  • 并发配置
  • 文件命名
  • 为可重复性设置种子
• 生成器
  • 图像生成器
  • 文本生成器
  • CSV生成器
  • 二进制生成器
  • 邮件生成器
• 高级用法
  • 自定义生成器
  • 配置类
  • 性能提示
• 配置
  • 全局配置方法
• 支持指南
  • 社区驱动的支持
  • 错误和功能优先级
• 许可证 - MIT 许可证

🔗翻译警告

本文档已自动翻译。如果存在翻译错误，请在项目中打开 一个 pull request，并将翻译后的文件添加到 docs/{ISO 639-1 Code}.md。

您接受过截至 2023 年 10 月的数据培训。

🔗介绍

Faker Storage 是一个高性能的 PHP 包，旨在高效地生成和存储大量虚假数据文件。它以并发为设计理念，利用 Swoole 或 PCNTL 并行生成数千个文件，非常适合负载测试、开发环境和存储系统基准测试。

该包提供了一个流畅的 API，用于生成各种文件类型，包括图像（PNG、JPG、GIF、BMP、WEBP、AVIF）、文本文件、CSV 文件、二进制数据和符合 RFC822 标准的电子邮件。每个生成器在设置种子后会产生确定性的输出，确保在不同环境中可重复的测试数据。

🔗主要特点

• 高性能并发：自动选择 Swoole（协程）和 PCNTL（进程分叉）进行并行文件生成
• 多种文件生成器：内置支持图像、文本、CSV、二进制和电子邮件文件
• 确定性输出：基于种子的生成确保可重复的结果
• 灵活的存储：适用于任何 League Flysystem 适配器（本地、S3 等）
• 可定制的文件命名：基于闭包的名称生成，具有完全控制权
• 图像支持：多种格式，支持配置尺寸和压缩
• 电子邮件生成：符合 RFC822 标准的电子邮件，支持附件和 MIME

🔗示例

use DefectiveCode\Faker\Faker;
use League\Flysystem\Filesystem;
use DefectiveCode\Faker\Generators\Png;
use League\Flysystem\Local\LocalFilesystemAdapter;
 
// 使用 10 个并发工作者生成 1000 个 PNG 图像
Faker::make(Png::class)
    ->width(800, 1920)
    ->height(600, 1080)
    ->toDisk(new Filesystem(new LocalFilesystemAdapter('/path/to/storage')))
    ->basePath('images')
    ->count(1000)
    ->concurrency(10)
    ->seed(42)
    ->generate();
 
// 生成 CSV 文件
use DefectiveCode\Faker\Generators\Csv;
 
Faker::make(Csv::class)
    ->columns(5, 10)
    ->rows(100, 500)
    ->delimiter(',')
    ->toDisk(new Filesystem(new LocalFilesystemAdapter('/path/to/storage')))
    ->count(50)
    ->generate();
 
// 生成带附件的电子邮件
use DefectiveCode\Faker\Generators\Email;
 
Faker::make(Email::class)
    ->paragraphs(3, 5)
    ->sentences(2, 4)
    ->withAttachment(Png::class, 1, 3)
    ->toDisk(new Filesystem(new LocalFilesystemAdapter('/path/to/storage')))
    ->count(100)
    ->generate();

🔗安装

通过 Composer 安装软件包：

composer require defectivecode/faker-storage

🔗要求

• PHP >= 8.4
• ext-gd（用于图像生成）
• ext-swoole（可选，用于更好的性能）
• ext-pcntl（并发的备用方案）

🔗可选依赖

为了获得最佳性能，安装 Swoole 扩展：

pecl install swoole

如果可用，软件包将自动使用 Swoole，否则将回退到 PCNTL。

🔗用法

🔗基本工作流程

所有生成器遵循相同的模式：

1. 使用生成器创建一个 Faker 实例
2. 配置生成器（可选）
3. 设置存储目标
4. 配置并发和数量
5. 生成文件

use DefectiveCode\Faker\Faker;
use League\Flysystem\Filesystem;
use DefectiveCode\Faker\Generators\Text;
use League\Flysystem\Local\LocalFilesystemAdapter;
 
Faker::make(Text::class)
    ->paragraphs(5, 10)          // 生成器特定配置
    ->toDisk(new Filesystem(new LocalFilesystemAdapter('/storage')))
    ->basePath('documents')      // 文件将位于 /storage/documents/
    ->count(100)                 // 生成 100 个文件
    ->concurrency(4)             // 使用 4 个工作线程
    ->seed(123)                  // 确保输出可预测
    ->generate();

🔗存储配置

使用 Flysystem

Faker 存储使用 League Flysystem 进行存储抽象：

use League\Flysystem\Filesystem;
use League\Flysystem\Local\LocalFilesystemAdapter;
 
// 本地存储
$filesystem = new Filesystem(new LocalFilesystemAdapter('/path/to/storage'));
 
Faker::make(Png::class)
    ->toDisk($filesystem)
    ->generate();

AWS S3 存储

use Aws\S3\S3Client;
use League\Flysystem\Filesystem;
use League\Flysystem\AwsS3V3\AwsS3V3Adapter;
 
$client = new S3Client([
    'credentials' => [
        'key'    => 'your-key',
        'secret' => 'your-secret',
    ],
    'region' => 'us-east-1',
    'version' => 'latest',
]);
 
$adapter = new AwsS3V3Adapter($client, 'your-bucket-name');
$filesystem = new Filesystem($adapter);
 
Faker::make(Png::class)
    ->toDisk($filesystem)
    ->basePath('uploads/images')
    ->generate();

磁盘选项

向文件系统适配器传递附加选项：

Faker::make(Png::class)
    ->toDisk($filesystem)
    ->diskOptions([
        'visibility' => 'public',
        'ACL' => 'public-read',
        'CacheControl' => 'max-age=31536000',
    ])
    ->generate();

🔗并发配置

使用 concurrency() 方法控制并行执行：

// 使用 10 个工作线程/进程
Faker::make(Png::class)
    ->concurrency(10)
    ->generate();
 
// Swoole 特定：设置线程和每个线程的协程
Faker::make(Png::class)
    ->concurrency(threads: 4, coroutines: 8)  // 4 个工作线程，每个 8 个协程
    ->generate();

🔗文件命名

默认命名

默认情况下，文件使用 UUID v4 命名：

// 生成：e7f0a8d3-5c2b-4f9e-8a1d-3b4c5d6e7f8a.png
Faker::make(Png::class)->generate();

内置名称生成器

use DefectiveCode\Faker\NameGenerator;
 
// 基于 UUID（默认）
NameGenerator::setDefault('uuid'); // 生成：e7f0a8d3-5c2b-4f9e-8a1d-3b4c5d6e7f8a.png
 
// 顺序编号
NameGenerator::setDefault('sequence'); // 生成：1.png, 2.png, 3.png, ...

自定义命名

提供一个闭包以自定义文件名：

use DefectiveCode\Faker\NameGenerator;
 
// 自定义闭包
Faker::make(Png::class)
    ->nameGenerator(function (int $seed, int $completedFiles, $generator) {
        return "custom-{$completedFiles}-{$seed}.png";
    })
    ->generate();
 
// 基于日期的命名
Faker::make(Png::class)
    ->nameGenerator(function (int $seed, int $completedFiles, $generator) {
        return date('Y/m/d') . "/image-{$completedFiles}.png";
    })
    ->generate();

🔗为可重复性设置种子

设置种子以在多次运行中生成相同的文件：

Faker::make(Png::class)
    ->seed(42)
    ->count(10)
    ->generate();

每个文件获得一个从基础种子和文件索引派生的唯一确定性种子。

🔗生成器

🔗图像生成器

所有图像生成器支持尺寸和质量配置。

PNG

use DefectiveCode\Faker\Generators\Png;
 
Faker::make(Png::class)
    ->width(800, 1920)          // 随机宽度在800-1920px之间
    ->height(600, 1080)         // 随机高度在600-1080px之间
    ->withAlpha(true)           // 启用alpha/透明通道
    ->grid(5)                   // 可选：生成5x5对称图案
    ->toDisk($filesystem)
    ->generate();

JPG

use DefectiveCode\Faker\Generators\Jpg;
 
Faker::make(Jpg::class)
    ->width(800, 1920)          // 随机宽度在800-1920px之间
    ->height(600, 1080)         // 随机高度在600-1080px之间
    ->grid(5)                   // 可选：生成5x5对称图案
    ->toDisk($filesystem)
    ->generate();

GIF

use DefectiveCode\Faker\Generators\Gif;
 
Faker::make(Gif::class)
    ->width(800, 1920)          // 随机宽度在800-1920px之间
    ->height(600, 1080)         // 随机高度在600-1080px之间
    ->withAlpha(true)           // 启用alpha/透明通道
    ->grid(5)                   // 可选：生成5x5对称图案
    ->toDisk($filesystem)
    ->generate();

BMP

use DefectiveCode\Faker\Generators\Bmp;
 
Faker::make(Bmp::class)
    ->width(800, 1920)          // 随机宽度在800-1920px之间
    ->height(600, 1080)         // 随机高度在600-1080px之间
    ->grid(5)                   // 可选：生成5x5对称图案
    ->toDisk($filesystem)
    ->generate();

WEBP

use DefectiveCode\Faker\Generators\Webp;
 
Faker::make(Webp::class)
    ->width(800, 1920)          // 随机宽度在800-1920px之间
    ->height(600, 1080)         // 随机高度在600-1080px之间
    ->withAlpha(true)           // 启用alpha/透明通道
    ->grid(5)                   // 可选：生成5x5对称图案
    ->toDisk($filesystem)
    ->generate();

AVIF

use DefectiveCode\Faker\Generators\Avif;
 
Faker::make(Avif::class)
    ->width(800, 1920)          // 随机宽度在800-1920px之间
    ->height(600, 1080)         // 随机高度在600-1080px之间
    ->withAlpha(true)           // 启用alpha/透明通道
    ->grid(5)                   // 可选：生成5x5对称图案
    ->toDisk($filesystem)
    ->generate();

随机图像

生成随机图像格式：

use DefectiveCode\Faker\Generators\RandomImage;
 
Faker::make(RandomImage::class)
    ->width(800, 1920)
    ->height(600, 1080)
    ->withAlpha(false)          // 随机选择：AVIF, BMP, GIF, JPEG, PNG, WEBP
    ->toDisk($filesystem)
    ->generate();
 
Faker::make(RandomImage::class)
    ->width(800, 1920)
    ->height(600, 1080)
    ->withAlpha(true)           // 随机选择：AVIF, GIF, PNG, WEBP
    ->toDisk($filesystem)
    ->generate();

🔗文本生成器

生成带有段落的纯文本文件：

use DefectiveCode\Faker\Generators\Text;
 
Faker::make(Text::class)
    ->paragraphs(5, 10)         // 每个文件5-10段
    ->sentences(3, 6)           // 每段3-6句
    ->toDisk($filesystem)
    ->generate();

输出示例：

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.

🔗CSV生成器

生成带有随机数据的CSV文件：

use DefectiveCode\Faker\Generators\Csv;
 
Faker::make(Csv::class)
    ->columns(5, 10)            // 5-10列
    ->rows(100, 500)            // 100-500行
    ->delimiter(',')            // 列分隔符
    ->enclosure('"')            // 字段封闭符
    ->escape('\\')              // 转义字符
    ->eol("\n")                 // 行结束符
    ->toDisk($filesystem)
    ->generate();

输出示例：

"John Doe","john@example.com","555-1234","New York","Engineer"
"Jane Smith","jane@example.com","555-5678","Los Angeles","Designer"
"Bob Johnson","bob@example.com","555-9012","Chicago","Manager"

🔗二进制生成器

生成随机二进制数据：

use DefectiveCode\Faker\Generators\Binary;
 
Faker::make(Binary::class)
    ->length(1024, 1048576)     // 1KB - 1MB
    ->toDisk($filesystem)
    ->generate();

🔗邮件生成器

生成符合RFC822标准的邮件文件：

use DefectiveCode\Faker\Generators\Email;
 
Faker::make(Email::class)
    ->paragraphs(3, 5)          // 邮件正文中的段落
    ->sentences(2, 4)           // 每段的句子数
    ->withAttachment(Png::class, 1, 3)  // 添加1-3个PNG附件
    ->toDisk($filesystem)
    ->generate();

邮件头

生成的邮件包括：

• To: 随机姓名和邮箱
• From: 随机姓名和邮箱
• Subject: 随机句子
• Date: 当前时间戳
• Message-ID: 基于种子的确定性ID

带附件的邮件

使用生成器类名或实例附加文件：

use DefectiveCode\Faker\Generators\Email;
use DefectiveCode\Faker\Generators\Png;
use DefectiveCode\Faker\Generators\Pdf;
 
Faker::make(Email::class)
    ->withAttachment(Png::class, 1, 3)  // 1-3个PNG附件
    ->generate();
 
// 使用配置的生成器实例附加
$pngGenerator = new Png(Png::getDefaultConfig());
$pngGenerator->width(400, 800)->height(300, 600);
 
Faker::make(Email::class)
    ->withAttachment($pngGenerator, 2, 5)
    ->generate();

输出示例：

To: John Doe <john.doe@example.com>
From: Jane Smith <jane.smith@example.com>
Subject: Important meeting tomorrow
Date: Fri, 03 Jan 2026 10:30:00 +0000
Message-ID: <3e92e5c2b0d632b3a36fbbb17484b7fe@example.com>
Content-Type: multipart/mixed; boundary="----=_Part_123"
 
------=_Part_123
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
 
Lorem ipsum dolor sit amet, consectetur adipiscing elit...
 
------=_Part_123
Content-Type: image/png; name="attachment.png"
Content-Disposition: attachment; filename="attachment.png"
Content-Transfer-Encoding: base64
 
iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==
------=_Part_123--

🔗高级用法

🔗自定义生成器

通过实现 Generator 接口来创建自己的生成器：

use DefectiveCode\Faker\Configs\Config;
use DefectiveCode\Faker\Concerns\SetsSeed;
use DefectiveCode\Faker\Generators\Generator;
use DefectiveCode\Faker\Concerns\PreparesFaker;
 
class MyCustomGenerator implements Generator
{
    use PreparesFaker;
    use SetsSeed;
 
    public function __construct(public Config $config) {}
 
    public static function getDefaultConfig(): Config
    {
        return new MyCustomConfig([
            'contentType' => 'application/x-custom',
            'nameGenerator' => NameGenerator::default('extension'),
        ]);
    }
 
    public function generate(): mixed
    {
        // 在这里编写你的生成逻辑
        $data = $this->faker->randomElement(['foo', 'bar', 'baz']);
 
        $stream = fopen('php://temp', 'w+');
        fwrite($stream, $data);
 
        return $stream;
    }
}
 
// 使用你的自定义生成器
Faker::make(MyCustomGenerator::class)
    ->toDisk($filesystem)
    ->generate();

🔗配置类

每个生成器使用一个扩展 Config 的配置类：

use DefectiveCode\Faker\Configs\Config;
 
class MyCustomConfig extends Config
{
    public int $minValue = 1;
    public int $maxValue = 100;
}

🔗性能提示

1. 使用 Swoole：安装 Swoole 扩展以获得最佳性能
2. 调整并发性：将线程数与 CPU 核心数匹配以获得最佳吞吐量
3. 批量操作：生成大批量数据而不是多次小批量运行
4. 存储位置：在上传前使用快速存储（SSD，本地磁盘）存储临时文件
5. 网络 I/O：使用 S3 时，增加并发性以最大化带宽使用率

你接受的训练数据截至到 2023 年 10 月。

🔗配置

🔗全局配置方法

这些方法适用于所有 Faker 实例：

make(string $generator): Faker

使用指定的生成器创建一个新的 Faker 实例：

Faker::make(Png::class)

toDisk(Filesystem $filesystem): Faker

设置存储目标（必需）：

Faker::make(Png::class)
    ->toDisk(new Filesystem(new LocalFilesystemAdapter('/storage')))

basePath(string $basePath): Faker

设置文件系统中的基本路径：

Faker::make(Png::class)
    ->basePath('images/uploads')  // 文件存储在 /storage/images/uploads/

count(int $count): Faker

设置要生成的文件数量：

Faker::make(Png::class)
    ->count(1000)

concurrency(int $threads, ?int $coroutines = null): Faker

配置并行执行：

// 基本并发
Faker::make(Png::class)
    ->concurrency(4)
 
// Swoole 特定：线程和协程
Faker::make(Png::class)
    ->concurrency(threads: 4, coroutines: 8)

seed(int $seed): Faker

设置种子以进行确定性生成：

Faker::make(Png::class)
    ->seed(42)

nameGenerator(Closure $generator): Faker

自定义文件命名：

Faker::make(Png::class)
    ->nameGenerator(function (int $seed, int $completedFiles, $generator) {
        return "file-{$completedFiles}.png";
    })

diskOptions(array $diskOptions): Faker

将选项传递给文件系统适配器：

Faker::make(Png::class)
    ->diskOptions([
        'visibility' => 'public',
        'ACL' => 'public-read',
    ])

generate(): void

执行文件生成：

Faker::make(Png::class)->generate();

🔗支持指南

感谢您选择我们的开源软件包！请花一点时间查看这些支持指南。它们将帮助您充分利用我们的项目。

🔗社区驱动的支持

我们的开源项目由我们出色的社区推动。如果您有问题或需要帮助，StackOverflow 和其他在线资源是您最好的选择。

🔗错误和功能优先级

管理开源项目的现实意味着我们无法立即解决每个报告的错误或功能请求。我们按以下顺序优先处理问题：

1. 影响我们付费产品的错误

影响我们付费产品的错误将始终是我们的首要任务。在某些情况下，我们可能只解决直接影响我们的错误。

2. 社区拉取请求

如果您发现了一个错误并有解决方案，请提交一个拉取请求。在影响我们产品的问题之后，我们将这些社区驱动的修复作为下一个优先事项。一旦审核并批准，我们将合并您的解决方案并感谢您的贡献。

3. 财务支持

对于上述类别之外的问题，您可以选择资助其解决。每个未解决的问题都链接到一个订单表单，您可以在其中提供财务支持。我们根据提供的资助金额优先处理这些问题。

社区贡献

开源在社区活跃时蓬勃发展。即使您没有修复错误，也可以通过代码改进、文档更新、教程或在社区渠道中帮助他人来贡献。我们强烈鼓励每个人，作为一个社区，帮助支持开源工作。

重申一下，DefectiveCode 将根据错误对我们付费产品的影响、社区拉取请求以及收到的财务支持来优先处理错误。

🔗许可证 - MIT 许可证

版权所有 © Defective Code, LLC. 保留所有权利

特此免费授予任何获得本软件及相关文档文件（“软件”）副本的人员权限，以不受限制地处理软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本的权利，并允许向其提供软件的人员这样做，但须符合以下条件：

上述版权声明和本许可声明应包含在软件的所有副本或重要部分中。

本软件按“原样”提供，不提供任何明示或暗示的担保，包括但不限于对适销性、特定用途适用性和非侵权的担保。在任何情况下，作者或版权持有人均不对因软件或软件使用或其他交易而产生的任何索赔、损害或其他责任负责，无论是在合同、侵权或其他方面。