PHPackages                             mitsuki/storage - 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. mitsuki/storage

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

mitsuki/storage
===============

A flexible and framework-agnostic storage library for managing structured records, originally built for the Mitsuki PHP framework and usable in any PHP application.

v1.0.0(2mo ago)10MITPHPCI passing

Since Feb 25Pushed 2mo agoCompare

[ Source](https://github.com/zgeniuscoders/mitsuki-storage)[ Packagist](https://packagist.org/packages/mitsuki/storage)[ RSS](/packages/mitsuki-storage/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (5)Versions (2)Used By (0)

Mitsuki Storage
===============

[](#mitsuki-storage)

**Mitsuki Storage** is a flexible, framework-agnostic PHP library for managing file storage and structured records. Originally built for the Mitsuki framework, it provides a clean and secure abstraction over the Symfony Filesystem component to handle uploads, persistence, and file management in any PHP application.

---

🚀 Features
----------

[](#-features)

- **Secure Uploads**: Automatic unique filename generation to prevent collisions and overwrites.
- **Fluent Directory Management**: Automatically handles recursive directory creation.
- **Standardized Exceptions**: Robust error handling with custom `FileException` and `FileNotFoundException`.
- **Framework Agnostic**: Integration-ready for Laravel, Symfony, Slim, or any vanilla PHP project.
- **Fully Tested**: High-quality code base tested with Pest PHP.

---

📦 Installation
--------------

[](#-installation)

Install the package via Composer:

```
composer require mitsuki/storage
```

---

🛠 Usage
-------

[](#-usage)

### Initialization

[](#initialization)

To start, you need a base directory where files will be stored and an instance of Symfony's `Filesystem`.

```
use Mitsuki\Storage\Storage;
use Symfony\Component\Filesystem\Filesystem;

$baseDir = __DIR__ . '/storage';
$storage = new Storage(new Filesystem(), $baseDir);
```

### Storing an Uploaded File

[](#storing-an-uploaded-file)

The `store` method expects a `Symfony\Component\HttpFoundation\File\UploadedFile` (standard in many frameworks).

```
try {
    // Stores file in storage/avatars/user-1/ with a secure unique name
    $absolutePath = $storage->store('avatars/user-1', $uploadedFile);

    echo "File saved at: " . $absolutePath;
} catch (FileException $e) {
    echo "Upload failed: " . $e->getMessage();
}
```

### Retrieving and Checking Files

[](#retrieving-and-checking-files)

```
// Get the absolute path of a relative file
try {
    $path = $storage->getFile('avatars/user-1/photo.jpg');
} catch (FileNotFoundException $e) {
    // Handle error
}

// Simple existence check
if ($storage->exists('documents/report.pdf')) {
    // Logic here...
}
```

### Deleting Files

[](#deleting-files)

```
try {
    $storage->delete('temp/old-file.txt');
} catch (FileNotFoundException $e) {
    // File not found
}
```

---

🧪 Testing
---------

[](#-testing)

The library is tested using [Pest PHP](https://pestphp.com).

```
# Install development dependencies
composer install

# Run the test suite
vendor/bin/pest
```

---

📄 API Reference
---------------

[](#-api-reference)

### `Storage` Class

[](#storage-class)

MethodArgumentDescription`store()``string $path, UploadedFile $file`Validates, secures, and moves an upload. Returns full path.`getFile()``string $path`Resolves a relative path to an absolute path.`exists()``string $path`Returns `true` if the path exists.`createDir()``string $path`Recursively creates directories.`delete()``string $path`Removes a file or directory.---

👤 Author
--------

[](#-author)

**Zgenius Matondo**

- GitHub: [@zgeniusecoders](https://www.google.com/search?q=https://github.com/zgeniusecoders)
- Email:

---

⚖️ License
----------

[](#️-license)

This project is licensed under the MIT License - see the [LICENSE](https://www.google.com/search?q=LICENSE) file for details.

---

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance84

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity34

Early-stage or recently created project

 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

Unknown

Total

1

Last Release

82d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/59ea5d2ce29d5426a3d7feabbcc7b07772b03dd80e4cd13afd6f9ac5e0469998?d=identicon)[zgenius](/maintainers/zgenius)

---

Top Contributors

[![zgeniuscoders](https://avatars.githubusercontent.com/u/101071661?v=4)](https://github.com/zgeniuscoders "zgeniuscoders (1 commits)")

---

Tags

phppersistencestoragebackendmodularframework agnosticdata-storagemitsukiorecord-managementfiches

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/mitsuki-storage/health.svg)

```
[![Health](https://phpackages.com/badges/mitsuki-storage/health.svg)](https://phpackages.com/packages/mitsuki-storage)
```

###  Alternatives

[sylius/resource-bundle

Resource component for Sylius.

23410.2M173](/packages/sylius-resource-bundle)[bitrix24/b24phpsdk

An official PHP library for the Bitrix24 REST API

9230.2k4](/packages/bitrix24-b24phpsdk)

PHPackages © 2026

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