PHPackages                             mheads/yii-filestorage - 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. mheads/yii-filestorage

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

mheads/yii-filestorage
======================

Core file storage facade for Yii3/yiisoft projects.

1.0.1(1mo ago)124↓87.5%2BSD-3-ClausePHPPHP 8.3 - 8.5

Since Jun 3Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/mheads-dev/yii-filestorage)[ Packagist](https://packagist.org/packages/mheads/yii-filestorage)[ RSS](/packages/mheads-yii-filestorage/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (4)Dependencies (28)Versions (5)Used By (2)

mheads/yii-filestorage
======================

[](#mheadsyii-filestorage)

A unified facade for working with uploaded files in Yii3 / yiisoft projects.

The package separates file handling into three responsibilities:

- `Storage` - one facade for `add()`, `findById()`, `remove()`, `getUrl()`, `getContent()`, and `getResource()`.
- `StoreInterface` - physical file storage, for example public or private filesystem storage.
- `RepositoryInterface` - file metadata storage.

The core package contains the facade, file entity, repository/store contracts, filesystem stores, and a lightweight demo repository for local examples. DB and ActiveRecord integrations live in separate adapter packages: [`mheads/yii-filestorage-db`](https://github.com/mheads-dev/yii-filestorage-db) and [`mheads/yii-filestorage-active-record`](https://github.com/mheads-dev/yii-filestorage-active-record).

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

[](#requirements)

- PHP 8.3 - 8.5.
- `yiisoft/files` `^2.1`.
- `yiisoft/strings` `^2.7`.
- `psr/http-message` `^2.0`.

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

[](#installation)

Install the package with [Composer](https://getcomposer.org):

```
composer require mheads/yii-filestorage
```

Adapters
--------

[](#adapters)

Install an adapter when file metadata must be stored outside the demo repository:

- [`mheads/yii-filestorage-db`](https://github.com/mheads-dev/yii-filestorage-db) - DB metadata repository and migrations.
- [`mheads/yii-filestorage-active-record`](https://github.com/mheads-dev/yii-filestorage-active-record) - ActiveRecord integration. Depends on `mheads/yii-filestorage-db`.

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

[](#quick-start)

### 1. Configure storage

[](#1-configure-storage)

For manual configuration:

```
use Mheads\Yii\Filestorage\Repository\DemoRepository;
use Mheads\Yii\Filestorage\Storage;
use Mheads\Yii\Filestorage\StorageProvider;
use Mheads\Yii\Filestorage\Store\FileSystem\PublicFileSystemStore;

$repository = new DemoRepository('/app/runtime/demo-filestorage.json');

$storage = new Storage(
    repository: $repository,
    stores: [
        new PublicFileSystemStore(
            name: 'upload',
            path: '/app/runtime/upload',
            baseUrl: 'https://cdn.example.com/upload',
        ),
    ],
    defaultStoreName: 'upload',
    defaultGroupName: 'common',
);

StorageProvider::set($storage);
```

For production metadata storage, install [`mheads/yii-filestorage-db`](https://github.com/mheads-dev/yii-filestorage-db), [`mheads/yii-filestorage-active-record`](https://github.com/mheads-dev/yii-filestorage-active-record), or implement a repository adapter.

### 2. Add and read a file

[](#2-add-and-read-a-file)

```
/** @var \Mheads\Yii\Filestorage\StorageInterface $storage */

$file = $storage->add($uploadedFile, groupName: 'products');

$url = $storage->getUrl($file);
$content = $storage->getContent($file);
$resource = $storage->getResource($file);

$sameFile = $storage->findById($file->getId());
if($sameFile !== null) {
    $storage->remove($sameFile);
}
```

See [Usage basics](docs/guide/en/usage.md) for details.

Documentation
-------------

[](#documentation)

- [Guide](docs/guide/en/README.md)
- [Internals](docs/internals.md)
- [Examples](examples/README.md)

Examples
--------

[](#examples)

`examples/*` are reference/demo scripts. Adapt them to your project runtime: paths, bootstrap, and launch method.

See [examples/README.md](examples/README.md).

License
-------

[](#license)

The package is released under the [BSD 3-Clause License](LICENSE.md).

###  Health Score

44

—

FairBetter than 90% of packages

Maintenance90

Actively maintained with recent releases

Popularity10

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 75% 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 ~0 days

Total

4

Last Release

49d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/8805360bd6ba1a19f70a9a23819afe7109a80ea0a4c387201f4fa986a50c75f8?d=identicon)[alse0017](/maintainers/alse0017)

---

Top Contributors

[![sa-machineheads](https://avatars.githubusercontent.com/u/22737984?v=4)](https://github.com/sa-machineheads "sa-machineheads (3 commits)")[![alse0017](https://avatars.githubusercontent.com/u/13018747?v=4)](https://github.com/alse0017 "alse0017 (1 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/mheads-yii-filestorage/health.svg)

```
[![Health](https://phpackages.com/badges/mheads-yii-filestorage/health.svg)](https://phpackages.com/packages/mheads-yii-filestorage)
```

###  Alternatives

[aws/aws-sdk-php

AWS SDK for PHP - Use Amazon Web Services in your PHP project

6.2k543.5M2.7k](/packages/aws-aws-sdk-php)[guzzlehttp/psr7

PSR-7 message implementation that also provides common utility methods

7.9k1.1B4.1k](/packages/guzzlehttp-psr7)[google/cloud

Google Cloud Client Library

1.2k16.7M57](/packages/google-cloud)[neuron-core/neuron-ai

The PHP Agentic Framework.

2.0k656.1k46](/packages/neuron-core-neuron-ai)[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k16](/packages/tempest-framework)[telnyx/telnyx-php

Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network.

36789.4k2](/packages/telnyx-telnyx-php)

PHPackages © 2026

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