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

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.

Table Of Contents

1. Why Was This Class Created?
2. Useful Links
3. Requirements
4. Installation
5. Usage
   • Local File
   • Extending the Library
6. Binary vs Decimal Units
   • Switching Units
   • Dynamic Locale and Unit Customization
7. API Reference
   • Source Methods
   • Configuration Methods
   • Output Methods
8. Extensions
   • Available Extensions
9. Contributing
10. 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

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

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:

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:

License

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