README

PHP FileSizeHandler

The FileSizeHandler class is a utility designed to fetch and format file sizes across various file storage systems. It offers cross-platform compatibility with support for both SI (decimal) and IEC (binary) standards, making it HDD-agnostic and highly flexible.

Local Files
Remote Files (HTTP/HTTPS) (via Remote File Extension)
FTP (via FTP Extension)
Amazon S3 (via S3 Extension)
Google Cloud Storage (via Google Cloud Extension)
Custom Sources (via user-implemented interfaces)

This package addresses the discrepancies in file size measurement (binary vs decimal units) and provides flexible APIs for developers.

Features

Supports Local, Remote, and FTP Files:
- Easily calculate file sizes from multiple sources.
Binary and Decimal Calculations:
- Switch between binary (KiB, MiB, etc.) and decimal (KB, MB, etc.) bases with simple methods.
Fluent Interface:
- Intuitive method chaining for base selection and size formatting.
Extensibility:
- Ready for integration with cloud storage systems like S3 and Google Cloud.
i18n Support:
- Format file size with custom localized units.
- Dynamically provide translations for units.
Chaining and Echo Support:
- Supports method chaining for cleaner code.
- Directly echo the handler instance to get the formatted size.
Custom Source Support:
- Implement FileSourceInterface and register your custom source.

Why Was This Class Created?
Useful Links
Requirements
Installation
Usage
- Local File
- Extending the Library
Binary vs Decimal Units
- Switching Units
- Dynamic Locale and Unit Customization
API Reference
Extensions
- Available Extensions
Contributing
License

Why Was This Class Created?

When working with file sizes, differences in measurement units across systems can cause confusion:

Cross-OS Consistency: File size interpretations vary between operating systems (Windows, Linux, macOS) and hardware (HDD/SSD manufacturers often use decimal, while OS file systems may use binary).
Unified Interface: Simplifies handling file size retrieval from diverse sources.
Extensibility: Easily extend functionality by integrating additional storage systems via a simple, well-defined interface.

Useful Links

Wikipedia: Binary Prefixes
- Comprehensive explanation of binary (KiB, MiB) vs. decimal (KB, MB) prefixes.
NIST: Prefixes for Binary Multiples
- Official standards for binary-based units.
IBM: Units of Measurement for Storage Data
- Insights into storage measurement across platforms.
Google: Byte Units
- Guidelines for using decimal and binary units consistently.
Metric View: What are binary prefixes?
- Provides an overview of binary prefixes and their usage

Requirements

PHP: Version 8.0 or higher
PHP Extension - ext-intl: Required

Installation

The recommended way use Composer to install the package:

composer require nassiry/filesize-handler

Usage

Local File

By default, the library supports fetching file sizes for local files.

use Nassiry\FileSizeUtility\FileSizeHandler;

$handler = FileSizeHandler::create()
    ->local('/path/to/file')
    ->binary();

// Get the formatted size
echo $handler->format(); // Example output: "1.23 MiB"

// Or use directly with echo
echo FileSizeHandler::create()
    ->local('/path/to/file')
    ->binary()
    ->format();

Extending the Library

To add support for a new file source, implement the FileSourceInterface:

use Nassiry\FileSizeUtility\Sources\FileSourceInterface;

class CustomCloudSource implements FileSourceInterface
{
    public function __construct(private string $apiKey, private string $filePath) {}

    public function getSizeInBytes(): int
    {
        // Implement API logic to get file size
        return 123456789;
    }
}

$customSource = new CustomCloudSource('api-key', '/path/to/file');

// Once implemented, register your custom source using:
$handler = FileSizeHandler::create()
    ->from($customSource)
    ->binary();
    
echo $handler->format(); // Example output: "1.23 MiB"

For more information on extending the library, check the official extensions available.

Binary vs Decimal Units

Switching Units

$handler = FileSizeHandler::create()
    ->local('/path/to/file.txt');

// Default: Binary (1024-based)
echo $handler->format(); // Output: "1.23 MiB"

// Switch to Decimal (1000-based)
echo $handler->decimal()->format(); // Output: "1.30 MB"

Dynamic Locale and Unit Customization

$customUnits = [
    'binary_units' => ['o', 'Kio', 'Mio', 'Gio', 'Tio', 'Pio', 'Eio', 'Zio', 'Yio'],
    'decimal_units' => ['o', 'Ko', 'Mo', 'Go', 'To', 'Po', 'Eo', 'Zo', 'Yo'],
];

$handler = FileSizeHandler::create('fr_FR', $customUnits)
    ->local('/path/to/file')
    ->binary();

echo $handler->format(1); // Example output: "1,2 Mio"

Key Points:

Two-letter country codes are based on the ISO 3166-1 alpha-2 standard and are used in locale naming conventions.

Examples of Supported Locales: en_US, fr_FR, de_DE.
The Default: units and locale are set to en_US

API Reference

`FileSizeHandler::create(string $locale = 'en_US', array $units = [])`

Initializes a new FileSizeHandler instance.

Source Methods

local(string $filePath): self
Creates an instance for a local file.
from(FileSourceInterface $source): self
Allows integration of a custom file source by implementing the FileSourceInterface.

Configuration Methods

binary(): self
Switches unit calculation to binary (1024-based).
decimal(): self
Switches unit calculation to decimal (1000-based).

Output Methods

bytes(): int
Returns the file size in bytes.
format(int $precision = 2): string
Returns the formatted file size with the specified precision.

Extensions

FileSizeHandler is extensible via optional extensions for advanced integrations. These extensions add support for remote and cloud-based file sources. Install the extensions via Composer.

Available Extensions:

Extension	Description	Installation Command	Documentation
FTP	Support for FTP file size retrieval.	`composer require nassiry/filesize-handler-ftp-extension`	See Full Documentation
Amazon S3	Fetch file sizes from Amazon S3 buckets.	`composer require nassiry/filesize-handler-s3-extension`	See Full Documentation
Google Cloud	Retrieve file sizes from Google Cloud Storage.	`composer require nassiry/filesize-handler-googlecloud-extension`	See Full Documentation
Remote	Support for files accessible via HTTP/HTTPS.	`composer require nassiry/filesize-handler-remote-extension`	See Full Documentation

Contributing

Feel free to submit issues or pull requests to improve the package. Contributions are welcome!

Changelog

See CHANGELOG for release details.

⚠️ Deprecated Methods

As of version 1.1.0, the following methods are deprecated and will be removed in version 2.0.0:

Deprecated	Use Instead
`baseBinary()`	`binary()`
`baseDecimal()`	`decimal()`
`formattedSize()`	`format()`
`sizeInBytes()`	`bytes()`

License

This package is open-source software licensed under the MIT license.

nassiry / filesize-handler

Maintainers

Details