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
  • Semillado 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 Globales
• 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, incluidos imágenes (PNG, JPG, GIF, BMP, WEBP, AVIF), archivos de texto, archivos CSV, datos binarios y correos electrónicos compatibles con RFC822. Cada generador produce una salida determinista cuando se le proporciona una semilla, asegurando datos de prueba reproducibles en todos los entornos.

🔗Características Clave

• Concurrencia de Alto Rendimiento: Selección automática entre Swoole (corutinas) y PCNTL (fork de procesos) para la generación de archivos en paralelo.
• Múltiples Generadores de Archivos: Soporte integrado para imágenes, texto, CSV, binario y archivos de correo electrónico.
• Salida Determinista: La generación basada en semillas garantiza resultados reproducibles.
• Almacenamiento Flexible: Funciona con cualquier adaptador de League Flysystem (local, S3, etc.).
• Nomenclatura de Archivos Personalizable: Generación de nombres basada en closures con control total.
• Soporte para Imágenes: Múltiples formatos con dimensiones y compresión configurables.
• Generación de Correos Electrónicos: Correos electrónicos compatibles con RFC822 con archivos 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 archivos 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

Instale el paquete a través de Composer:

composer require defectivecode/faker-storage

🔗Requisitos

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

🔗Dependencias Opcionales

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

pecl install swoole

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

🔗Uso

🔗Flujo de Trabajo Básico

Todos los generadores siguen el mismo patrón:

1. Crear una instancia de Faker con un generador.
2. Configurar el generador (opcional).
3. Establecer el destino de almacenamiento.
4. Configurar la concurrencia y el conteo.
5. Generar 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 en 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' => 'latest',
]);
 
$adapter = new AwsS3V3Adapter($client, 'tu-nombre-de-bucket');
$filesystem = new Filesystem($adapter);
 
Faker::make(Png::class)
    ->toDisk($filesystem)
    ->basePath('uploads/imagenes')
    ->generate();

Opciones de Disco

Pase opciones adicionales al adaptador de sistema de archivos:

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

🔗Configuración de Concurrencia

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

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

🔗Nomenclatura de Archivos

Nomenclatura Predeterminada

Por defecto, los archivos se nombran usando UUID v4:

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

Generadores de Nombres Incorporados

use DefectiveCode\Faker\NameGenerator;
 
// Basado en UUID (predeterminado)
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

Proporcione un closure para personalizar los nombres de los archivos:

use DefectiveCode\Faker\NameGenerator;
 
// Closure personalizada
Faker::make(Png::class)
    ->nameGenerator(function (int $seed, int $completedFiles, $generator) {
        return "custom-{$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();

🔗Semillado para Reproducibilidad

Establezca una semilla para generar los mismos archivos en distintas ejecuciones:

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

Cada archivo recibe una semilla única determinista 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)         // Altura aleatoria entre 600-1080px
    ->withAlpha(true)           // Habilitar canal alfa/transparente
    ->grid(5)                   // Opcional: Generar patrón simétrico de 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)         // Altura aleatoria entre 600-1080px
    ->grid(5)                   // Opcional: Generar patrón simétrico de 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)         // Altura aleatoria entre 600-1080px
    ->withAlpha(true)           // Habilitar canal alfa/transparente
    ->grid(5)                   // Opcional: Generar patrón simétrico de 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)         // Altura aleatoria entre 600-1080px
    ->grid(5)                   // Opcional: Generar patrón simétrico de 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)         // Altura aleatoria entre 600-1080px
    ->withAlpha(true)           // Habilitar canal alfa/transparente
    ->grid(5)                   // Opcional: Generar patrón simétrico de 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)         // Altura aleatoria entre 600-1080px
    ->withAlpha(true)           // Habilitar canal alfa/transparente
    ->grid(5)                   // Opcional: Generar patrón simétrico de 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('"')            // Envoltura 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 compatibles con 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)  // Agregar 1-3 archivos adjuntos PNG
    ->toDisk($filesystem)
    ->generate();

Encabezados de Correos Electrónicos

Los correos electrónicos 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.

Correos Electrónicos con Archivos Adjuntos

Adjunte archivos usando nombres de clases o instancias de generador:

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 archivos adjuntos PNG
    ->generate();
 
// Adjuntar usando la 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: 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--

🔗Uso Avanzado

🔗Generadores Personalizados

Cree sus 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;
    }
}
 
// Usar 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. Usar Swoole: Instale la extensión Swoole para el mejor rendimiento.
2. Ajustar la Concurrencia: Alinee el conteo de hilos con los núcleos de CPU para un rendimiento óptimo.
3. Operaciones por Lotes: Genere grandes lotes en lugar de múltiples ejecuciones pequeñas.
4. Ubicación de Almacenamiento: Use almacenamiento rápido (SSD, disco local) para archivos temporales antes de subirlos.
5. I/O de Red: Al usar S3, aumente la concurrencia para maximizar el uso del ancho de banda.

🔗Configuración

🔗Métodos de Configuración Globales

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

make(string $generator): Faker

Cree una nueva instancia de Faker con el generador especificado:

Faker::make(Png::class)

toDisk(Filesystem $filesystem): Faker

Establezca el destino de almacenamiento (requerido):

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

basePath(string $basePath): Faker

Establezca la ruta base dentro del sistema de archivos:

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

count(int $count): Faker

Establezca el número de archivos a generar:

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

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

Configure la ejecución paralela:

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

seed(int $seed): Faker

Establezca una semilla para la generación determinista:

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

nameGenerator(Closure $generator): Faker

Personalice la nomenclatura de archivos:

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

diskOptions(array $diskOptions): Faker

Pase opciones al adaptador de sistema de archivos:

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

generate(): void

Ejecute 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.