简介

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;
 
// 生成 1000 个 PNG 图像，使用 10 个并发工作线程
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。

使用

基本工作流程

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

使用生成器创建一个 Faker 实例
配置生成器（可选）
设置存储目的地
配置并发和数量
生成文件

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 Storage 使用 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;
}

性能提示

使用 Swoole：安装 Swoole 扩展以获得最佳性能
调整并发：将线程数与 CPU 核心数匹配，以实现最佳吞吐量
批量操作：生成大批量文件，而不是多次小规模运行
存储位置：使用快速存储（SSD、本地磁盘）处理临时文件，然后再上传
网络 I/O：使用 S3 时，增加并发以最大化带宽利用率

配置

全局配置方法

这些方法适用于所有 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 许可

特此免费授权任何获得此软件及相关文档文件（“软件”）副本的人，允许在软件中自由处理，包括不限于使用、复制、修改、合并、发布、分发、再授权和/或销售软件副本的权利，并允许被提供软件的人这样做，前提是满足以下条件：

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

🔗简介

🔗主要特性

🔗示例

🔗安装

🔗要求

🔗可选依赖

🔗使用

🔗基本工作流程

🔗存储配置

使用 Flysystem

AWS S3 存储

磁盘选项

🔗并发配置

🔗文件命名

默认命名

内置名称生成器

自定义命名

🔗可重现性播种

🔗生成器

🔗图像生成器

PNG

JPG

GIF

BMP

WEBP

AVIF

随机图像

🔗文本生成器

🔗CSV 生成器

🔗二进制生成器

🔗电子邮件生成器

电子邮件头

带有附件的电子邮件

🔗高级用法

🔗自定义生成器

🔗配置类

🔗性能提示

🔗配置

🔗全局配置方法

make(string $generator): Faker

toDisk(Filesystem $filesystem): Faker

basePath(string $basePath): Faker

count(int $count): Faker

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

seed(int $seed): Faker

nameGenerator(Closure $generator): Faker

diskOptions(array $diskOptions): Faker

generate(): void

🔗支持指南

🔗社区驱动支持

🔗错误和功能优先级

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

2. 社区拉取请求

3. 财务支持

社区贡献

🔗许可 - MIT 许可

简介

主要特性

示例

安装

要求

可选依赖

使用

基本工作流程

存储配置

并发配置

文件命名

可重现性播种

生成器

图像生成器

文本生成器

CSV 生成器

二进制生成器

电子邮件生成器

高级用法

自定义生成器

配置类

性能提示

配置

全局配置方法

`make(string $generator): Faker`

`toDisk(Filesystem $filesystem): Faker`

`basePath(string $basePath): Faker`

`count(int $count): Faker`

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

`seed(int $seed): Faker`

`nameGenerator(Closure $generator): Faker`

`diskOptions(array $diskOptions): Faker`

`generate(): void`

支持指南

社区驱动支持

错误和功能优先级

许可 - MIT 许可