README

A fluent PHP library for working with file sizes. Easily create, convert, format, and perform arithmetic operations on file sizes with support for both binary (1024-based) and decimal (1000-based) units.

Features

• Fluent, chainable API
• Binary (IEC) and Decimal (SI) unit support
• Arithmetic operations (add, subtract, multiply, divide)
• Human-readable formatting
• Comparison methods
• Lazy evaluation for flexible format switching
• Configurable precision and formatting options

Laravel?

See the Laravel File Size port of this library which contains a Laravel facade and more.

Requirements

• PHP 8.3 or higher

Installation

Install via Composer:

composer require martincamen/php-file-size

Basic Usage

use MartinCamen\PhpFileSize\FileSize; // Create from various units $size = (new FileSize())->megabytes(1.5); // Convert to other units $size->toKilobytes(); // 1536.0 (binary: 1.5 * 1024) $size->toBytes(); // 1572864.0 // Format for display $size->forHumans(); // "1.50 Mebibytes" $size->formatShort(); // "1.50 MiB"

Creating File Sizes

You can create file sizes from any unit:

$size = (new FileSize())->bytes(1024); $size = (new FileSize())->kilobytes(512); $size = (new FileSize())->megabytes(2.5); $size = (new FileSize())->gigabytes(1); $size = (new FileSize())->terabytes(0.5); $size = (new FileSize())->petabytes(1); // Singular forms for single units $size = (new FileSize())->kilobyte(); // 1 KB $size = (new FileSize())->megabyte(); // 1 MB

Binary vs Decimal Units

The library supports both binary (IEC) and decimal (SI) standards:

Binary is the default. To use decimal:

use MartinCamen\PhpFileSize\Enums\ByteBase; // Using fluent methods $size = (new FileSize())->inDecimalFormat()->megabytes(2); $size->toKilobytes(); // 2000.0 // Using constructor options $size = (new FileSize())->megabytes(2, ['byte_base' => ByteBase::Decimal]); $size->toKilobytes(); // 2000.0 // Switch formats in a chain (lazy evaluation) $size = (new FileSize()) ->megabytes(2) ->inDecimalFormat() ->toKilobytes(); // 2000.0

Lazy Evaluation

The library uses lazy evaluation, meaning calculations are deferred until you call a terminal method (like toKilobytes() or forHumans()). This allows you to set the format at any point in the chain:

// The last format set is used for ALL operations $result = (new FileSize()) ->inDecimalFormat() // Initial format ->megabytes(2) // Stored, not computed ->subKilobytes(100) // Stored, not computed ->inBinaryFormat() // Switch to binary ->toKilobytes(); // NOW everything is computed using binary // Force evaluation at a specific point $evaluated = (new FileSize()) ->inDecimalFormat() ->megabytes(2) ->evaluate(); // Returns new FileSize with computed bytes

Arithmetic Operations

Perform arithmetic with any unit:

$size = (new FileSize())->megabytes(10); // Addition $size->addBytes(512); $size->addKilobytes(100); $size->addMegabytes(5); $size->add(2, Unit::GigaByte); // Subtraction $size->subBytes(256); $size->subKilobytes(50); $size->subMegabytes(2); $size->sub(1, Unit::GigaByte); // Multiplication and Division $size->multiply(2); $size->divide(4); // Absolute value $size->abs(); // Chain operations $result = (new FileSize()) ->gigabytes(1) ->addMegabytes(512) ->subKilobytes(1024) ->multiply(2) ->toMegabytes();

Conversions

Convert to any unit:

$size = (new FileSize())->gigabytes(2.5); $size->toBytes(); // Raw bytes $size->toKilobytes(); // 2621440.0 $size->toMegabytes(); // 2560.0 $size->toGigabytes(); // 2.5 $size->toTerabytes(); // 0.0 $size->toPetabytes(); // 0.0 // With custom precision $size->toMegabytes(4); // 2560.0000 // Magic property access $size->bytes; // 2684354560 $size->kilobytes; // 2621440.0 $size->megabytes; // 2560.0

Formatting

Format sizes for human-readable output:

$size = (new FileSize())->megabytes(1536); // Long format (default) $size->forHumans(); // "1.50 Gibibytes" $size->format(); // "1.50 Gibibytes" // Short format $size->formatShort(); // "1.50 GiB" $size->forHumans(true); // "1.50 GiB" // Decimal labels with binary calculation $size->inBinaryFormat()->withDecimalLabel()->forHumans(); // "1.50 Gigabytes" // Custom precision $size->precision(4)->forHumans(); // "1.5000 Gibibytes"

Formatting Options

use MartinCamen\PhpFileSize\Enums\ConfigurationOption; $size = (new FileSize())->megabytes(1234.5678, [ ConfigurationOption::Precision->value => 3, ConfigurationOption::DecimalSeparator->value => ',', ConfigurationOption::ThousandsSeparator->value => ' ', ConfigurationOption::SpaceBetweenValueAndUnit->value => false, ]); $size->forHumans(); // "1,205GiB" (with binary base)

Comparisons

Compare file sizes:

use MartinCamen\PhpFileSize\Enums\Unit; $size = (new FileSize())->megabytes(100); // Equality $size->equals(100, Unit::MegaByte); // true $size->notEquals(50, Unit::MegaByte); // true // Ordering $size->greaterThan(50, Unit::MegaByte); // true $size->greaterThanOrEqual(100, Unit::MegaByte); // true $size->lessThan(200, Unit::MegaByte); // true $size->lessThanOrEqual(100, Unit::MegaByte); // true // Range $size->between(50, 150, Unit::MegaByte); // true // State checks $size->isZero(); // false $size->isPositive(); // true $size->isNegative(); // false // Min/Max with another FileSize $other = (new FileSize())->megabytes(200); $size->min($other); // Returns the 100MB FileSize $size->max($other); // Returns the 200MB FileSize

Configuration Options

Setting Options

use MartinCamen\PhpFileSize\Enums\ByteBase; use MartinCamen\PhpFileSize\Enums\ConfigurationOption; // Via constructor $size = (new FileSize())->megabytes(100, [ ConfigurationOption::ByteBase->value => ByteBase::Decimal, ConfigurationOption::Precision->value => 4, ]); // Via fluent methods $size = (new FileSize()) ->inDecimalFormat() ->precision(4) ->megabytes(100);

Immutability

All operations return new instances, preserving the original:

$original = (new FileSize())->megabytes(100); $modified = $original->addMegabytes(50); $original->toMegabytes(); // 100.0 $modified->toMegabytes(); // 150.0

Error Handling

use MartinCamen\PhpFileSize\Exceptions\InvalidValueException; use MartinCamen\PhpFileSize\Exceptions\NegativeValueException; // Division by zero try { $size->divide(0); } catch (InvalidValueException $e) { // "Cannot divide by zero." } // Invalid values (INF, NaN) try { (new FileSize())->bytes(INF); } catch (InvalidValueException $e) { // "Value must be a finite number." } // Negative input (when not allowed) try { (new FileSize())->megabytes(-5); } catch (NegativeValueException $e) { // "Negative values are not allowed." } // Allow negative values $size = (new FileSize())->megabytes(-5, [ ConfigurationOption::ValidationAllowNegativeInput->value => true, ]);

License

The MIT License (MIT). Please see License File for more information.