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

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

fluxfiles/laravel
=================

Laravel adapter for FluxFiles file manager

v0.1.0(1w ago)08MITPHPPHP ^8.1

Since May 30Pushed 1w agoCompare

[ Source](https://github.com/thai-pc/fluxfiles-laravel)[ Packagist](https://packagist.org/packages/fluxfiles/laravel)[ Docs](https://github.com/thai-pc/fluxfiles)[ RSS](/packages/fluxfiles-laravel/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (3)Dependencies (8)Versions (12)Used By (0)

FluxFiles for Laravel
=====================

[](#fluxfiles-for-laravel)

Laravel adapter for [FluxFiles](https://github.com/thai-pc/fluxfiles) — a standalone, embeddable file manager with multi-storage support (Local, AWS S3, Cloudflare R2).

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

[](#requirements)

- PHP >= 8.1 (matches `fluxfiles/fluxfiles`)
- Laravel 10, 11, or 12

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

[](#installation)

```
composer require fluxfiles/laravel
```

Publish the config file:

```
php artisan vendor:publish --tag=fluxfiles-config
```

Add to your `.env`:

```
FLUXFILES_SECRET=your-random-32-char-secret
```

For the default local disk, expose Laravel public storage once:

```
php artisan storage:link
```

The default `local` disk writes to `storage/app/public/fluxfiles/uploads` and returns URLs under `/storage/fluxfiles/uploads`.

Modes
-----

[](#modes)

ModeDescription`proxy` (default)FluxFiles API runs through Laravel routes — no separate server needed`standalone`FluxFiles runs on its own server; Laravel only generates tokens and embeds the iframeSet mode in `.env`:

```
FLUXFILES_MODE=proxy
# or
FLUXFILES_MODE=standalone
FLUXFILES_ENDPOINT=https://your-fluxfiles-server.com
```

Usage
-----

[](#usage)

### Blade Component

[](#blade-component)

```

```

### Generate Token

[](#generate-token)

```
use FluxFiles\Laravel\FluxFilesFacade as FluxFiles;

// For the current authenticated user
$token = FluxFiles::tokenForUser();

// With custom overrides
$token = FluxFiles::token(auth()->id(), [
    'perms'      => ['read', 'write'],
    'disks'      => ['local', 's3'],
    'prefix'     => 'user-123/',
    'max_upload'  => 20,    // MB — per uploaded file
    'max_storage' => 1000,  // MB — total quota per prefix (0 = unlimited)
    'max_files'   => 0,     // max files per prefix (0 = unlimited)
    'allowed_ext' => ['jpg', 'png', 'pdf'], // lowercase, no dot; null = all safe
    'ttl'         => 7200,  // seconds — token lifetime (7200 = 2 hours)
]);
```

### Blade Directives

[](#blade-directives)

```

FluxFiles.open({
    endpoint: '@fluxfilesEndpoint',
    token: '@fluxfilesToken',
    disk: 'local',
    mode: 'picker'
});

```

### Facade Methods

[](#facade-methods)

```
use FluxFiles\Laravel\FluxFilesFacade as FluxFiles;

FluxFiles::token($user, $overrides);   // Generate JWT token
FluxFiles::tokenForUser($overrides);   // Token for auth user
FluxFiles::endpoint();                  // Get FluxFiles URL
FluxFiles::iframeSrc();                 // Get iframe source URL
FluxFiles::sdkUrl();                    // Get SDK script URL
```

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

[](#configuration)

After publishing, edit `config/fluxfiles.php`:

```
return [
    'secret'     => env('FLUXFILES_SECRET'),
    'mode'       => env('FLUXFILES_MODE', 'proxy'),
    'endpoint'   => env('FLUXFILES_ENDPOINT'),

    'route_prefix' => 'api/fm',
    'middleware'    => ['web', 'auth'],

    'disks' => [
        'local' => [...],
        's3'    => [...],
        'r2'    => [...],
    ],

    'defaults' => [
        'perms'       => ['read', 'write', 'delete'],
        'disks'       => ['local'],
        'prefix'      => '',
        'max_upload'  => 10,    // MB
        'allowed_ext' => null,  // null = allow all
        'max_storage' => 0,     // 0 = unlimited
        'ttl'         => 3600,  // seconds
    ],

    'locale'      => env('FLUXFILES_LOCALE', ''),
    'ai_provider' => env('FLUXFILES_AI_PROVIDER', ''),
    'ai_api_key'  => env('FLUXFILES_AI_API_KEY', ''),
    'ai_model'    => env('FLUXFILES_AI_MODEL', ''),
    'ai_auto_tag' => env('FLUXFILES_AI_AUTO_TAG', false),
];
```

Using an existing upload directory
----------------------------------

[](#using-an-existing-upload-directory)

If your app already has a directory tree like `public/uploads/user_1/`, `public/uploads/user_2/` (populated before FluxFiles was installed), you can point FluxFiles at it — existing files show up immediately, and a one-shot Artisan command makes them searchable.

### 1. Point the `local` disk at your existing path

[](#1-point-the-local-disk-at-your-existing-path)

In `config/fluxfiles.php`:

```
'disks' => [
    'local' => [
        'driver' => 'local',
        'root'   => public_path('uploads'),     // where your files already live
        'url'    => '/uploads',                 // URL prefix for preview links
    ],
],
```

### 2. Scope each user to their own sub-folder via the `prefix` claim

[](#2-scope-each-user-to-their-own-sub-folder-via-the-prefix-claim)

Always derive the prefix server-side from the authenticated user — never trust client input:

```
use FluxFiles\Laravel\FluxFilesFacade as FluxFiles;

$token = FluxFiles::tokenForUser([
    'prefix' => 'user_' . auth()->id() . '/',
    'disks'  => ['local'],
    'perms'  => ['read', 'write', 'delete'],
]);
```

With `prefix = 'user_1/'`, all API paths are transparently scoped to `public/uploads/user_1/`. User 1 cannot see or touch `user_2/`.

### 3. Filesystem permissions

[](#3-filesystem-permissions)

Make `public/uploads` writable by the PHP process (upload / mkdir / delete):

```
chown -R www-data:www-data public/uploads
chmod -R u+rwX public/uploads
```

### 4. Seed metadata + folder index for pre-existing content

[](#4-seed-metadata--folder-index-for-pre-existing-content)

Listing existing files works out of the box. Preview links load only when the disk `url` matches a path your web server actually serves. **Search** relies on the FluxFiles metadata index (`_fluxfiles/index.json`) and the directory index (`_fluxfiles/dirs.json`), which are only written when content is created through the API. To make pre-existing files and folders searchable, run the included Artisan command once:

```
# Dry run first — report what would be indexed, no writes
php artisan fluxfiles:seed --disk=local --dry-run

# Apply
php artisan fluxfiles:seed --disk=local

# Generate thumbnails for existing images
php artisan fluxfiles:seed --disk=local --variants

# Add hashes for duplicate detection too
php artisan fluxfiles:seed --disk=local --hash --variants

# Only a sub-tree
php artisan fluxfiles:seed --disk=local --path=user_1

# Force re-index (overwrite any existing metadata)
php artisan fluxfiles:seed --disk=local --overwrite
```

What it does:

- Walks the disk recursively (skipping `_fluxfiles/`, `_variants/`, and `*.meta.json`).
- For each **file**: creates a metadata record with `title` derived from the filename so search can find it. Metadata writes are skipped for files that already have metadata unless `--overwrite` is passed, but `--hash` and `--variants` can still fill in missing hashes/thumbnails.
- For each **folder**: tracks it in `_fluxfiles/dirs.json` so folder search (`/api/fm/search-folders`) can return it.

After seeding, both file and folder search work for the existing tree.

### 5. Notes & gotchas

[](#5-notes--gotchas)

- FluxFiles auto-creates `public/uploads/_fluxfiles/` (metadata index and audit log) and `public/uploads/_variants/` (image thumbnails). These are hidden from the UI — do not delete them. If you use FTP/rsync/backup tools, add them to your ignore list.
- `url = '/uploads'` must match how your web server serves `public/`. Preview links are built as `{url}/{key}` — e.g. file key `user_1/avatar.jpg` → `/uploads/user_1/avatar.jpg`.
- Files uploaded **before** seeding won't have an `uploaded_by` metadata field. If you later enable `owner_only`, legacy files fall through gracefully (all users can act on them) until the next time someone edits them through the UI.
- For S3/R2 disks with an existing bucket, the same seed command works — pass `--disk=s3` (or `--disk=r2`). Listing is slower because it pages the bucket remotely.

Features
--------

[](#features)

- **Blade component** `` with auto token generation
- **Blade directives** `@fluxfilesToken` and `@fluxfilesEndpoint`
- **Facade** `FluxFiles::token()` for programmatic token generation
- **Proxy mode** — serve FluxFiles API through Laravel routes
- **Standalone mode** — connect to a separate FluxFiles server
- **Auto-discovery** — ServiceProvider and Facade register automatically
- **16 languages** — en, vi, zh, ja, ko, fr, de, es, ar, pt, it, ru, th, hi, tr, nl

License
-------

[](#license)

MIT — see [LICENSE](LICENSE) for details.

Links
-----

[](#links)

- [FluxFiles](https://github.com/thai-pc/fluxfiles) — Main repository
- [Documentation](https://github.com/thai-pc/fluxfiles#laravel) — Full docs
- [Issues](https://github.com/thai-pc/fluxfiles/issues) — Bug reports

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance98

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

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

11

Last Release

10d ago

PHP version history (2 changes)v1.23.0PHP >=7.4

v1.26.4PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/32d0caeb5c686e7417b8c55fd0f36faff14a9e726c663bff70b84d23193a5db1?d=identicon)[thai-pc](/maintainers/thai-pc)

---

Tags

laravels3uploadfile managerr2fluxfiles

### Embed Badge

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

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

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3325.1M337](/packages/psalm-plugin-laravel)[laravel/cashier

Laravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services.

2.5k28.4M134](/packages/laravel-cashier)[laravel-doctrine/orm

An integration library for Laravel and Doctrine ORM

8455.5M96](/packages/laravel-doctrine-orm)[moonshine/moonshine

Laravel administration panel

1.3k239.9k72](/packages/moonshine-moonshine)[hasinhayder/tyro-dashboard

Tyro Dashboard - Beautiful admin dashboard for managing Tyro roles, privileges, users, and settings

5222.7k](/packages/hasinhayder-tyro-dashboard)[sopamo/laravel-filepond

Laravel backend module for filepond uploads

217293.6k3](/packages/sopamo-laravel-filepond)

PHPackages © 2026

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