介绍

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 许可