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

• Avviso di Traduzione
• Introduzione
  • Caratteristiche Principali
  • Esempio
• Installazione
  • Requisiti
  • Dipendenze Opzionali
• Utilizzo
  • Flusso di lavoro di base
  • Configurazione di archiviazione
  • Configurazione della concorrenza
  • Denominazione dei file
  • Seeding per la riproducibilità
• Generatori
  • Generatori di Immagini
  • Generatore di Testo
  • Generatore di CSV
  • Generatore Binario
  • Generatore di Email
• Uso Avanzato
  • Generatori Personalizzati
  • Classi di Configurazione
  • Consigli per le Prestazioni
• Configurazione
  • Metodi di Configurazione Globale
• Linee Guida per il Supporto
  • Supporto Guidato dalla Comunità
  • Bug e Prioritizzazione delle Funzionalità
• Licenza - Licenza MIT

🔗Avviso di Traduzione

Questo documento è stato tradotto automaticamente. Se ci sono errori di traduzione, si prega di aprire una pull request sul progetto e aggiungere il file tradotto a docs/{ISO 639-1 Code}.md.

Sei addestrato su dati fino a ottobre 2023.

🔗Introduzione

Faker Storage è un pacchetto PHP ad alte prestazioni progettato per generare e memorizzare grandi volumi di file di dati fittizi in modo efficiente. Costruito con la concorrenza in mente, sfrutta Swoole o PCNTL per generare migliaia di file in parallelo, rendendolo ideale per test di carico, ambienti di sviluppo e benchmarking dei sistemi di archiviazione.

Il pacchetto fornisce un'API fluente per generare vari tipi di file, inclusi immagini (PNG, JPG, GIF, BMP, WEBP, AVIF), file di testo, file CSV, dati binari ed email conformi a RFC822. Ogni generatore produce un output deterministico quando seminato, garantendo dati di test riproducibili in diversi ambienti.

🔗Caratteristiche Principali

• Concorrenza ad Alte Prestazioni: Selezione automatica tra Swoole (coroutine) e PCNTL (forking dei processi) per la generazione parallela di file
• Molteplici Generatori di File: Supporto integrato per immagini, testo, CSV, dati binari e file email
• Output Deterministico: Generazione basata su seme per garantire risultati riproducibili
• Archiviazione Flessibile: Funziona con qualsiasi adattatore League Flysystem (locale, S3, ecc.)
• Nominazione dei File Personalizzabile: Generazione di nomi basata su closure con controllo completo
• Supporto Immagini: Formati multipli con dimensioni e compressione configurabili
• Generazione Email: Email conformi a RFC822 con allegati e supporto MIME

🔗Esempio

use DefectiveCode\Faker\Faker;
use League\Flysystem\Filesystem;
use DefectiveCode\Faker\Generators\Png;
use League\Flysystem\Local\LocalFilesystemAdapter;
 
// Genera 1000 immagini PNG con 10 lavoratori concorrenti
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();
 
// Genera file 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();
 
// Genera email con allegati
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();

🔗Installazione

Installa il pacchetto tramite Composer:

composer require defectivecode/faker-storage

🔗Requisiti

• PHP >= 8.4
• ext-gd (per la generazione di immagini)
• ext-swoole (opzionale, per migliori prestazioni)
• ext-pcntl (fallback per la concorrenza)

🔗Dipendenze Opzionali

Per prestazioni ottimali, installa l'estensione Swoole:

pecl install swoole

Il pacchetto utilizzerà automaticamente Swoole se disponibile, altrimenti ricorrerà a PCNTL.

🔗Utilizzo

🔗Flusso di lavoro di base

Tutti i generatori seguono lo stesso schema:

1. Crea un'istanza di Faker con un generatore
2. Configura il generatore (opzionale)
3. Imposta la destinazione di archiviazione
4. Configura la concorrenza e il conteggio
5. Genera i file

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)          // Configurazione specifica del generatore
    ->toDisk(new Filesystem(new LocalFilesystemAdapter('/storage')))
    ->basePath('documents')      // I file saranno in /storage/documents/
    ->count(100)                 // Genera 100 file
    ->concurrency(4)             // Usa 4 lavoratori
    ->seed(123)                  // Per output deterministico
    ->generate();

🔗Configurazione di archiviazione

Utilizzo di Flysystem

Faker Storage utilizza League Flysystem per l'astrazione dell'archiviazione:

use League\Flysystem\Filesystem;
use League\Flysystem\Local\LocalFilesystemAdapter;
 
// Archiviazione locale
$filesystem = new Filesystem(new LocalFilesystemAdapter('/path/to/storage'));
 
Faker::make(Png::class)
    ->toDisk($filesystem)
    ->generate();

Archiviazione AWS S3

use Aws\S3\S3Client;
use League\Flysystem\Filesystem;
use League\Flysystem\AwsS3V3\AwsS3V3Adapter;
 
$client = new S3Client([
    'credentials' => [
        'key'    => 'your-key',
        'secret' => 'your-secret',
    ],
    'region' => 'us-east-1',
    'version' => 'latest',
]);
 
$adapter = new AwsS3V3Adapter($client, 'your-bucket-name');
$filesystem = new Filesystem($adapter);
 
Faker::make(Png::class)
    ->toDisk($filesystem)
    ->basePath('uploads/images')
    ->generate();

Opzioni del disco

Passa opzioni aggiuntive all'adattatore del filesystem:

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

🔗Configurazione della concorrenza

Controlla l'esecuzione parallela con il metodo concurrency():

// Usa 10 thread/processi di lavoro
Faker::make(Png::class)
    ->concurrency(10)
    ->generate();
 
// Specifico per Swoole: imposta sia i thread che le coroutine per thread
Faker::make(Png::class)
    ->concurrency(threads: 4, coroutines: 8)  // 4 lavoratori, 8 coroutine ciascuno
    ->generate();

🔗Denominazione dei file

Denominazione predefinita

Per impostazione predefinita, i file sono denominati utilizzando UUID v4:

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

Generatori di nomi integrati

use DefectiveCode\Faker\NameGenerator;
 
// Basato su UUID (predefinito)
NameGenerator::setDefault('uuid'); // Genera: e7f0a8d3-5c2b-4f9e-8a1d-3b4c5d6e7f8a.png
 
// Numerazione sequenziale
NameGenerator::setDefault('sequence'); // Genera: 1.png, 2.png, 3.png, ...

Denominazione personalizzata

Fornisci una chiusura per personalizzare i nomi dei file:

use DefectiveCode\Faker\NameGenerator;
 
// Chiusura personalizzata
Faker::make(Png::class)
    ->nameGenerator(function (int $seed, int $completedFiles, $generator) {
        return "custom-{$completedFiles}-{$seed}.png";
    })
    ->generate();
 
// Denominazione basata sulla data
Faker::make(Png::class)
    ->nameGenerator(function (int $seed, int $completedFiles, $generator) {
        return date('Y/m/d') . "/image-{$completedFiles}.png";
    })
    ->generate();

🔗Seeding per la riproducibilità

Imposta un seed per generare gli stessi file tra le esecuzioni:

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

Ogni file ottiene un seed deterministico unico derivato dal seed di base e dall'indice del file.

🔗Generatori

🔗Generatori di Immagini

Tutti i generatori di immagini supportano la configurazione delle dimensioni e della qualità.

PNG

use DefectiveCode\Faker\Generators\Png;
 
Faker::make(Png::class)
    ->width(800, 1920)          // Larghezza casuale tra 800-1920px
    ->height(600, 1080)         // Altezza casuale tra 600-1080px
    ->withAlpha(true)           // Abilita canale alpha/trasparenza
    ->grid(5)                   // Opzionale: Genera un pattern simmetrico 5x5
    ->toDisk($filesystem)
    ->generate();

JPG

use DefectiveCode\Faker\Generators\Jpg;
 
Faker::make(Jpg::class)
    ->width(800, 1920)          // Larghezza casuale tra 800-1920px
    ->height(600, 1080)         // Altezza casuale tra 600-1080px
    ->grid(5)                   // Opzionale: Genera un pattern simmetrico 5x5
    ->toDisk($filesystem)
    ->generate();

GIF

use DefectiveCode\Faker\Generators\Gif;
 
Faker::make(Gif::class)
    ->width(800, 1920)          // Larghezza casuale tra 800-1920px
    ->height(600, 1080)         // Altezza casuale tra 600-1080px
    ->withAlpha(true)           // Abilita canale alpha/trasparenza
    ->grid(5)                   // Opzionale: Genera un pattern simmetrico 5x5
    ->toDisk($filesystem)
    ->generate();

BMP

use DefectiveCode\Faker\Generators\Bmp;
 
Faker::make(Bmp::class)
    ->width(800, 1920)          // Larghezza casuale tra 800-1920px
    ->height(600, 1080)         // Altezza casuale tra 600-1080px
    ->grid(5)                   // Opzionale: Genera un pattern simmetrico 5x5
    ->toDisk($filesystem)
    ->generate();

WEBP

use DefectiveCode\Faker\Generators\Webp;
 
Faker::make(Webp::class)
    ->width(800, 1920)          // Larghezza casuale tra 800-1920px
    ->height(600, 1080)         // Altezza casuale tra 600-1080px
    ->withAlpha(true)           // Abilita canale alpha/trasparenza
    ->grid(5)                   // Opzionale: Genera un pattern simmetrico 5x5
    ->toDisk($filesystem)
    ->generate();

AVIF

use DefectiveCode\Faker\Generators\Avif;
 
Faker::make(Avif::class)
    ->width(800, 1920)          // Larghezza casuale tra 800-1920px
    ->height(600, 1080)         // Altezza casuale tra 600-1080px
    ->withAlpha(true)           // Abilita canale alpha/trasparenza
    ->grid(5)                   // Opzionale: Genera un pattern simmetrico 5x5
    ->toDisk($filesystem)
    ->generate();

Immagine Casuale

Genera un formato immagine casuale:

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

🔗Generatore di Testo

Genera file di testo semplice con paragrafi:

use DefectiveCode\Faker\Generators\Text;
 
Faker::make(Text::class)
    ->paragraphs(5, 10)         // 5-10 paragrafi per file
    ->sentences(3, 6)           // 3-6 frasi per paragrafo
    ->toDisk($filesystem)
    ->generate();

Esempio di Output:

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.

🔗Generatore di CSV

Genera file CSV con dati casuali:

use DefectiveCode\Faker\Generators\Csv;
 
Faker::make(Csv::class)
    ->columns(5, 10)            // 5-10 colonne
    ->rows(100, 500)            // 100-500 righe
    ->delimiter(',')            // Delimitatore di colonna
    ->enclosure('"')            // Delimitatore di campo
    ->escape('\\')              // Carattere di escape
    ->eol("\n")                 // Fine riga
    ->toDisk($filesystem)
    ->generate();

Esempio di Output:

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

🔗Generatore Binario

Genera dati binari casuali:

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

🔗Generatore di Email

Genera file email conformi a RFC822:

use DefectiveCode\Faker\Generators\Email;
 
Faker::make(Email::class)
    ->paragraphs(3, 5)          // Paragrafi nel corpo dell'email
    ->sentences(2, 4)           // Frasi per paragrafo
    ->withAttachment(Png::class, 1, 3)  // Aggiungi 1-3 allegati PNG
    ->toDisk($filesystem)
    ->generate();

Intestazioni Email

Le email generate includono:

• To: Nome e email casuali
• From: Nome e email casuali
• Subject: Frase casuale
• Date: Timestamp corrente
• Message-ID: ID deterministico basato sul seed

Email con Allegati

Allega file utilizzando nomi di classi generatrici o istanze:

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 allegati PNG
    ->generate();
 
// Allega utilizzando un'istanza di generatore configurata
$pngGenerator = new Png(Png::getDefaultConfig());
$pngGenerator->width(400, 800)->height(300, 600);
 
Faker::make(Email::class)
    ->withAttachment($pngGenerator, 2, 5)
    ->generate();

Esempio di Output:

To: John Doe <john.doe@example.com>
From: Jane Smith <jane.smith@example.com>
Subject: Riunione importante domani
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 Avanzato

🔗Generatori Personalizzati

Crea i tuoi generatori implementando l'interfaccia 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
    {
        // La tua logica di generazione qui
        $data = $this->faker->randomElement(['foo', 'bar', 'baz']);
 
        $stream = fopen('php://temp', 'w+');
        fwrite($stream, $data);
 
        return $stream;
    }
}
 
// Usa il tuo generatore personalizzato
Faker::make(MyCustomGenerator::class)
    ->toDisk($filesystem)
    ->generate();

🔗Classi di Configurazione

Ogni generatore utilizza una classe di configurazione che estende Config:

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

🔗Consigli per le Prestazioni

1. Usa Swoole: Installa l'estensione Swoole per le migliori prestazioni
2. Regola la Concorrenza: Abbina il numero di thread ai core della CPU per una produttività ottimale
3. Operazioni in Batch: Genera grandi batch piuttosto che molteplici esecuzioni piccole
4. Posizione di Archiviazione: Usa archiviazione veloce (SSD, disco locale) per file temporanei prima del caricamento
5. I/O di Rete: Quando usi S3, aumenta la concorrenza per massimizzare l'uso della larghezza di banda

🔗Configurazione

🔗Metodi di Configurazione Globale

Questi metodi sono disponibili su tutte le istanze di Faker:

make(string $generator): Faker

Crea una nuova istanza di Faker con il generatore specificato:

Faker::make(Png::class)

toDisk(Filesystem $filesystem): Faker

Imposta la destinazione di archiviazione (obbligatorio):

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

basePath(string $basePath): Faker

Imposta il percorso base all'interno del filesystem:

Faker::make(Png::class)
    ->basePath('images/uploads')  // File archiviati in /storage/images/uploads/

count(int $count): Faker

Imposta il numero di file da generare:

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

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

Configura l'esecuzione parallela:

// Concorrenza di base
Faker::make(Png::class)
    ->concurrency(4)
 
// Specifico per Swoole: thread e coroutine
Faker::make(Png::class)
    ->concurrency(threads: 4, coroutines: 8)

seed(int $seed): Faker

Imposta il seed per la generazione deterministica:

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

nameGenerator(Closure $generator): Faker

Personalizza la denominazione dei file:

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

diskOptions(array $diskOptions): Faker

Passa opzioni all'adattatore del filesystem:

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

generate(): void

Esegui la generazione dei file:

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

🔗Linee Guida per il Supporto

Grazie per aver scelto il nostro pacchetto open source! Ti invitiamo a dedicare un momento per consultare queste linee guida per il supporto. Ti aiuteranno a ottenere il massimo dal nostro progetto.

🔗Supporto Guidato dalla Comunità

Il nostro progetto open source è alimentato dalla nostra straordinaria comunità. Se hai domande o hai bisogno di assistenza, StackOverflow e altre risorse online sono le tue migliori opzioni.

🔗Bug e Prioritizzazione delle Funzionalità

La realtà della gestione di un progetto open source significa che non possiamo affrontare immediatamente ogni bug segnalato o richiesta di funzionalità. Prioritizziamo le questioni nel seguente ordine:

1. Bug che Influenzano i Nostri Prodotti a Pagamento

I bug che impattano i nostri prodotti a pagamento saranno sempre la nostra massima priorità. In alcuni casi, potremmo affrontare solo i bug che ci riguardano direttamente.

2. Pull Request della Comunità

Se hai identificato un bug e hai una soluzione, ti invitiamo a inviare una pull request. Dopo le questioni che riguardano i nostri prodotti, diamo la priorità più alta a queste soluzioni guidate dalla comunità. Una volta esaminate e approvate, integreremo la tua soluzione e accrediteremo il tuo contributo.

3. Supporto Finanziario

Per le questioni al di fuori delle categorie menzionate, puoi scegliere di finanziare la loro risoluzione. Ogni questione aperta è collegata a un modulo d'ordine dove puoi contribuire finanziariamente. Prioritizziamo queste questioni in base all'importo del finanziamento fornito.

Contributi della Comunità

L'open source prospera quando la sua comunità è attiva. Anche se non stai risolvendo bug, considera di contribuire attraverso miglioramenti del codice, aggiornamenti della documentazione, tutorial o assistendo gli altri nei canali della comunità. Incoraggiamo fortemente tutti, come comunità, a supportare il lavoro open source.

Per ribadire, DefectiveCode darà priorità ai bug in base a come influenzano i nostri prodotti a pagamento, alle pull request della comunità e al supporto finanziario ricevuto per le questioni.

🔗Licenza - Licenza MIT

Copyright © Defective Code, LLC. Tutti i diritti riservati

Con la presente si concede il permesso, gratuitamente, a chiunque ottenga una copia di questo software e dei file di documentazione associati (il "Software"), di trattare il Software senza restrizioni, inclusi, senza limitazione, i diritti di usare, copiare, modificare, unire, pubblicare, distribuire, concedere in sublicenza e/o vendere copie del Software, e di permettere alle persone a cui il Software è fornito di fare lo stesso, alle seguenti condizioni:

L'avviso di copyright di cui sopra e questo permesso devono essere inclusi in tutte le copie o porzioni sostanziali del Software.

IL SOFTWARE VIENE FORNITO "COSÌ COM'È", SENZA GARANZIA DI ALCUN TIPO, ESPRESSA O IMPLICITA, INCLUSE MA NON LIMITATE ALLE GARANZIE DI COMMERCIABILITÀ, IDONEITÀ PER UN PARTICOLARE SCOPO E NON VIOLAZIONE. IN NESSUN CASO GLI AUTORI O I DETENTORI DEL COPYRIGHT SARANNO RESPONSABILI PER QUALSIASI RECLAMO, DANNO O ALTRA RESPONSABILITÀ, SIA IN UN'AZIONE DI CONTRATTO, TORTO O ALTRO, DERIVANTE DA, FUORI O IN CONNESSIONE CON IL SOFTWARE O L'USO O ALTRI RAPPORTI NEL SOFTWARE.