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

• 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 Arquivos
  • Sementes para Reproduzibilidade
• Geradores
  • Geradores de Imagem
  • Gerador de Texto
  • Gerador CSV
  • Gerador Binário
  • Gerador de Emails
• Uso Avançado
  • Geradores Personalizados
  • Classes de Configuração
  • Dicas de Desempenho
• 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. Construído com concorrência em mente, ele utiliza 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 fornece 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 semeado, garantindo dados de teste reproduzíveis em diferentes ambientes.

🔗Principais Características

• Concorrência de Alto Desempenho: Seleção automática entre Swoole (corrotinas) e PCNTL (forking de processos) para geração paralela de arquivos.
• 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 reproduzíveis.
• Armazenamento Flexível: Funciona com qualquer adaptador League Flysystem (local, S3, etc.).
• Nomeação de Arquivos Personalizável: Geração de nomes baseada em closures com total controle.
• 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;
 
// Gera 1000 imagens PNG com 10 trabalhadores concorrentes
Faker::make(Png::class)
    ->width(800, 1920)
    ->height(600, 1080)
    ->toDisk(new Filesystem(new LocalFilesystemAdapter('/caminho/para/armazenamento')))
    ->basePath('imagens')
    ->count(1000)
    ->concurrency(10)
    ->seed(42)
    ->generate();
 
// Gera arquivos CSV
use DefectiveCode\Faker\Generators\Csv;
 
Faker::make(Csv::class)
    ->columns(5, 10)
    ->rows(100, 500)
    ->delimiter(',')
    ->toDisk(new Filesystem(new LocalFilesystemAdapter('/caminho/para/armazenamento')))
    ->count(50)
    ->generate();
 
// Gera 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('/caminho/para/armazenamento')))
    ->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, voltando para PCNTL caso contrário.

🔗Uso

🔗Fluxo de Trabalho Básico

Todos os geradores seguem o mesmo padrão:

1. Crie uma instância Faker com um gerador.
2. Configure o gerador (opcional).
3. Defina o destino de armazenamento.
4. Configure a concorrência e a contagem.
5. Gere os 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('/armazenamento')))
    ->basePath('documentos')     // Arquivos estarão em /armazenamento/documentos/
    ->count(100)                 // Gere 100 arquivos
    ->concurrency(4)             // Use 4 trabalhadores
    ->seed(123)                  // Para saída determinística
    ->generate();

🔗Configuração de Armazenamento

Usando Flysystem

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

use League\Flysystem\Filesystem;
use League\Flysystem\Local\LocalFilesystemAdapter;
 
// Armazenamento local
$filesystem = new Filesystem(new LocalFilesystemAdapter('/caminho/para/armazenamento'));
 
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'    => 'sua-chave',
        'secret' => 'seu-segredo',
    ],
    'region' => 'us-east-1',
    'version' => 'latest',
]);
 
$adapter = new AwsS3V3Adapter($client, 'seu-nome-do-bucket');
$filesystem = new Filesystem($adapter);
 
Faker::make(Png::class)
    ->toDisk($filesystem)
    ->basePath('uploads/imagens')
    ->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 Arquivos

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 Nome 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 uma closure para personalizar os nomes dos arquivos:

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

🔗Sementes para Reproduzibilidade

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ão 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)           // Habilitar canal alpha/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)           // Habilitar canal alpha/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)           // Habilitar canal alpha/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)           // Habilitar canal alpha/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 entre: AVIF, BMP, GIF, JPEG, PNG, WEBP
    ->toDisk($filesystem)
    ->generate();
 
Faker::make(RandomImage::class)
    ->width(800, 1920)
    ->height(600, 1080)
    ->withAlpha(true)           // Aleatório entre: 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 frases 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('"')            // Anexo 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 Iorque","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 Emails

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)           // Frases 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: Frase aleatória
• Data: Carimbo de tempo atual
• Message-ID: ID determinístico baseado na semente

Email com Anexos

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

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 de gerador configurada
$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
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--

🔗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

1. Use Swoole: Instale a extensão Swoole para o melhor desempenho.
2. Ajuste a Concorrência: Ajuste a contagem de threads para corresponder aos núcleos da CPU para um rendimento ideal.
3. Operações em Lote: Gere grandes lotes em vez de várias pequenas execuções.
4. Localização de Armazenamento: Use armazenamento rápido (SSD, disco local) para arquivos temporários antes do upload.
5. I/O de Rede: Ao usar S3, aumente a concorrência para maximizar o uso de largura de banda.

🔗Configuração

🔗Métodos de Configuração Global

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

make(string $generator): Faker

Cria uma nova instância Faker com o gerador especificado:

Faker::make(Png::class)

toDisk(Filesystem $filesystem): Faker

Define o destino de armazenamento (obrigatório):

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

basePath(string $basePath): Faker

Define o caminho base dentro do sistema de arquivos:

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

count(int $count): Faker

Define o número de arquivos a serem gerados:

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

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

Configura 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

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

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

nameGenerator(Closure $generator): Faker

Personaliza 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

Executa 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

Copyright © Defective Code, LLC. Todos os direitos reservados

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.