PHPackages                             martincamen/laravel-file-size - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [File & Storage](/categories/file-storage)
4. /
5. martincamen/laravel-file-size

ActiveLibrary[File & Storage](/categories/file-storage)

martincamen/laravel-file-size
=============================

Eloquent file size calculations and formatting for Laravel

1.0.6(3mo ago)02.9k↓47.6%MITPHPPHP ^8.3CI passing

Since Dec 15Pushed 3mo agoCompare

[ Source](https://github.com/MartinCamen/laravel-file-size)[ Packagist](https://packagist.org/packages/martincamen/laravel-file-size)[ Docs](https://github.com/martincamen/laravel-file-size)[ RSS](/packages/martincamen-laravel-file-size/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (7)Dependencies (12)Versions (10)Used By (0)

Laravel File Size
=================

[](#laravel-file-size)

A fluent, immutable API for converting, comparing, and formatting file sizes in Laravel with support for both binary (1024-based) and decimal (1000-based) byte systems.

Requirements
------------

[](#requirements)

- PHP 8.3+
- Laravel 12.x+

Installation
------------

[](#installation)

```
composer require martincamen/laravel-file-size
```

The package will automatically register its service provider.

### Publish Configuration

[](#publish-configuration)

```
php artisan vendor:publish --tag="file-size-config"
```

Quick Start
-----------

[](#quick-start)

```
use MartinCamen\FileSize\FileSize;
use MartinCamen\FileSize\Enums\ByteBase;

// Create a file size
$size = FileSize::megabytes(5);

// Convert between units
$size->toKilobytes();    // 5120.0 (binary)
$size->toGigabytes();    // 0.00 (rounded to 2 decimals)
$size->toBytes();        // 5242880.0

// Format for display
$size->forHumans();                                // "5.00 Megabytes"
$size->formatShort(labelStyle: ByteBase::Decimal); // "5.00 MB"

// Arithmetic operations
$size->addMegabytes(2)->toMegabytes(); // 7.0
$size->multiply(2)->toMegabytes();    // 10.0

// Comparisons
$size->greaterThan(4, Unit::MegaByte); // true
$size->between(1, 10, Unit::MegaByte); // true
```

Factory Methods
---------------

[](#factory-methods)

Create `FileSize` instances using static factory methods:

```
// Plural forms (specify value)
FileSize::bytes(1024);
FileSize::kilobytes(5);
FileSize::megabytes(100);
FileSize::gigabytes(2.5);
FileSize::terabytes(1);
FileSize::petabytes(0.5);

// Singular forms (default to 1)
FileSize::byte();     // 1 byte
FileSize::kilobyte(); // 1 KB
FileSize::megabyte(); // 1 MB
FileSize::gigabyte(); // 1 GB
FileSize::terabyte(); // 1 TB
FileSize::petabyte(); // 1 PB
```

### Specifying Byte Base

[](#specifying-byte-base)

```
use MartinCamen\FileSize\Enums\ByteBase;

// Binary (1024-based) - default
FileSize::megabytes(1, ByteBase::Binary); // 1 MB = 1,048,576 bytes

// Decimal (1000-based)
FileSize::megabytes(1, ByteBase::Decimal); // 1 MB = 1,000,000 bytes
```

Conversions
-----------

[](#conversions)

Convert to specific units:

```
$size = FileSize::gigabytes(2.5, ByteBase::Binary);

$size->toBytes();     // 2684354560.0
$size->toKilobytes(); // 2621440.0
$size->toMegabytes(); // 2560.0
$size->toGigabytes(); // 2.5
$size->toTerabytes(); // 0.0
$size->toPetabytes(); // 0.0
```

### With Custom Precision

[](#with-custom-precision)

```
$size = FileSize::bytes(1234567, ByteBase::Binary);

$size->toKilobytes(0); // 1206.0
$size->toKilobytes(2); // 1205.63
$size->toKilobytes(4); // 1205.6318
```

### Property Access

[](#property-access)

```
$size = FileSize::megabytes(2);

$size->bytes;     // 2097152.0
$size->kilobytes; // 2048.0
$size->megabytes; // 2.0
```

Arithmetic Operations
---------------------

[](#arithmetic-operations)

All operations return new immutable instances:

```
$size = FileSize::megabytes(10);

// Addition
$size->addBytes(512);
$size->addKilobytes(100);
$size->addMegabytes(5);
$size->addGigabytes(1);
$size->addTerabytes(0.5);
$size->addPetabytes(0.1);

// Subtraction
$size->subBytes(512);
$size->subKilobytes(100);
$size->subMegabytes(5);
$size->subGigabytes(1);
$size->subTerabytes(0.5);
$size->subPetabytes(0.1);

// Multiplication and Division
$size->multiply(2); // 20 MB
$size->divide(4);   // 2.5 MB

// Absolute value
$size->subMegabytes(15)->abs(); // 5 MB
```

### Generic Add/Sub with Unit

[](#generic-addsub-with-unit)

```
use MartinCamen\FileSize\Enums\Unit;

$size->add(100, Unit::KiloByte);
$size->sub(50, Unit::MegaByte);
```

### Method Chaining

[](#method-chaining)

```
$size = FileSize::megabytes(100)
    ->addGigabytes(1)
    ->subMegabytes(50)
    ->multiply(2)
    ->divide(4);
```

Comparisons
-----------

[](#comparisons)

```
use MartinCamen\FileSize\Enums\Unit;

$size = FileSize::megabytes(500);

// Equality
$size->equals(500, Unit::MegaByte);    // true
$size->notEquals(400, Unit::MegaByte); // true

// Greater than
$size->greaterThan(400, Unit::MegaByte);        // true
$size->greaterThanOrEqual(500, Unit::MegaByte); // true

// Less than
$size->lessThan(600, Unit::MegaByte);        // true
$size->lessThanOrEqual(500, Unit::MegaByte); // true

// Range check
$size->between(100, 1000, Unit::MegaByte); // true
```

### Min/Max

[](#minmax)

```
$size1 = FileSize::megabytes(100);
$size2 = FileSize::megabytes(200);

$size1->min($size2); // Returns $size1 (100 MB)
$size1->max($size2); // Returns $size2 (200 MB)
```

### State Checks

[](#state-checks)

```
$size->isZero();     // true if 0 bytes
$size->isPositive(); // true if > 0
$size->isNegative(); // true if < 0
```

Formatting
----------

[](#formatting)

```
$size = FileSize::megabytes(1.5);

// Full labels
$size->forHumans(); // "1.50 Megabytes"
$size->format();    // "1.50 Megabytes"

// Short labels
$size->forHumans(short: true); // "1.50 MB"
$size->formatShort();          // "1.50 MB"

// Custom precision
$size->forHumans(precision: 0); // "2 Megabytes"
$size->forHumans(precision: 4); // "1.5000 Megabytes"

// Labels with specific label formatting
$size->forHumans(labelStyle: ByteBase::Decimal);       // "1.50 Megabytes" (default)
$size->forHumans(labelStyle: ByteBase::Binary);        // "1.50 Mebibytes"
$size->format(labelStyle: ByteBase::Decimal);          // "1.50 Megabytes" (default)
$size->format(labelStyle: ByteBase::Binary);           // "1.50 Mebibytes"
```

### Automatic Unit Selection

[](#automatic-unit-selection)

The formatter automatically selects the most appropriate unit:

```
FileSize::bytes(500)->forHumans();     // "500.00 Bytes"
FileSize::kilobytes(1.5)->forHumans(); // "1.50 Kilobytes"
FileSize::megabytes(2.5)->forHumans(); // "2.50 Megabytes"
FileSize::gigabytes(1.25)->forHumans();// "1.25 Gigabytes"
```

### Decimal vs Binary Labels

[](#decimal-vs-binary-labels)

```
// Binary base (default)
FileSize::megabytes(1, ByteBase::Binary)->forHumans();   // "1.00 Megabytes"
FileSize::megabytes(1, ByteBase::Binary)->formatShort(); // "1.00 MB"
// Binary base with Decimal labels
FileSize::megabytes(1, ByteBase::Binary)->forHumans(labelStyle: ByteBase::Decimal);   // "1.00 Megabytes"
FileSize::megabytes(1, ByteBase::Binary)->formatShort(labelStyle: ByteBase::Decimal); // "1.00 MB"

// Decimal base
FileSize::megabytes(1, ByteBase::Decimal)->forHumans();   // "1.00 Megabytes"
FileSize::megabytes(1, ByteBase::Decimal)->formatShort(); // "1.00 MB"
// Decimal base with Binary labels
FileSize::megabytes(1, ByteBase::Decimal)->forHumans(labelStyle: ByteBase::Binary);   // "1.00 Megabytes"
FileSize::megabytes(1, ByteBase::Decimal)->formatShort(labelStyle: ByteBase::Binary); // "1.00 MB"
```

Fluent Configuration
--------------------

[](#fluent-configuration)

### Precision

[](#precision)

```
$size = FileSize::bytes(1234567)->precision(4);

$size->toKilobytes(); // 1205.6318
$size->forHumans();   // "1.1774 Megabytes"
```

### Byte Base

[](#byte-base)

```
$size = FileSize::megabytes(1)->byteBase(ByteBase::Decimal);

$size->toKilobytes(); // 1000.0
```

Configuration
-------------

[](#configuration)

Publish the configuration file:

```
php artisan vendor:publish --tag="file-size-config"
```

### Available Options

[](#available-options)

```
// config/file-size.php
return [
    // Default byte base: 'binary' (1024) or 'decimal' (1000)
    'byte_base' => env('FILE_INFO_BYTE_BASE', 'binary'),

    // Default decimal precision
    'precision' => 2,

    // Formatting options
    'formatting' => [
        'label_style'                  => 'decimal', // 'decimal', 'binary' or null (`null` uses value from `byte_base`)
        'decimal_separator'            => '.',
        'thousands_separator'          => ',',
        'space_between_value_and_unit' => true,
    ],

    // Validation options
    'validation' => [
        'allow_negative_input'     => false,
        'throw_on_negative_result' => false,
    ],
];
```

Validation
----------

[](#validation)

### Negative Values

[](#negative-values)

By default, negative input values throw an exception:

```
FileSize::megabytes(-5); // Throws NegativeValueException
```

Enable negative values in configuration:

```
// config/file-size.php
'validation' => [
    'allow_negative_input' => true,
],
```

### Invalid Values

[](#invalid-values)

```
FileSize::bytes(INF); // Throws InvalidValueException
FileSize::bytes(NAN); // Throws InvalidValueException
```

### Division by Zero

[](#division-by-zero)

```
$size->divide(0); // Throws InvalidValueException
```

Accessors
---------

[](#accessors)

```
$size = FileSize::megabytes(5, ByteBase::Binary)->precision(4);

$size->getBytes();     // 5242880.0
$size->getByteBase();  // ByteBase::Binary
$size->getPrecision(); // 4
```

Testing
-------

[](#testing)

```
composer test
```

Code Quality
------------

[](#code-quality)

```
composer format  # Laravel Pint
composer analyse # PHPStan level 7
composer rector  # Rector suggestions
```

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

44

—

FairBetter than 92% of packages

Maintenance80

Actively maintained with recent releases

Popularity22

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~8 days

Total

7

Last Release

105d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/8720813?v=4)[Martin Camen](/maintainers/MartinCamen)[@MartinCamen](https://github.com/MartinCamen)

---

Top Contributors

[![MartinCamen](https://avatars.githubusercontent.com/u/8720813?v=4)](https://github.com/MartinCamen "MartinCamen (16 commits)")

---

Tags

laravelstorageformattingbytesfile-size

###  Code Quality

TestsPest

Static AnalysisPHPStan, Rector

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/martincamen-laravel-file-size/health.svg)

```
[![Health](https://phpackages.com/badges/martincamen-laravel-file-size/health.svg)](https://phpackages.com/packages/martincamen-laravel-file-size)
```

###  Alternatives

[djurovicigoor/lara-files

Lara-files is a package which will make it easier to work with files. Package has built-in support for DigitalOcean spaces and Amazon S3.

1196.5k](/packages/djurovicigoor-lara-files)[mwguerra/filemanager

A full-featured file manager package for Laravel and Filament v5 with dual operating modes, drag-and-drop uploads, S3/MinIO support, and comprehensive security features.

718.5k1](/packages/mwguerra-filemanager)[zing/laravel-flysystem-obs

Flysystem Adapter for OBS

1211.2k](/packages/zing-laravel-flysystem-obs)[vormkracht10/flysystem-uploadcare

Flysystem driver for Uploadcare for Laravel.

1834.2k](/packages/vormkracht10-flysystem-uploadcare)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)