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

• Aviso de Tradução
• 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
  • Semeadura para Reprodutibilidade
• Geradores
  • Geradores de Imagem
  • Gerador de Texto
  • Gerador de 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
• Diretrizes de Suporte
  • Suporte Orientado pela Comunidade
  • Bugs e Priorização de Funcionalidades
• Licença - Licença MIT

🔗Aviso de Tradução

Este documento foi traduzido automaticamente. Se houver erros de tradução, por favor abra um pull request no projeto e adicione o arquivo traduzido em docs/{Código ISO 639-1}.md.

Você foi treinado com dados até outubro de 2023.

🔗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 e-mails 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 e-mail
• Saída Determinística: Geração baseada em sementes 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 controle total
• Suporte a Imagens: Múltiplos formatos com dimensões e compressão configuráveis
• Geração de E-mails: E-mails 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 e-mails 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 (alternativa 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, caso contrário, usará o PCNTL.

🔗Uso

🔗Fluxo de Trabalho Básico

Todos os geradores seguem o mesmo padrão:

1. Crie uma instância do 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('/storage')))
    ->basePath('documents')      // Os 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 Flysystem

O Armazenamento do Faker 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'    => 'sua-chave',
        'secret' => 'seu-segredo',
    ],
    'region' => 'us-east-1',
    'version' => 'latest',
]);
 
$adapter = new AwsS3V3Adapter($client, 'nome-do-seu-bucket');
$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 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 Integrados

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

use DefectiveCode\Faker\NameGenerator;
 
// Closure 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();

🔗Semeadura para Reprodutibilidade

Defina uma semente para gerar os mesmos arquivos em diferentes 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 alfa/transparência
    ->grid(5)                   // Opcional: Gerar 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: Gerar 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 alfa/transparência
    ->grid(5)                   // Opcional: Gerar 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: Gerar 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 alfa/transparência
    ->grid(5)                   // Opcional: Gerar 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 alfa/transparência
    ->grid(5)                   // Opcional: Gerar 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

Gera 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 de CSV

Gera 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('"')            // Delimitador de campo
    ->escape('\\')              // Caractere de escape
    ->eol("\n")                 // Fim de linha
    ->toDisk($filesystem)
    ->generate();

Exemplo de Saída:

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

🔗Gerador Binário

Gera 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

Gera 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)  // Adicionar 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: Timestamp atual
• Message-ID: ID determinístico baseado em seed

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 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 obter o melhor desempenho
2. Ajuste a Concorrência: Combine a contagem de threads com os núcleos da CPU para um rendimento ideal
3. Operações em Lote: Gere grandes lotes em vez de várias execuções pequenas
4. Local de Armazenamento: Use armazenamento rápido (SSD, disco local) para arquivos temporários antes de fazer o upload
5. I/O de Rede: Ao usar S3, aumente a concorrência para maximizar o uso da 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

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 coroutines
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 do 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 tirar o máximo proveito do nosso projeto.

🔗Suporte Orientado pela Comunidade

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

🔗Bugs e Priorização de Funcionalidades

A realidade de gerenciar um projeto de código aberto significa que não podemos resolver imediatamente todos os bugs relatados ou pedidos de funcionalidades. Priorizamos as questões na seguinte ordem:

1. Bugs que Afetam Nossos Produtos Pagos

Bugs que impactam nossos produtos pagos serão sempre nossa maior prioridade. Em alguns casos, podemos resolver apenas bugs que nos afetam diretamente.

2. Pull Requests da Comunidade

Se você identificou um bug 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, integraremos sua solução e creditaremos sua contribuição.

3. Suporte Financeiro

Para questões fora das categorias mencionadas, você pode optar por financiar sua resolução. Cada questão aberta está vinculada 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 está ativa. Mesmo que você não esteja corrigindo bugs, considere contribuir através de melhorias de código, atualizações de documentação, tutoriais ou ajudando outros em canais comunitários. Incentivamos fortemente todos, como comunidade, a ajudar a apoiar o trabalho de código aberto.

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

🔗Licença - Licença MIT

Copyright © Defective Code, LLC. Todos os direitos reservados

A permissão é concedida, gratuitamente, a qualquer pessoa que obtenha 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, mesclar, publicar, distribuir, sublicenciar e/ou vender cópias do Software, e permitir que as pessoas a quem o Software é fornecido façam o mesmo, sujeitas à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 partes substanciais do Software.

O SOFTWARE É FORNECIDO "COMO ESTÁ", SEM GARANTIA DE QUALQUER TIPO, EXPRESSA OU IMPLÍCITA, INCLUINDO, MAS NÃO SE LIMITANDO ÀS GARANTIAS DE COMERCIALIZAÇÃO, ADEQUAÇÃO A UM DETERMINADO FIM E NÃO VIOLAÇÃO. EM NENHUM CASO OS AUTORES OU DETENTORES DOS DIREITOS AUTORAIS SERÃO RESPONSÁVEIS POR QUALQUER REIVINDICAÇÃO, DANOS OU OUTRA RESPONSABILIDADE, SEJA EM UMA AÇÃO DE CONTRATO, DELITO OU DE OUTRA FORMA, DECORRENTE DE, FORA OU EM CONEXÃO COM O SOFTWARE OU O USO OU OUTRAS NEGOCIAÇÕES NO SOFTWARE.