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

• Introducción
  • Características Clave
  • Ejemplo
• Instalación
  • Requisitos
  • Dependencias Opcionales
• Uso
  • Flujo de Trabajo Básico
  • Configuración de Almacenamiento
  • Configuración de Concurrencia
  • Nomenclatura de Archivos
  • Siembra para Reproducibilidad
• Generadores
  • Generadores de Imágenes
  • Generador de Texto
  • Generador CSV
  • Generador Binario
  • Generador de Correos Electrónicos
• Uso Avanzado
  • Generadores Personalizados
  • Clases de Configuración
  • Consejos de Rendimiento
• Configuración
  • Métodos de Configuración Global
• Directrices de Soporte
  • Soporte Impulsado por la Comunidad
  • Errores y Priorización de Funciones
• Licencia - Licencia MIT

🔗Introducción

Faker Storage es un paquete PHP de alto rendimiento diseñado para generar y almacenar grandes volúmenes de archivos de datos falsos de manera eficiente. Construido con la concurrencia en mente, aprovecha Swoole o PCNTL para generar miles de archivos en paralelo, lo que lo hace ideal para pruebas de carga, entornos de desarrollo y evaluación de sistemas de almacenamiento.

El paquete proporciona una API fluida para generar varios tipos de archivos, incluyendo imágenes (PNG, JPG, GIF, BMP, WEBP, AVIF), archivos de texto, archivos CSV, datos binarios y correos electrónicos conforme a la RFC822. Cada generador produce una salida determinista cuando se siembra, asegurando datos de prueba reproducibles a través de diferentes entornos.

🔗Características Clave

• Concurrencia de Alto Rendimiento: Selección automática entre Swoole (corrutinas) y PCNTL (forking de procesos) para la generación de archivos en paralelo
• Múltiples Generadores de Archivos: Soporte integrado para archivos de imágenes, texto, CSV, binarios y correos electrónicos
• Salida Determinista: La generación basada en semillas asegura resultados reproducibles
• Almacenamiento Flexible: Funciona con cualquier adaptador de League Flysystem (local, S3, etc.)
• Nomenclatura de Archivos Personalizable: Generación de nombres basada en cierres con control total
• Soporte de Imágenes: Múltiples formatos con dimensiones y compresión configurables
• Generación de Correos Electrónicos: Correos electrónicos conformes a la RFC822 con adjuntos y soporte MIME

🔗Ejemplo

use DefectiveCode\Faker\Faker;
use League\Flysystem\Filesystem;
use DefectiveCode\Faker\Generators\Png;
use League\Flysystem\Local\LocalFilesystemAdapter;
 
// Generar 1000 imágenes PNG con 10 trabajadores concurrentes
Faker::make(Png::class)
    ->width(800, 1920)
    ->height(600, 1080)
    ->toDisk(new Filesystem(new LocalFilesystemAdapter('/ruta/a/almacenamiento')))
    ->basePath('imagenes')
    ->count(1000)
    ->concurrency(10)
    ->seed(42)
    ->generate();
 
// Generar archivos CSV
use DefectiveCode\Faker\Generators\Csv;
 
Faker::make(Csv::class)
    ->columns(5, 10)
    ->rows(100, 500)
    ->delimiter(',')
    ->toDisk(new Filesystem(new LocalFilesystemAdapter('/ruta/a/almacenamiento')))
    ->count(50)
    ->generate();
 
// Generar correos electrónicos con adjuntos
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('/ruta/a/almacenamiento')))
    ->count(100)
    ->generate();

🔗Instalación

Instala el paquete a través de Composer:

composer require defectivecode/faker-storage

🔗Requisitos

• PHP >= 8.4
• ext-gd (para generación de imágenes)
• ext-swoole (opcional, para mejor rendimiento)
• ext-pcntl (respaldo para concurrencia)

🔗Dependencias Opcionales

Para un rendimiento óptimo, instala la extensión Swoole:

pecl install swoole

El paquete usará automáticamente Swoole si está disponible, cayendo en PCNTL en caso contrario.

🔗Uso

🔗Flujo de Trabajo Básico

Todos los generadores siguen el mismo patrón:

1. Crea una instancia de Faker con un generador
2. Configura el generador (opcional)
3. Establece el destino de almacenamiento
4. Configura la concurrencia y el número de archivos
5. Genera archivos

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)          // Configuración específica del generador
    ->toDisk(new Filesystem(new LocalFilesystemAdapter('/almacenamiento')))
    ->basePath('documentos')      // Los archivos estarán en /almacenamiento/documentos/
    ->count(100)                 // Generar 100 archivos
    ->concurrency(4)             // Usar 4 trabajadores
    ->seed(123)                  // Para salida determinista
    ->generate();

🔗Configuración de Almacenamiento

Usando Flysystem

Faker Storage usa League Flysystem para la abstracción de almacenamiento:

use League\Flysystem\Filesystem;
use League\Flysystem\Local\LocalFilesystemAdapter;
 
// Almacenamiento local
$filesystem = new Filesystem(new LocalFilesystemAdapter('/ruta/a/almacenamiento'));
 
Faker::make(Png::class)
    ->toDisk($filesystem)
    ->generate();

Almacenamiento AWS S3

use Aws\S3\S3Client;
use League\Flysystem\Filesystem;
use League\Flysystem\AwsS3V3\AwsS3V3Adapter;
 
$client = new S3Client([
    'credentials' => [
        'key'    => 'tu-clave',
        'secret' => 'tu-secreto',
    ],
    'region' => 'us-east-1',
    'version' => 'última',
]);
 
$adapter = new AwsS3V3Adapter($client, 'tu-nombre-de-bucket');
$filesystem = new Filesystem($adapter);
 
Faker::make(Png::class)
    ->toDisk($filesystem)
    ->basePath('subidas/imagenes')
    ->generate();

Opciones de Disco

Pasa opciones adicionales al adaptador de sistema de archivos:

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

🔗Configuración de Concurrencia

Controla la ejecución paralela con el método concurrency():

// Utiliza 10 hilos/procesos trabajadores
Faker::make(Png::class)
    ->concurrency(10)
    ->generate();
 
// Específico de Swoole: Establece tanto hilos como corrutinas por hilo
Faker::make(Png::class)
    ->concurrency(threads: 4, coroutines: 8)  // 4 trabajadores, 8 corrutinas cada uno
    ->generate();

🔗Nomenclatura de Archivos

Nomenclatura por Defecto

Por defecto, los archivos se nombran usando UUID v4:

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

Generadores de Nombres Integrados

use DefectiveCode\Faker\NameGenerator;
 
// Basado en UUID (por defecto)
NameGenerator::setDefault('uuid'); // Genera: e7f0a8d3-5c2b-4f9e-8a1d-3b4c5d6e7f8a.png
 
// Numeración secuencial
NameGenerator::setDefault('sequence'); // Genera: 1.png, 2.png, 3.png, ...

Nomenclatura Personalizada

Proporciona un cierre para personalizar los nombres de los archivos:

use DefectiveCode\Faker\NameGenerator;
 
// Cierre personalizado
Faker::make(Png::class)
    ->nameGenerator(function (int $seed, int $completedFiles, $generator) {
        return "personalizado-{$completedFiles}-{$seed}.png";
    })
    ->generate();
 
// Nomenclatura basada en la fecha
Faker::make(Png::class)
    ->nameGenerator(function (int $seed, int $completedFiles, $generator) {
        return date('Y/m/d') . "/imagen-{$completedFiles}.png";
    })
    ->generate();

🔗Siembra para Reproducibilidad

Establece una semilla para generar los mismos archivos en diferentes ejecuciones:

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

Cada archivo recibe una semilla determinista única derivada de la semilla base y el índice del archivo.

🔗Generadores

🔗Generadores de Imágenes

Todos los generadores de imágenes soportan configuración de dimensiones y calidad.

PNG

use DefectiveCode\Faker\Generators\Png;
 
Faker::make(Png::class)
    ->width(800, 1920)          // Ancho aleatorio entre 800-1920px
    ->height(600, 1080)         // Alto aleatorio entre 600-1080px
    ->withAlpha(true)           // Habilitar canal alfa/transparencia
    ->grid(5)                   // Opcional: Generar patrón simétrico 5x5
    ->toDisk($filesystem)
    ->generate();

JPG

use DefectiveCode\Faker\Generators\Jpg;
 
Faker::make(Jpg::class)
    ->width(800, 1920)          // Ancho aleatorio entre 800-1920px
    ->height(600, 1080)         // Alto aleatorio entre 600-1080px
    ->grid(5)                   // Opcional: Generar patrón simétrico 5x5
    ->toDisk($filesystem)
    ->generate();

GIF

use DefectiveCode\Faker\Generators\Gif;
 
Faker::make(Gif::class)
    ->width(800, 1920)          // Ancho aleatorio entre 800-1920px
    ->height(600, 1080)         // Alto aleatorio entre 600-1080px
    ->withAlpha(true)           // Habilitar canal alfa/transparencia
    ->grid(5)                   // Opcional: Generar patrón simétrico 5x5
    ->toDisk($filesystem)
    ->generate();

BMP

use DefectiveCode\Faker\Generators\Bmp;
 
Faker::make(Bmp::class)
    ->width(800, 1920)          // Ancho aleatorio entre 800-1920px
    ->height(600, 1080)         // Alto aleatorio entre 600-1080px
    ->grid(5)                   // Opcional: Generar patrón simétrico 5x5
    ->toDisk($filesystem)
    ->generate();

WEBP

use DefectiveCode\Faker\Generators\Webp;
 
Faker::make(Webp::class)
    ->width(800, 1920)          // Ancho aleatorio entre 800-1920px
    ->height(600, 1080)         // Alto aleatorio entre 600-1080px
    ->withAlpha(true)           // Habilitar canal alfa/transparencia
    ->grid(5)                   // Opcional: Generar patrón simétrico 5x5
    ->toDisk($filesystem)
    ->generate();

AVIF

use DefectiveCode\Faker\Generators\Avif;
 
Faker::make(Avif::class)
    ->width(800, 1920)          // Ancho aleatorio entre 800-1920px
    ->height(600, 1080)         // Alto aleatorio entre 600-1080px
    ->withAlpha(true)           // Habilitar canal alfa/transparencia
    ->grid(5)                   // Opcional: Generar patrón simétrico 5x5
    ->toDisk($filesystem)
    ->generate();

Imagen Aleatoria

Genera un formato de imagen aleatorio:

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

🔗Generador de Texto

Genera archivos de texto plano con párrafos:

use DefectiveCode\Faker\Generators\Text;
 
Faker::make(Text::class)
    ->paragraphs(5, 10)         // 5-10 párrafos por archivo
    ->sentences(3, 6)           // 3-6 oraciones por párrafo
    ->toDisk($filesystem)
    ->generate();

Ejemplo de Salida:

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.

🔗Generador CSV

Genera archivos CSV con datos aleatorios:

use DefectiveCode\Faker\Generators\Csv;
 
Faker::make(Csv::class)
    ->columns(5, 10)            // 5-10 columnas
    ->rows(100, 500)            // 100-500 filas
    ->delimiter(',')            // Delimitador de columnas
    ->enclosure('"')            // Enclosure de campo
    ->escape('\\')              // Carácter de escape
    ->eol("\n")                 // Fin de línea
    ->toDisk($filesystem)
    ->generate();

Ejemplo de Salida:

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

🔗Generador Binario

Genera datos binarios aleatorios:

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

🔗Generador de Correos Electrónicos

Genera archivos de correo electrónico conformes a la RFC822:

use DefectiveCode\Faker\Generators\Email;
 
Faker::make(Email::class)
    ->paragraphs(3, 5)          // Párrafos en el cuerpo del correo
    ->sentences(2, 4)           // Oraciones por párrafo
    ->withAttachment(Png::class, 1, 3)  // Añadir 1-3 adjuntos PNG
    ->toDisk($filesystem)
    ->generate();

Encabezados del Correo Electrónico

Los correos generados incluyen:

• To: Nombre y correo aleatorios
• From: Nombre y correo aleatorios
• Subject: Oración aleatoria
• Date: Marca de tiempo actual
• Message-ID: ID determinista basado en la semilla

Correo Electrónico con Adjuntos

Adjunta archivos usando nombres de generador de clase o instancias:

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 adjuntos PNG
    ->generate();
 
// Adjunta usando instancia de generador configurada
$pngGenerator = new Png(Png::getDefaultConfig());
$pngGenerator->width(400, 800)->height(300, 600);
 
Faker::make(Email::class)
    ->withAttachment($pngGenerator, 2, 5)
    ->generate();

Ejemplo de Salida:

To: John Doe <john.doe@example.com>
From: Jane Smith <jane.smith@example.com>
Subject: Importante reunión mañana
Date: Vie, 03 Ene 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 Avanzado

🔗Generadores Personalizados

Crea tus propios generadores implementando la interfaz 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
    {
        // Tu lógica de generación aquí
        $data = $this->faker->randomElement(['foo', 'bar', 'baz']);
 
        $stream = fopen('php://temp', 'w+');
        fwrite($stream, $data);
 
        return $stream;
    }
}
 
// Usa tu generador personalizado
Faker::make(MyCustomGenerator::class)
    ->toDisk($filesystem)
    ->generate();

🔗Clases de Configuración

Cada generador utiliza una clase de configuración que extiende Config:

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

🔗Consejos de Rendimiento

1. Usa Swoole: Instala la extensión Swoole para el mejor rendimiento
2. Ajusta la Concurrencia: Alinea la cantidad de hilos con los núcleos de CPU para un rendimiento óptimo
3. Operaciones por Lotes: Genera grandes lotes en lugar de múltiples pequeñas ejecuciones
4. Ubicación de Almacenamiento: Usa almacenamientos rápidos (SSD, disco local) para archivos temporales antes de subir
5. E/S de Red: Cuando uses S3, aumenta la concurrencia para maximizar el uso de ancho de banda

🔗Configuración

🔗Métodos de Configuración Global

Estos métodos están disponibles en todas las instancias de Faker:

make(string $generator): Faker

Crea una nueva instancia de Faker con el generador especificado:

Faker::make(Png::class)

toDisk(Filesystem $filesystem): Faker

Establece el destino de almacenamiento (requerido):

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

basePath(string $basePath): Faker

Establece la ruta base dentro del sistema de archivos:

Faker::make(Png::class)
    ->basePath('imagenes/subidas')  // Archivos almacenados en /almacenamiento/imagenes/subidas/

count(int $count): Faker

Establece el número de archivos a generar:

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

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

Configura la ejecución paralela:

// Concurrencia básica
Faker::make(Png::class)
    ->concurrency(4)
 
// Específico de Swoole: hilos y corrutinas
Faker::make(Png::class)
    ->concurrency(threads: 4, coroutines: 8)

seed(int $seed): Faker

Establece la semilla para la generación determinista:

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

nameGenerator(Closure $generator): Faker

Personaliza la nomenclatura de archivos:

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

diskOptions(array $diskOptions): Faker

Pasa opciones al adaptador del sistema de archivos:

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

generate(): void

Ejecuta la generación de archivos:

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

🔗Directrices de Soporte

¡Gracias por elegir nuestro paquete de código abierto! Tómate un momento para revisar estas directrices de soporte. Te ayudarán a sacar el máximo provecho de nuestro proyecto.

🔗Soporte Impulsado por la Comunidad

Nuestro proyecto de código abierto es impulsado por nuestra increíble comunidad. Si tienes preguntas o necesitas asistencia, StackOverflow y otros recursos en línea son tus mejores opciones.

🔗Errores y Priorización de Funciones

La realidad de gestionar un proyecto de código abierto significa que no podemos abordar cada error reportado o solicitud de función de inmediato. Priorizamos los problemas en el siguiente orden:

1. Errores que Afectan Nuestros Productos de Pago

Los errores que impactan nuestros productos de pago siempre serán nuestra máxima prioridad. En algunos casos, solo abordaremos los errores que nos afectan directamente.

2. Solicitudes de Extracción de la Comunidad

Si has identificado un error y tienes una solución, por favor envía una solicitud de extracción. Después de los problemas que afectan a nuestros productos, damos la siguiente mayor prioridad a estas soluciones impulsadas por la comunidad. Una vez revisada y aprobada, integraremos tu solución y daremos crédito a tu contribución.

3. Apoyo Financiero

Para problemas fuera de las categorías mencionadas, puedes optar por financiar su resolución. Cada problema abierto está vinculado a un formulario de pedido donde puedes contribuir financieramente. Priorizamos estos problemas según la cantidad de financiamiento proporcionada.

Contribuciones de la Comunidad

El código abierto prospera cuando su comunidad está activa. Incluso si no estás solucionando errores, considera contribuir a través de mejoras de código, actualizaciones de documentación, tutoriales o asistiendo a otros en los canales de la comunidad. Animamos encarecidamente a todos, como comunidad, a ayudar a apoyar el trabajo de código abierto.

Para reiterar, DefectiveCode priorizará los errores en función de cómo impactan a nuestros productos de pago, las solicitudes de extracción de la comunidad y el apoyo financiero recibido para los problemas.

🔗Licencia - Licencia MIT

Copyright © Defective Code, LLC. Todos los derechos reservados

Por la presente se otorga permiso, de forma gratuita, a cualquier persona que obtenga una copia de este software y los archivos de documentación asociados (el "Software"), para tratar el Software sin restricciones, incluyendo sin limitación los derechos a usar, copiar, modificar, fusionar, publicar, distribuir, sublicenciar y/o vender copias del Software, y a permitir a las personas a las que se les proporciona el Software hacerlo, sujeto a las siguientes condiciones:

La mención de copyright anterior y esta nota de permiso deberán incluirse en todas las copias o partes sustanciales del Software.

EL SOFTWARE SE PROPORCIONA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O IMPLÍCITA, INCLUYENDO PERO NO LIMITÁNDOSE A LAS GARANTÍAS DE COMERCIALIZABILIDAD, ADECUACIÓN PARA UN PROPÓSITO PARTICULAR Y NO INFRACCIÓN. EN NINGÚN CASO LOS AUTORES O TITULARES DE LOS DERECHOS DE AUTOR SERÁN RESPONSABLES DE NINGUNA RECLAMACIÓN, DAÑO O OTRA RESPONSABILIDAD, YA SEA EN UNA ACCIÓN DE CONTRATO, AGRAVIO O DE OTRA MANERA, QUE SURJA DE, O EN CONEXIÓN CON EL SOFTWARE O EL USO O OTRAS NEGOCIACIONES EN EL SOFTWARE.