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

• Advertencia de Traducción
• 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
  • Semillas para Reproducibilidad
• Generadores
  • Generadores de Imágenes
  • Generador de Texto
  • Generador de CSV
  • Generador Binario
  • Generador de Email
• 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

🔗Advertencia de Traducción

Este documento ha sido traducido automáticamente. Si hay errores de traducción, por favor abre un pull request en el proyecto y añade el archivo traducido a docs/{Código ISO 639-1}.md.

Estás entrenado con datos hasta octubre de 2023.

🔗Introducción

Faker Storage es un paquete de 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 comparativa 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 siembra, 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 (bifurcación de procesos) para la generación paralela de archivos
• Múltiples Generadores de Archivos: Soporte incorporado para imágenes, texto, CSV, binario y archivos de correo electrónico
• Salida Determinista: Generación basada en semillas que asegura resultados reproducibles
• Almacenamiento Flexible: Funciona con cualquier adaptador de League Flysystem (local, S3, etc.)
• Nombres de Archivos Personalizables: Generación de nombres basada en clausuras 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 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/al/almacenamiento')))
    ->basePath('images')
    ->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/al/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/al/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 (alternativa 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, de lo contrario, recurrirá a PCNTL.

🔗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 concurrencia y cantidad
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('/storage')))
    ->basePath('documents')      // Los archivos estarán en /storage/documents/
    ->count(100)                 // Generar 100 archivos
    ->concurrency(4)             // Usar 4 trabajadores
    ->seed(123)                  // Para salida determinista
    ->generate();

🔗Configuración de Almacenamiento

Usando Flysystem

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

use League\Flysystem\Filesystem;
use League\Flysystem\Local\LocalFilesystemAdapter;
 
// Almacenamiento local
$filesystem = new Filesystem(new LocalFilesystemAdapter('/path/to/storage'));
 
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' => 'latest',
]);
 
$adapter = new AwsS3V3Adapter($client, 'nombre-de-tu-bucket');
$filesystem = new Filesystem($adapter);
 
Faker::make(Png::class)
    ->toDisk($filesystem)
    ->basePath('uploads/images')
    ->generate();

Opciones de Disco

Pasa opciones adicionales al adaptador del sistema de archivos:

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

🔗Configuración de Concurrencia

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

// Usar 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

Proporciona un closure para personalizar los nombres de archivo:

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

🔗Semillas para Reproducibilidad

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

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

Cada archivo obtiene 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)         // Altura aleatoria 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)         // Altura aleatoria 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)         // Altura aleatoria 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)         // Altura aleatoria 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)         // Altura aleatoria 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)         // Altura aleatoria 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 de: AVIF, BMP, GIF, JPEG, PNG, WEBP
    ->toDisk($filesystem)
    ->generate();
 
Faker::make(RandomImage::class)
    ->width(800, 1920)
    ->height(600, 1080)
    ->withAlpha(true)           // Aleatorio de: 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 de 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 columna
    ->enclosure('"')            // Encerramiento 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 Email

Genera archivos de email compatibles con RFC822:

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

Encabezados de Email

Los emails generados incluyen:

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

Email con Adjuntos

Adjuntar archivos usando nombres de clases generadoras 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();
 
// Adjuntar 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: Reunión importante mañana
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

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 obtener el mejor rendimiento
2. Ajusta la Concurrencia: Ajusta el número de hilos a los núcleos de la CPU para un rendimiento óptimo
3. Operaciones por Lotes: Genera grandes lotes en lugar de múltiples ejecuciones pequeñas
4. Ubicación de Almacenamiento: Usa almacenamiento rápido (SSD, disco local) para archivos temporales antes de subirlos
5. I/O de Red: Al usar S3, aumenta la concurrencia para maximizar el uso del ancho de banda

Estás entrenado con datos hasta octubre de 2023.

🔗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('/storage')))

basePath(string $basePath): Faker

Establece la ruta base dentro del sistema de archivos:

Faker::make(Png::class)
    ->basePath('images/uploads')  // Archivos almacenados en /storage/images/uploads/

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 en paralelo:

// 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 generación determinista:

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

nameGenerator(Closure $generator): Faker

Personaliza el nombrado de archivos:

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

diskOptions(array $diskOptions): Faker

Pasa opciones al adaptador del sistema de archivos:

Faker::make(Png::class)
    ->diskOptions([
        'visibility' => 'public',
        '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! Por favor, tómese un momento para revisar estas directrices de soporte. Le ayudarán a sacar el máximo provecho de nuestro proyecto.

🔗Soporte Impulsado por la Comunidad

Nuestro proyecto de código abierto se alimenta de nuestra increíble comunidad. Si tiene preguntas o necesita asistencia, StackOverflow y otros recursos en línea son sus 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 a Nuestros Productos Pagos

Los errores que impactan nuestros productos pagos siempre serán nuestra máxima prioridad. En algunos casos, solo podemos abordar errores que nos afectan directamente.

2. Solicitudes de Extracción de la Comunidad

Si ha identificado un error y tiene una solución, por favor envíe una solicitud de extracción. Después de los problemas que afectan a nuestros productos, damos la siguiente prioridad más alta a estas correcciones impulsadas por la comunidad. Una vez revisada y aprobada, integraremos su solución y acreditaremos su contribución.

3. Soporte Financiero

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

Contribuciones de la Comunidad

El código abierto prospera cuando su comunidad está activa. Incluso si no está corrigiendo errores, considere contribuir a través de mejoras de código, actualizaciones de documentación, tutoriales o ayudando 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 según cómo impacten nuestros productos pagos, las solicitudes de extracción de la comunidad y el apoyo financiero recibido para los problemas.

🔗Licencia - Licencia MIT

Derechos de autor © Defective Code, LLC. Todos los derechos reservados

Por la presente se concede permiso, sin cargo, 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 de usar, copiar, modificar, fusionar, publicar, distribuir, sublicenciar y/o vender copias del Software, y para permitir a las personas a quienes se les proporcione el Software hacerlo, sujeto a las siguientes condiciones:

El aviso de derechos de autor anterior y este aviso de permiso se incluirán 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 LIMITADO A LAS GARANTÍAS DE COMERCIABILIDAD, IDONEIDAD 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 POR NINGUNA RECLAMACIÓN, DAÑOS U OTRA RESPONSABILIDAD, YA SEA EN UNA ACCIÓN DE CONTRATO, AGRAVIO O DE OTRO MODO, QUE SURJA DE, FUERA O EN CONEXIÓN CON EL SOFTWARE O EL USO U OTROS TRATOS EN EL SOFTWARE.