README

A PHP library for file operations, providing an object-oriented abstraction layer for reading, writing, uploading, and serving files with streaming support, Base64 encoding/decoding, MIME type detection, and chunked file processing.

Supported PHP Versions
Key Features
Why This Library?
Installation
Quick Start
Core Classes
Using FileInterface
Examples
Testing
Contributing
License
Support
Changelog

Supported PHP Versions

Build Status

Key Features

Object-oriented file read, write, create, remove, copy, and move
Streaming I/O with constant memory usage via FileStream
File upload handling with extension validation, size limits, and callback hooks
Stream processing during uploads with hash verification support
Atomic writes (temp + rename) for crash-safe operations
Base64 encoding/decoding
Byte-range reads for partial file access
MIME type detection for ~600 file extensions
ResponseEmitter interface for framework-agnostic HTTP file serving
FileInterface for dependency injection and mocking

Why This Library?

All-in-one — File I/O, uploads, streaming, and HTTP serving in a single package.
Upload-first design — FileUploader, StreamingUploader, and ResumableUploader handle multipart forms, raw body streams, and chunked uploads with pause/resume — each with extension filtering, size limits, and callback hooks.
Constant-memory streaming — Generators power reads, writes, uploads, and serving. Process gigabyte files without touching memory limits.
Framework-agnostic HTTP serving — The ResponseEmitter interface decouples file serving from any specific HTTP layer. Plug in PSR-7, any framework, or raw PHP.
Testable by design — FileInterface enables dependency injection and mocking. No filesystem required in your unit tests.
Lightweight — Single dependency, no framework coupling.

Installation

composer require webfiori/file

Requirements:

PHP 8.1 or higher
webfiori/jsonx ^4.0

Quick Start

<?php
require_once 'vendor/autoload.php';

use WebFiori\File\File;

$file = new File('/path/to/document.txt');
$file->read();
echo $file->getRawData();

Core Classes

FileInterface — Contract defining core file operations. Use for type-hinting and mocking.
File — Read, write, create, remove, copy, move, and serve files. Supports byte-range reads, Base64 encoding/decoding, chunked processing, and JSON serialization.
FileStream — Streaming file I/O with constant memory usage. Read chunks, lines, ranges, and serve large files.
FileUploader — Handle multipart form file uploads with extension validation, size limits, stream processing, and callback hooks.
StreamingUploader — Receive files from raw HTTP body (php://input) in constant memory. Ideal for single-shot binary uploads.
ResumableUploader — Chunked upload handler with resume-on-failure support. Tracks byte offset on disk for seamless resume after network drops.
UploadedFile — Extends File with upload-specific properties (upload status, replacement status, error message).
ResponseEmitter — Interface for abstracting HTTP output when serving files.
MIME — Static lookup of ~600 file extension to MIME type mappings.

Using FileInterface

Type-hint FileInterface when your code only needs I/O operations. Use the concrete File class when you need encoding, serialization, or HTTP features.

use WebFiori\File\FileInterface;

class DocumentService {
    public function process(FileInterface $file): string {
        $file->read();
        return strtoupper($file->getRawData());
    }
}

Mocking in Tests

use WebFiori\File\FileInterface;

$mockFile = $this->createMock(FileInterface::class);
$mockFile->method('getRawData')->willReturn('test content');
$mockFile->method('getName')->willReturn('test.txt');
$mockFile->method('isExist')->willReturn(true);

$service = new DocumentService();
$result = $service->process($mockFile);

Examples

The examples/ directory contains runnable PHP scripts covering every feature of the library:

Example	Description
Reading and Writing Files	Create, write, read, append, and remove files
File Information	File metadata: name, extension, MIME, size, timestamps, constructor variants
Partial Read	Read specific byte ranges from a file
Appending Data	Build up in-memory content with `append()`
Base64 Encoding	Encode/decode Base64, `writeEncoded()`, `readDecoded()`
Chunked Processing	Split file data into fixed-size chunks
Bytes and Hex	Convert data to byte arrays and hex strings
MIME Detection	Look up MIME types by extension
Error Handling	`FileException` scenarios and how to handle them
JSON Serialization	Convert `File` objects to JSON
Path Utilities	Path normalization, directory creation, file existence checks
File Upload	Configure and process uploads with `FileUploader`
Serving Files	Serve files over HTTP with ResponseEmitter
Streaming I/O	Read chunks, lines, and ranges with `FileStream`
Copy and Move	Copy and move files with streaming
Atomic Write	Crash-safe writes with temp + rename
Streaming Upload	Receive large files from `php://input`
Upload Callbacks	Before/after hooks for validation and logging
Resumable Upload	Chunked upload with pause/resume support
Custom FileInterface	Implement `FileInterface` for DI, mocking, or custom storage
Custom Emitter	Implement `ResponseEmitter` for framework integration

Each example has its own README with detailed explanations. Run any example with:

php examples/read-and-write/read-and-write.php

Testing

# Run all tests
composer test

# Run tests with PHPUnit 10
composer test10

Contributing

Fork the repository and create a feature branch
Write tests for new functionality
Follow PSR-12 coding standards
Submit a pull request

License

MIT — see LICENSE for details.

Support

Found a bug or have a feature request? Open an issue.

Changelog

See CHANGELOG.md for release history.

webfiori / file

Maintainers

Package info

Statistics

Security