PHPackages                             nvahalik/laravel-filer - 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. nvahalik/laravel-filer

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

nvahalik/laravel-filer
======================

An advanced wrapper over Flysystem for Laravel.

1.0.0(3y ago)164.2k1[3 issues](https://github.com/nvahalik/laravel-filer/issues)MITPHPPHP >=7.4

Since Jan 24Pushed 3y ago1 watchersCompare

[ Source](https://github.com/nvahalik/laravel-filer)[ Packagist](https://packagist.org/packages/nvahalik/laravel-filer)[ RSS](/packages/nvahalik-laravel-filer/feed)WikiDiscussions master Synced 1mo ago

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

Laravel Filer
=============

[](#laravel-filer)

This project was started to scratch my itch on our growing Laravel site:

- **Metadata for all files is stored in a local repository** - Supported backing systems are `json`, `database`, and `memory` (for testing). This is designed to speed up certain operations which normally call out to the remote filesystems.
- **Handles fallback to the original disk** - If you provide an "original disk" list, this adapter will attempt to import data from those original disks into the metadata repository.
- **Pluggable Strategies** - While the current version ships with a single strategy, you can replace the `Basic`implementation which allows for 1 + async, mirror, or other interactions with backing storage adapters.
- **Manage data + files** - Coming soon: query and manage the metadata to do things like:
    - Find files stored on a single service and mirror them
    - Migrate files between stores while still maintaining continuity
- **Abstract data from metadata** - Planning at some point on allow things like deduplication and copy-on-write to make copies, renames, and deletions work better.

Getting Started
===============

[](#getting-started)

To get started, require the project.

Laravel 7, 8 (Flysystem V1):

```
composer require nvahalik/laravel-filer@^1

```

Laravel 9 (Flysystem V3):

```
composer require nvahalik/laravel-filer@dev-laravel-9

```

Once that's done, you'll need to edit the filer config file and then update your filesystem configuration.

Config File
===========

[](#config-file)

By default, the metadata is stored in a JSON file. You can edit `config/filer.php` to change the default storage mechanism from `json` to `database` or `memory`. Note that memory is really a null adapter. The JSON adapter wraps memory and just serializes and saves it after each operation.

Filesystem Configuration
========================

[](#filesystem-configuration)

The configuration is very similar to other disks:

```
'example' => [
    'driver' => 'filer',
    'original_disks' => [
        'test:s3-original',
    ],
    'id' => 'test',
    'disk_strategy' => 'basic',
    'backing_disks' => [
        'test:s3-new',
        'test:s3-original',
    ],
    'visibility' => 'private',
],

```

The `original_disks` is an option if you are migrating from an existing disk or disks to the filer system. Effectively, this is a fallback so that files which are not found in the local metadata store will be searched for in `original_disks`. If they are found, their metadata will be imported. If not, the file will be treated as missing. We'll cover doing mass importing of metadata later on.

**Note: that this will slow the filesystem down until the cache is filled. Once the cache is loaded, you can remove these original\_disks and those extra operations looking for files will be eliminated.**

**Note 2: files which are truly missing do not get cached. Therefore, if a file is missing, and you repeatedly attempt to assert its existence, it will search over and over again. This could be improved by caching the results or likewise having some sort of `missing-files` cache.**

`id` is just an internal ID for the metadata store. File duplications are not allowed within the metadata of a single `id`, for example, but would be allowed for different `id`s.

`disk_strategy` has only a single option currently: `'basic'` but will be pluggable to allow for different strategies to be added and used. The `basic` strategy simply writes to the first available disk from the list of provided `backing_disks`.

`backing_disks` allows you to define multiple flysystem disks to use. Want to use multiple S3-compatible adapters? You can. Note that for the basic adapter, the order of the disks determines the order in which they are tried.

A couple of examples
--------------------

[](#a-couple-of-examples)

Given the configuration above, if the following code is run:

```
Storage::disk('example')->has('does/not/exist.txt');

```

1. The existing metadata repo will be searched.
2. Then, the single 'original\_disks' will be searched.
3. Finally, the operation will fail.

```
Storage::disk('example')->put('does/not/exist.txt', 'content');

```

1. The existing metadata repo will be searched.
2. Then, the single 'original\_disks' will be searched.
3. Then, a write will be attempted on `test:s3-new`.
4. If that fails, then a write will be attempted on `test:s3-original`.
5. If any of the writes succeeds, that adapter's backing information will be returned and the entries metadata updated.
6. If any of them fails, then false will be returned and the operation will have failed.

Importing Metadata
==================

[](#importing-metadata)

If you already have a ton of files on S3, you can use the `filer:import-s3-metadata` command to import that data into your metadata repository:

```
# Grab the existing contents.
s3cmd ls s3://bucket-name -rl > s3output.txt

# Import that data into the "example" storageId.
php artisan filer:import-s3-metadata example s3output.txt
```

The importer uses `File::lines()` to load its data, and therefore should not consume a lot of memory. Additionally, it will look at the bucket name in the URL which is present in the output and attempt to find that within your existing filesystems config.

Visibility
----------

[](#visibility)

By default, it will grab this from the filesystem configuration. If none is found nor provided with `--visibility`, it will default to `private`.

Filename stripping
------------------

[](#filename-stripping)

You can strip a string from the filenames by specifying the `--strip` option.

Disk
----

[](#disk)

If you need to specify the disk directly or want to otherwise override it, just pass it in with `--disk`. This is not checked, so don't mess it up.

Example
-------

[](#example)

```
php artisan filer:import-s3-metadata example s3output.txt --disk=some-disk --visibility=public --strip=prefix-dir/
```

The above command would strip `prefix-dir/` from the imported URLs, set their visibility to public, and mark their default backing-disk to `some-disk`.

###  Health Score

27

—

LowBetter than 49% of packages

Maintenance16

Infrequent updates — may be unmaintained

Popularity25

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity46

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

Unknown

Total

1

Last Release

1204d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/07d893fa2cb6e7ed1398099d7abfa8ece8618e3e1a1ea17c0ebd31e7ec3382b6?d=identicon)[nvahalik](/maintainers/nvahalik)

---

Top Contributors

[![nvahalik](https://avatars.githubusercontent.com/u/632120?v=4)](https://github.com/nvahalik "nvahalik (47 commits)")

---

Tags

filesystemFlysystem

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/nvahalik-laravel-filer/health.svg)

```
[![Health](https://phpackages.com/badges/nvahalik-laravel-filer/health.svg)](https://phpackages.com/packages/nvahalik-laravel-filer)
```

###  Alternatives

[league/flysystem-aws-s3-v3

AWS S3 filesystem adapter for Flysystem.

1.6k263.6M790](/packages/league-flysystem-aws-s3-v3)[league/flysystem-local

Local filesystem adapter for Flysystem.

226231.8M39](/packages/league-flysystem-local)[oneup/flysystem-bundle

Integrates Flysystem filesystem abstraction library to your Symfony project.

64422.9M66](/packages/oneup-flysystem-bundle)[league/flysystem-bundle

Symfony bundle integrating Flysystem into Symfony applications

40029.5M87](/packages/league-flysystem-bundle)[league/flysystem-sftp-v3

SFTP filesystem adapter for Flysystem.

6129.6M91](/packages/league-flysystem-sftp-v3)[league/flysystem-memory

In-memory filesystem adapter for Flysystem.

8533.6M194](/packages/league-flysystem-memory)

PHPackages © 2026

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