m1roff/faker-file-provider

Faker provider for generating various file types (PDF, PNG, JPEG, TXT, DOCX) for testing purposes

v1.0.0 2025-06-29 11:59 UTC

Requires

• php: ^8.1
• ext-gd: *
• ext-zip: *
• fakerphp/faker: ^1.20

Requires (Dev)

• illuminate/http: ^10.0|^11.0
• pcov/clobber: ^2.0
• phpunit/phpunit: ^10.0
• symfony/http-foundation: ^6.0|^7.0

Suggests

• ext-pcov: Required for code coverage generation
• ext-xdebug: Alternative for code coverage generation
• illuminate/http: Required for Laravel UploadedFile support
• symfony/http-foundation: Required for Symfony UploadedFile support

MIT

• Miroff

• faker
• testing
• pdf
• provider
• images
• docx
• files

README

A Faker provider for generating various file types for testing purposes.

Features

• Generate PDF files with customizable content and dimensions
• Generate PNG images with custom size, colors, and text
• Generate JPEG images with quality control
• Generate text files with custom content
• Generate DOCX documents with simple text content
• Support for Symfony UploadedFile objects
• Support for Laravel UploadedFile objects
• Automatic temporary file cleanup
• Manual file cleanup utilities

Installation

composer require m1roff/faker-file-provider

Requirements

• PHP 8.1+
• ext-gd (for image generation)
• ext-zip (for DOCX generation)
• fakerphp/faker

Optional Dependencies

• symfony/http-foundation (for Symfony UploadedFile support)
• illuminate/http (for Laravel UploadedFile support)

Usage

Basic Setup

use Faker\Factory;
use FakerFileProvider\FileProvider;

$faker = Factory::create();
$faker->addProvider(new FileProvider($faker));

Generate Files

// Generate basic files
$pdfPath = $faker->generateFile('pdf');
$pngPath = $faker->generateFile('png');
$jpegPath = $faker->generateFile('jpeg');
$txtPath = $faker->generateFile('txt');
$docxPath = $faker->generateFile('docx');

Generate Files with Options

// PDF with custom content and size
$pdfPath = $faker->generateFile('pdf', [
    'width' => 612,    // A4 width in points
    'height' => 792,   // A4 height in points
    'content' => 'Custom PDF content here'
]);

// PNG image with custom properties
$pngPath = $faker->generateFile('png', [
    'width' => 800,
    'height' => 600,
    'backgroundColor' => [255, 255, 255], // white background
    'textColor' => [0, 0, 0],             // black text
    'text' => 'Sample Image Text'
]);

// JPEG with quality setting
$jpegPath = $faker->generateFile('jpeg', [
    'width' => 1024,
    'height' => 768,
    'quality' => 85,
    'backgroundColor' => [200, 200, 200],
    'textColor' => [50, 50, 50],
    'text' => 'JPEG Sample'
]);

// Text file with custom content
$txtPath = $faker->generateFile('txt', [
    'content' => 'This is custom text content',
    'length' => 500  // used if content is not provided
]);

// DOCX with custom content
$docxPath = $faker->generateFile('docx', [
    'content' => 'This will be the document content'
]);

// Custom root directory for all file types
$filePath = $faker->generateFile('pdf', [
    'rootDir' => '/path/to/custom/temp/dir'
]);

Temporary Files with Auto-cleanup

// Generate temporary file that auto-deletes when object is destroyed
$tempFile = $faker->generateTemporaryFile('pdf', [
    'content' => 'Temporary PDF content'
]);

$filePath = $tempFile->getPath();
$fileSize = $tempFile->getSize();
$mimeType = $tempFile->getMimeType();
$basename = $tempFile->getBasename();

// File will be automatically deleted when $tempFile goes out of scope
// or you can disable auto-cleanup:
$tempFile->disableAutoCleanup();

// Manual cleanup
$tempFile->cleanup();

Framework Integration

Symfony UploadedFile

// Generate Symfony UploadedFile for form testing
$uploadedFile = $faker->generateUploadedFile('png', [
    'width' => 400,
    'height' => 300
]);

// Use in Symfony form tests
$client->request('POST', '/upload', [], ['file' => $uploadedFile]);

Laravel UploadedFile

// Generate Laravel UploadedFile for testing
$uploadedFile = $faker->generateLaravelUploadedFile('docx', [
    'content' => 'Document for Laravel test'
]);

// Use in Laravel tests
$response = $this->post('/upload', ['document' => $uploadedFile]);

Manual File Cleanup

// Generate files
$pdfPath = $faker->generateFile('pdf');
$imagePath = $faker->generateFile('png');

// Clean up manually when done
$faker->cleanupFile($pdfPath);
$faker->cleanupFile($imagePath);

API Reference

FileProvider Methods

generateFile(string $type, array $options = []): string

Generates a file of the specified type and returns the file path.

Parameters:

• $type - File type: 'pdf', 'png', 'jpeg'/'jpg', 'txt', 'docx'
• $options - Array of options specific to each file type

Returns: Path to the generated file

generateTemporaryFile(string $type, array $options = []): TemporaryFile

Generates a temporary file with automatic cleanup.

Parameters:

• $type - File type
• $options - Array of options

Returns: TemporaryFile object

generateUploadedFile(string $type, array $options = []): UploadedFile

Generates a Symfony UploadedFile object.

Parameters:

• $type - File type
• $options - Array of options

Returns: Symfony UploadedFile object

generateLaravelUploadedFile(string $type, array $options = []): UploadedFile

Generates a Laravel UploadedFile object.

Parameters:

• $type - File type
• $options - Array of options

Returns: Laravel UploadedFile object

cleanupFile(string $filePath): bool

Manually delete a generated file.

Parameters:

• $filePath - Path to the file to delete

Returns: True if successful or file doesn't exist, false otherwise

TemporaryFile Methods

getPath(): string

Returns the full path to the temporary file.

getSize(): int

Returns the file size in bytes.

getMimeType(): string

Returns the MIME type based on file extension.

getBasename(): string

Returns the filename with extension.

cleanup(): bool

Manually delete the temporary file.

disableAutoCleanup(): self

Disable automatic cleanup on object destruction.

enableAutoCleanup(): self

Enable automatic cleanup on object destruction.

toUploadedFile(): UploadedFile

Convert to Symfony UploadedFile object.

toLaravelUploadedFile(): UploadedFile

Convert to Laravel UploadedFile object.

File Type Options

PDF Options

• width (int): Page width in points (default: 595)
• height (int): Page height in points (default: 842)
• content (string): Text content for the PDF
• rootDir (string): Custom temporary directory

PNG/JPEG Options

• width (int): Image width in pixels (default: 640)
• height (int): Image height in pixels (default: 480)
• backgroundColor (array): RGB array for background color (default: [255,255,255])
• textColor (array): RGB array for text color (default: [0,0,0])
• text (string): Text to display on image
• quality (int): JPEG quality 0-100 (JPEG only, default: 90)
• rootDir (string): Custom temporary directory

TXT Options

• content (string): File content
• length (int): Content length if content not provided (default: 1000)
• rootDir (string): Custom temporary directory

DOCX Options

• content (string): Document text content
• rootDir (string): Custom temporary directory

Error Handling

The provider throws exceptions for various error conditions:

• \InvalidArgumentException: Unsupported file type
• \RuntimeException: File creation/writing failures, missing extensions

try {
    $filePath = $faker->generateFile('pdf');
} catch (\InvalidArgumentException $e) {
    // Handle unsupported file type
} catch (\RuntimeException $e) {
    // Handle file generation errors
}

License

MIT