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.

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

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

Features

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

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')
    ->baseBinary();

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

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

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)
    ->baseBinary();
    
echo $handler->formattedSize(); // 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->formattedSize(); // Output: "1.23 MiB"

// Switch to Decimal (1000-based)
echo $handler->baseDecimal()->formattedSize(); // 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')
    ->baseBinary();

echo $handler->formattedSize(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

• baseBinary(): self
  Switches unit calculation to binary (1024-based).

• baseDecimal(): self
  Switches unit calculation to decimal (1000-based).

Output Methods

• sizeInBytes(): int
  Returns the file size in bytes.

• formattedSize(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!

License

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