Introdução
- Principais Características
- Exemplo
Instalação
- Requisitos
- Dependências Opcionais
Uso
Geradores
Uso Avançado
Configuração
- Métodos de Configuração Global
Diretrizes de Suporte
- Suporte Direcionado pela Comunidade
- Erros e Priorização de Recursos
Licença - Licença MIT

Introdução

Faker Storage é um pacote PHP de alto desempenho projetado para gerar e armazenar grandes volumes de arquivos de dados falsos de forma eficiente. Desenvolvido com a concorrência em mente, ele aproveita Swoole ou PCNTL para gerar milhares de arquivos em paralelo, tornando-o ideal para testes de carga, ambientes de desenvolvimento e benchmarking de sistemas de armazenamento.

O pacote oferece uma API fluente para gerar vários tipos de arquivos, incluindo imagens (PNG, JPG, GIF, BMP, WEBP, AVIF), arquivos de texto, arquivos CSV, dados binários e emails compatíveis com RFC822. Cada gerador produz uma saída determinística quando semeada, garantindo dados de teste reprodutíveis em diferentes ambientes.

Principais Características

Concorrência de Alto Desempenho: Seleção automática entre Swoole (corrotinas) e PCNTL (fork de processos) para geração de arquivos paralela
Múltiplos Geradores de Arquivos: Suporte embutido para imagens, texto, CSV, binário e arquivos de email
Saída Determinística: Geração baseada em semente garante resultados reprodutíveis
Armazenamento Flexível: Funciona com qualquer adaptador do League Flysystem (local, S3 etc.)
Nomeação de Arquivos Personalizável: Geração de nomes baseada em fechamento com controle total
Suporte a Imagens: Múltiplos formatos com dimensões e compressão configuráveis
Geração de Emails: Emails compatíveis com RFC822 com anexos e suporte a MIME

Exemplo

use DefectiveCode\Faker\Faker;
use League\Flysystem\Filesystem;
use DefectiveCode\Faker\Generators\Png;
use League\Flysystem\Local\LocalFilesystemAdapter;
 
// Gerar 1000 imagens PNG com 10 trabalhadores concorrentes
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();
 
// Gerar arquivos 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();
 
// Gerar emails com anexos
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();

Instalação

Instale o pacote via Composer:

composer require defectivecode/faker-storage

Requisitos

PHP >= 8.4
ext-gd (para geração de imagens)
ext-swoole (opcional, para melhor desempenho)
ext-pcntl (fallback para concorrência)

Dependências Opcionais

Para desempenho ideal, instale a extensão Swoole:

pecl install swoole

O pacote usará automaticamente o Swoole se disponível, caindo de volta para o PCNTL caso contrário.

Uso

Fluxo de Trabalho Básico

Todos os geradores seguem o mesmo padrão:

Crie uma instância do Faker com um gerador
Configure o gerador (opcional)
Defina o destino de armazenamento
Configure concorrência e contagem
Gere arquivos

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)          // Configuração específica do gerador
    ->toDisk(new Filesystem(new LocalFilesystemAdapter('/storage')))
    ->basePath('documents')      // Arquivos estarão em /storage/documents/
    ->count(100)                 // Gere 100 arquivos
    ->concurrency(4)             // Use 4 trabalhadores
    ->seed(123)                  // Para saída determinística
    ->generate();

Configuração de Armazenamento

Usando o Flysystem

Faker Storage usa o League Flysystem para abstração de armazenamento:

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

Armazenamento 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();

Opções de Disco

Passe opções adicionais para o adaptador de sistema de arquivos:

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

Configuração de Concorrência

Controle a execução paralela com o método concurrency():

// Use 10 threads/processos de trabalho
Faker::make(Png::class)
    ->concurrency(10)
    ->generate();
 
// Específico para Swoole: Defina tanto threads quanto corrotinas por thread
Faker::make(Png::class)
    ->concurrency(threads: 4, coroutines: 8)  // 4 trabalhadores, 8 corrotinas cada
    ->generate();

Nomeação de Arquivo

Nomeação Padrão

Por padrão, os arquivos são nomeados usando UUID v4:

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

Geradores de Nomes Embutidos

use DefectiveCode\Faker\NameGenerator;
 
// Baseado em UUID (padrão)
NameGenerator::setDefault('uuid'); // Gera: e7f0a8d3-5c2b-4f9e-8a1d-3b4c5d6e7f8a.png
 
// Numeração sequencial
NameGenerator::setDefault('sequence'); // Gera: 1.png, 2.png, 3.png, ...

Nomeação Personalizada

Forneça um fechamento para personalizar os nomes dos arquivos:

use DefectiveCode\Faker\NameGenerator;
 
// Fechamento personalizado
Faker::make(Png::class)
    ->nameGenerator(function (int $seed, int $completedFiles, $generator) {
        return "custom-{$completedFiles}-{$seed}.png";
    })
    ->generate();
 
// Nomeação baseada em data
Faker::make(Png::class)
    ->nameGenerator(function (int $seed, int $completedFiles, $generator) {
        return date('Y/m/d') . "/image-{$completedFiles}.png";
    })
    ->generate();

Semear para Reprodutibilidade

Defina uma semente para gerar os mesmos arquivos em execuções:

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

Cada arquivo recebe uma semente determinística única derivada da semente base e do índice do arquivo.

Geradores

Geradores de Imagem

Todos os geradores de imagem suportam configuração de dimensões e qualidade.

PNG

use DefectiveCode\Faker\Generators\Png;
 
Faker::make(Png::class)
    ->width(800, 1920)          // Largura aleatória entre 800-1920px
    ->height(600, 1080)         // Altura aleatória entre 600-1080px
    ->withAlpha(true)           // Habilita o canal alfa/transparente
    ->grid(5)                   // Opcional: Gera padrão simétrico 5x5
    ->toDisk($filesystem)
    ->generate();

JPG

use DefectiveCode\Faker\Generators\Jpg;
 
Faker::make(Jpg::class)
    ->width(800, 1920)          // Largura aleatória entre 800-1920px
    ->height(600, 1080)         // Altura aleatória entre 600-1080px
    ->grid(5)                   // Opcional: Gera padrão simétrico 5x5
    ->toDisk($filesystem)
    ->generate();

GIF

use DefectiveCode\Faker\Generators\Gif;
 
Faker::make(Gif::class)
    ->width(800, 1920)          // Largura aleatória entre 800-1920px
    ->height(600, 1080)         // Altura aleatória entre 600-1080px
    ->withAlpha(true)           // Habilita o canal alfa/transparente
    ->grid(5)                   // Opcional: Gera padrão simétrico 5x5
    ->toDisk($filesystem)
    ->generate();

BMP

use DefectiveCode\Faker\Generators\Bmp;
 
Faker::make(Bmp::class)
    ->width(800, 1920)          // Largura aleatória entre 800-1920px
    ->height(600, 1080)         // Altura aleatória entre 600-1080px
    ->grid(5)                   // Opcional: Gera padrão simétrico 5x5
    ->toDisk($filesystem)
    ->generate();

WEBP

use DefectiveCode\Faker\Generators\Webp;
 
Faker::make(Webp::class)
    ->width(800, 1920)          // Largura aleatória entre 800-1920px
    ->height(600, 1080)         // Altura aleatória entre 600-1080px
    ->withAlpha(true)           // Habilita o canal alfa/transparente
    ->grid(5)                   // Opcional: Gera padrão simétrico 5x5
    ->toDisk($filesystem)
    ->generate();

AVIF

use DefectiveCode\Faker\Generators\Avif;
 
Faker::make(Avif::class)
    ->width(800, 1920)          // Largura aleatória entre 800-1920px
    ->height(600, 1080)         // Altura aleatória entre 600-1080px
    ->withAlpha(true)           // Habilita o canal alfa/transparente
    ->grid(5)                   // Opcional: Gera padrão simétrico 5x5
    ->toDisk($filesystem)
    ->generate();

Imagem Aleatória

Gera um formato de imagem aleatório:

use DefectiveCode\Faker\Generators\RandomImage;
 
Faker::make(RandomImage::class)
    ->width(800, 1920)
    ->height(600, 1080)
    ->withAlpha(false)          // Aleatório de: AVIF, BMP, GIF, JPEG, PNG, WEBP
    ->toDisk($filesystem)
    ->generate();
 
Faker::make(RandomImage::class)
    ->width(800, 1920)
    ->height(600, 1080)
    ->withAlpha(true)           // Aleatório de: AVIF, GIF, PNG, WEBP
    ->toDisk($filesystem)
    ->generate();

Gerador de Texto

Gere arquivos de texto simples com parágrafos:

use DefectiveCode\Faker\Generators\Text;
 
Faker::make(Text::class)
    ->paragraphs(5, 10)         // 5-10 parágrafos por arquivo
    ->sentences(3, 6)           // 3-6 sentenças por parágrafo
    ->toDisk($filesystem)
    ->generate();

Exemplo de Saída:

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.

Gerador CSV

Gere arquivos CSV com dados aleatórios:

use DefectiveCode\Faker\Generators\Csv;
 
Faker::make(Csv::class)
    ->columns(5, 10)            // 5-10 colunas
    ->rows(100, 500)            // 100-500 linhas
    ->delimiter(',')            // Delimitador de coluna
    ->enclosure('"')            // Enclausuramento de campo
    ->escape('\\')              // Caractere de escape
    ->eol("\n")                 // Final de linha
    ->toDisk($filesystem)
    ->generate();

Exemplo de Saída:

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

Gerador Binário

Gere dados binários aleatórios:

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

Gerador de Email

Gere arquivos de email compatíveis com RFC822:

use DefectiveCode\Faker\Generators\Email;
 
Faker::make(Email::class)
    ->paragraphs(3, 5)          // Parágrafos no corpo do email
    ->sentences(2, 4)           // Sentenças por parágrafo
    ->withAttachment(Png::class, 1, 3)  // Adicione 1-3 anexos PNG
    ->toDisk($filesystem)
    ->generate();

Cabeçalhos de Email

Os emails gerados incluem:

Para: Nome e email aleatórios
De: Nome e email aleatórios
Assunto: Sentença aleatória
Data: Timestamp atual
Mensagem-ID: ID determinístico baseado na semente

Email com Anexos

Anexe arquivos usando nomes de classes de geradores ou instâncias:

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 anexos PNG
    ->generate();
 
// Anexar usando a instância do gerador configurado
$pngGenerator = new Png(Png::getDefaultConfig());
$pngGenerator->width(400, 800)->height(300, 600);
 
Faker::make(Email::class)
    ->withAttachment($pngGenerator, 2, 5)
    ->generate();

Exemplo de Saída:

Para: John Doe <john.doe@example.com>
De: Jane Smith <jane.smith@example.com>
Assunto: Reunião importante amanhã
Data: Sex, 03 Jan 2026 10:30:00 +0000
Mensagem-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--

Uso Avançado

Geradores Personalizados

Crie seus próprios geradores implementando a interface 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
    {
        // Sua lógica de geração aqui
        $data = $this->faker->randomElement(['foo', 'bar', 'baz']);
 
        $stream = fopen('php://temp', 'w+');
        fwrite($stream, $data);
 
        return $stream;
    }
}
 
// Use seu gerador personalizado
Faker::make(MyCustomGenerator::class)
    ->toDisk($filesystem)
    ->generate();

Classes de Configuração

Cada gerador usa uma classe de configuração que estende Config:

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

Dicas de Desempenho

Use Swoole: Instale a extensão Swoole para o melhor desempenho
Ajuste a Concorrência: Combine a contagem de threads com os núcleos da CPU para uma produção ideal
Operações em Lote: Gere grandes lotes em vez de múltiplas execuções pequenas
Local de Armazenamento: Use armazenamento rápido (SSD, disco local) para arquivos temporários antes do upload
I/O de Rede: Ao usar o S3, aumente a concorrência para maximizar o uso da largura de banda

Configuração

Métodos de Configuração Global

Estes métodos estão disponíveis em todas as instâncias do Faker:

`make(string $generator): Faker`

Crie uma nova instância do Faker com o gerador especificado:

Faker::make(Png::class)

`toDisk(Filesystem $filesystem): Faker`

Defina o destino de armazenamento (obrigatório):

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

`basePath(string $basePath): Faker`

Defina o caminho base dentro do sistema de arquivos:

Faker::make(Png::class)
    ->basePath('images/uploads')  // Arquivos armazenados em /storage/images/uploads/

`count(int $count): Faker`

Defina o número de arquivos a serem gerados:

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

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

Configure a execução paralela:

// Concorrência básica
Faker::make(Png::class)
    ->concurrency(4)
 
// Específico para Swoole: threads e corrotinas
Faker::make(Png::class)
    ->concurrency(threads: 4, coroutines: 8)

`seed(int $seed): Faker`

Defina a semente para geração determinística:

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

`nameGenerator(Closure $generator): Faker`

Personalize a nomeação de arquivos:

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

`diskOptions(array $diskOptions): Faker`

Passe opções para o adaptador de sistema de arquivos:

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

`generate(): void`

Execute a geração de arquivos:

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

Diretrizes de Suporte

Obrigado por escolher nosso pacote de código aberto! Por favor, reserve um momento para conferir estas diretrizes de suporte. Elas ajudarão você a aproveitar ao máximo nosso projeto.

Suporte Direcionado pela Comunidade

Nosso projeto de código aberto é alimentado por nossa incrível comunidade. Se você tiver dúvidas ou precisar de assistência, StackOverflow e outros recursos online são suas melhores opções.

Erros e Priorização de Recursos

A realidade de gerenciar um projeto de código aberto significa que não podemos abordar imediatamente todos os erros ou solicitações de recursos relatados. Priorizamos as questões na seguinte ordem:

1. Erros que Afetam Nossos Produtos Pagos

Erros que impactam nossos produtos pagos serão sempre nossa maior prioridade. Em alguns casos, podemos abordar apenas erros que nos afetam diretamente.

2. Pull Requests da Comunidade

Se você identificou um erro e tem uma solução, por favor, envie um pull request. Após as questões que afetam nossos produtos, damos a próxima maior prioridade a essas correções impulsionadas pela comunidade. Uma vez revisada e aprovada, iremos mesclar sua solução e creditar sua contribuição.

3. Apoio Financeiro

Para questões fora das categorias mencionadas, você pode optar por financiar sua resolução. Cada problema em aberto está vinculado a um formulário de pedido onde você pode contribuir financeiramente. Priorizamos essas questões com base no valor do financiamento fornecido.

Contribuições da Comunidade

O código aberto prospera quando sua comunidade é ativa. Mesmo que você não esteja corrigindo erros, considere contribuir com melhorias de código, atualizações de documentação, tutoriais ou ajudando outros em canais da comunidade. Incentivamos fortemente todos, como comunidade, a ajudar a apoiar o trabalho de código aberto.

Para reiterar, a DefectiveCode priorizará erros com base em como eles impactam nossos produtos pagos, pull requests da comunidade e o apoio financeiro recebido para as questões.

Licença - Licença MIT

A permissão é concedida, sem qualquer custo, a qualquer pessoa que obter uma cópia deste software e dos arquivos de documentação associados (o "Software"), para lidar com o Software sem restrições, incluindo, sem limitação, os direitos de usar, copiar, modificar, fundir, publicar, distribuir, sublicenciar e/ou vender cópias do Software, e para permitir que pessoas a quem o Software é fornecido façam o mesmo, sujeito às seguintes condições:

O aviso de copyright acima e este aviso de permissão devem ser incluídos em todas as cópias ou porções substanciais do Software.

O SOFTWARE É FORNECIDO "COMO ESTÁ", SEM GARANTIA DE QUALQUER TIPO, EXPRESSA OU IMPLÍCITA, INCLUINDO, MAS NÃO SE LIMITANDO A GARANTIAS DE COMERCIALIZAÇÃO, ADEQUAÇÃO A UM FIM ESPECÍFICO E NÃO INFRAÇÃO. EM NENHUM CASO OS AUTORES OU DETENTORES DO DIREITO AUTORAL SERÃO RESPONSÁVEIS POR QUALQUER RECLAMAÇÃO, DANOS OU OUTRA RESPONSABILIDADE, SEJA EM AÇÃO DE CONTRATO, DELITO OU DE OUTRA FORMA, DECORRENTES DE, EM DECORRÊNCIA OU EM CONEXÃO COM O SOFTWARE OU O USO OU OUTRAS NEGOCIAÇÕES NO SOFTWARE.

🔗Introdução

🔗Principais Características

🔗Exemplo

🔗Instalação

🔗Requisitos

🔗Dependências Opcionais

🔗Uso

🔗Fluxo de Trabalho Básico

🔗Configuração de Armazenamento

Usando o Flysystem

Armazenamento AWS S3

Opções de Disco

🔗Configuração de Concorrência

🔗Nomeação de Arquivo

Nomeação Padrão

Geradores de Nomes Embutidos

Nomeação Personalizada

🔗Semear para Reprodutibilidade

🔗Geradores

🔗Geradores de Imagem

PNG

JPG

GIF

BMP

WEBP

AVIF

Imagem Aleatória

🔗Gerador de Texto

🔗Gerador CSV

🔗Gerador Binário

🔗Gerador de Email

Cabeçalhos de Email

Email com Anexos

🔗Uso Avançado

🔗Geradores Personalizados

🔗Classes de Configuração

🔗Dicas de Desempenho

🔗Configuração

🔗Métodos de Configuração Global

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

🔗Diretrizes de Suporte

🔗Suporte Direcionado pela Comunidade

🔗Erros e Priorização de Recursos

1. Erros que Afetam Nossos Produtos Pagos

2. Pull Requests da Comunidade

3. Apoio Financeiro

Contribuições da Comunidade

🔗Licença - Licença MIT

Introdução

Principais Características

Exemplo

Instalação

Requisitos

Dependências Opcionais

Uso

Fluxo de Trabalho Básico

Configuração de Armazenamento

Configuração de Concorrência

Nomeação de Arquivo

Semear para Reprodutibilidade

Geradores

Geradores de Imagem

Gerador de Texto

Gerador CSV

Gerador Binário

Gerador de Email

Uso Avançado

Geradores Personalizados

Classes de Configuração

Dicas de Desempenho

Configuração

Métodos de Configuração Global

`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`

Diretrizes de Suporte

Suporte Direcionado pela Comunidade

Erros e Priorização de Recursos

Licença - Licença MIT