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.

Table of Contents

• 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:

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

1. Fork the repository and create a feature branch
2. Write tests for new functionality
3. Follow PSR-12 coding standards
4. 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.