PHPackages                             monkeyscloud/monkeyslegion-files - 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. monkeyscloud/monkeyslegion-files

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

monkeyscloud/monkeyslegion-files
================================

Production-ready file storage, upload, and image processing for the MonkeysLegion framework

2.1.1(2mo ago)12.2k—0.5%[1 PRs](https://github.com/MonkeysCloud/MonkeysLegion-Files/pulls)1MITPHPPHP ^8.4

Since Jul 26Pushed 2mo agoCompare

[ Source](https://github.com/MonkeysCloud/MonkeysLegion-Files)[ Packagist](https://packagist.org/packages/monkeyscloud/monkeyslegion-files)[ RSS](/packages/monkeyscloud-monkeyslegion-files/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (28)Versions (12)Used By (1)

MonkeysLegion Files v2
======================

[](#monkeyslegion-files-v2)

Production-ready file storage, upload, and image processing for the MonkeysLegion framework.

> **PHP 8.4+** | Property Hooks | Asymmetric Visibility | Zero-Magic

Features
--------

[](#features)

FeatureStatusMulti-driver storage (Local, S3, GCS, Memory)✅Presigned upload URLs (browser → S3 direct)✅MIME content sniffing (anti-spoofing)✅Atomic writes (tmp + rename)✅Cross-disk copy/move✅Upload validation (size, MIME, extension)✅File record entity with property hooks✅Domain events (FileStored, FileDeleted, FileMoved)✅CDN URL generation with signed URLs✅Image processing (GD/Imagick, WebP/AVIF)✅Virus scanning integration✅In-memory driver for testing✅Garbage collection for orphaned files✅Installation
------------

[](#installation)

```
composer require monkeyscloud/monkeyslegion-files
```

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

[](#quick-start)

```
use MonkeysLegion\Files\FilesManager;
use MonkeysLegion\Files\Driver\LocalDriver;
use MonkeysLegion\Files\Driver\MemoryDriver;

// Create a manager with disks
$manager = new FilesManager(
    disks: [
        'local' => new LocalDriver('/var/www/storage', '/files'),
        'tmp'   => new MemoryDriver(),
    ],
    defaultDisk: 'local',
);

// Store a file
$manager->put('documents/readme.md', '# Hello World');

// Read it back
$contents = $manager->get('documents/readme.md');

// Check existence
$manager->exists('documents/readme.md'); // true

// Get metadata
$manager->size('documents/readme.md');     // 13
$manager->mimeType('documents/readme.md'); // 'text/plain'
$manager->checksum('documents/readme.md'); // sha256 hash
```

Upload Handling
---------------

[](#upload-handling)

```
use MonkeysLegion\Files\Upload\UploadedFile;
use MonkeysLegion\Files\Upload\UploadValidator;
use MonkeysLegion\Files\Security\ContentValidator;

// Create manager with validation
$manager = new FilesManager(
    disks: ['local' => new LocalDriver('/var/www/storage')],
    validator: new UploadValidator(
        maxSize: 50 * 1024 * 1024,  // 50 MB
        allowedMimes: ['image/jpeg', 'image/png', 'application/pdf'],
        deniedExtensions: ['php', 'exe', 'sh'],
    ),
    contentValidator: new ContentValidator(), // MIME sniffing
);

// Handle upload
$file = UploadedFile::fromGlobal($_FILES['avatar']);

// Property hooks — zero methods!
echo $file->extension;  // 'jpg'
echo $file->isImage;    // true
echo $file->humanSize;  // '2.5 MB'

$result = $manager->upload($file, 'avatars');

if ($result->failed) {
    // $result->errors contains validation messages
    foreach ($result->errors as $error) {
        echo $error;
    }
} else {
    echo $result->file->uuid;      // '550e8400-...'
    echo $result->file->humanSize; // '2.5 MB'
    echo $result->file->isImage;   // true
}
```

FileRecord — PHP 8.4 Property Hooks
-----------------------------------

[](#filerecord--php-84-property-hooks)

```
use MonkeysLegion\Files\Entity\FileRecord;
use MonkeysLegion\Files\Visibility;

$record = new FileRecord(
    disk: 'local',
    path: '/uploads/photo.jpg',  // set hook strips leading /
    originalName: 'photo.jpg',
    mimeType: 'image/jpeg',
    size: 2_621_440,
);

// Computed properties via get hooks — no methods!
$record->path;         // 'uploads/photo.jpg' (set hook normalized)
$record->extension;    // 'jpg'
$record->basename;     // 'photo'
$record->isImage;      // true
$record->isVideo;      // false
$record->humanSize;    // '2.5 MB'
$record->isDeleted;    // false

// Asymmetric visibility — read public, write private
$record->id;           // null (public private(set))
$record->uuid;         // '550e8400-...' (public private(set))
$record->createdAt;    // DateTimeImmutable (public private(set))

// Business logic
$record->softDelete();
$record->isDeleted;    // true (computed via hook)
$record->restore();

$record->attachTo('App\\Entity\\User', 42, 'avatars');
$record->setChecksum('abc123', 'sha256');
```

Cross-Disk Operations
---------------------

[](#cross-disk-operations)

```
// Copy between disks
$manager->crossDiskCopy(
    source: 'photo.jpg',
    destination: 'photo.jpg',
    sourceDisk: 'local',
    destDisk: 's3',
);

// Move between disks (atomic: copy + delete)
$manager->crossDiskMove(
    source: 'temp/file.pdf',
    destination: 'documents/file.pdf',
    sourceDisk: 'local',
    destDisk: 's3',
);
```

Storage Drivers
---------------

[](#storage-drivers)

### LocalDriver

[](#localdriver)

```
use MonkeysLegion\Files\Driver\LocalDriver;
use MonkeysLegion\Files\Visibility;

$local = new LocalDriver(
    basePath: '/var/www/storage',
    baseUrl: '/files',
    dirPermissions: 0o755,
    filePermissions: 0o644,
    defaultVisibility: Visibility::Public,
);
```

### MemoryDriver (Testing)

[](#memorydriver-testing)

```
use MonkeysLegion\Files\Driver\MemoryDriver;

$memory = new MemoryDriver();
$memory->put('test.txt', 'hello');

// Property hooks for test assertions
echo $memory->fileCount;   // 1
echo $memory->totalBytes;  // 5
```

Security
--------

[](#security)

### Path Traversal Prevention

[](#path-traversal-prevention)

The `LocalDriver` blocks `..` segments and validates resolved paths against the base directory. Both regex and `realpath()` checks are applied.

### MIME Content Sniffing

[](#mime-content-sniffing)

```
$validator = new ContentValidator();
$validator->validate('/tmp/upload.jpg', 'image/jpeg');
// Throws SecurityException if actual content is PHP code
```

### Virus Scanning

[](#virus-scanning)

```
use MonkeysLegion\Files\Security\ScanResult;

$result = new ScanResult(isClean: false, threat: 'Trojan.Gen');
$result->hasThreat; // true (computed via hook)
```

Domain Events
-------------

[](#domain-events)

```
use MonkeysLegion\Files\Event\FileStored;
use MonkeysLegion\Files\Event\FileDeleted;
use MonkeysLegion\Files\Event\FileMoved;

// All events are readonly value objects
$event = new FileStored(file: $record, disk: 'local');
$event->occurredAt; // DateTimeImmutable
```

Enums
-----

[](#enums)

```
use MonkeysLegion\Files\Visibility;
use MonkeysLegion\Files\Image\ImageFormat;
use MonkeysLegion\Files\Image\ImageDriver;

Visibility::Public;   // 'public'
Visibility::Private;  // 'private'

ImageFormat::Webp->mimeType();   // 'image/webp'
ImageFormat::Avif->extension();  // 'avif'

ImageDriver::Gd->isAvailable();  // true/false
```

Architecture
------------

[](#architecture)

```
src/
├── Contracts/          # StorageInterface, CloudStorageInterface
├── Driver/             # LocalDriver, MemoryDriver (S3/GCS stubs)
├── Entity/             # FileRecord with property hooks
├── Event/              # FileStored, FileDeleted, FileMoved
├── Exception/          # FilesException hierarchy
├── Image/              # ImageDriver, ImageFormat enums
├── Security/           # ContentValidator, ScanResult
├── Upload/             # UploadedFile, UploadValidator, UploadResult
├── FilesManager.php    # Main facade
└── Visibility.php      # Backed enum

```

Testing
-------

[](#testing)

```
vendor/bin/phpunit               # 127 tests, 223 assertions
vendor/bin/phpunit --coverage-text
```

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

[](#requirements)

- PHP ^8.4
- monkeyscloud/monkeyslegion-mlc ^3.1.2
- psr/log ^3.0

License
-------

[](#license)

MIT © MonkeysCloud Team

###  Health Score

48

—

FairBetter than 93% of packages

Maintenance85

Actively maintained with recent releases

Popularity22

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity61

Established project with proven stability

 Bus Factor1

Top contributor holds 81.1% 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 ~44 days

Recently: every ~30 days

Total

7

Last Release

78d ago

Major Versions

1.0.1 → 2.0.0.x-dev2025-12-15

PHP version history (2 changes)1.0.0PHP >=8.4

2.0.0.x-devPHP ^8.4

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/2913369?v=4)[Jorge Peraza](/maintainers/yorchperaza)[@yorchperaza](https://github.com/yorchperaza)

---

Top Contributors

[![yorchperaza](https://avatars.githubusercontent.com/u/2913369?v=4)](https://github.com/yorchperaza "yorchperaza (30 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (7 commits)")

---

Tags

s3image processingfilesstorageazuregcsuploadchunked-uploadmonkeyslegion

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/monkeyscloud-monkeyslegion-files/health.svg)

```
[![Health](https://phpackages.com/badges/monkeyscloud-monkeyslegion-files/health.svg)](https://phpackages.com/packages/monkeyscloud-monkeyslegion-files)
```

###  Alternatives

[league/flysystem

File storage abstraction for PHP

13.6k679.9M2.5k](/packages/league-flysystem)[league/flysystem-aws-s3-v3

AWS S3 filesystem adapter for Flysystem.

1.7k285.7M1.0k](/packages/league-flysystem-aws-s3-v3)[creocoder/yii2-flysystem

The flysystem extension for the Yii framework

2931.7M63](/packages/creocoder-yii2-flysystem)[league/flysystem-async-aws-s3

AsyncAws S3 filesystem adapter for Flysystem.

2812.1M44](/packages/league-flysystem-async-aws-s3)[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.

7620.3k3](/packages/mwguerra-filemanager)[verseles/flyclone

PHP wrapper for rclone

102.3k](/packages/verseles-flyclone)

PHPackages © 2026

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