Download the PHP package fluxfiles/laravel without Composer

FluxFiles for Laravel

Laravel adapter for FluxFiles — a standalone, embeddable file manager with multi-storage support (Local, AWS S3, Cloudflare R2).

Requirements

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

Installation

Publish the config file:

Add to your .env:

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

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

Cloud storage (optional)

The s3 and r2 disks read these from .env (see config/fluxfiles.php):

Modes

Proxy mode: exclude the route prefix from CSRF or uploads/deletes return 419 — see CSRF exclusion.

Set mode in .env:

SFTP disk & SSH terminal

Managing a remote VPS / shared host (SFTP disk, chmod, the SSH terminal) is a standalone-mode feature. Those serve files through the app and the terminal holds a live SSH connection, so they aren't proxied through Laravel routes.

• standalone mode (recommended for SFTP/terminal): run the FluxFiles server (or the Docker image), give it the SFTP_* env vars (see the core README → SFTP disk and SSH terminal), and point Laravel at it with FLUXFILES_ENDPOINT. Then mint tokens with the sftp disk and, opt-in, the terminal:

• proxy mode: local / S3 / R2 only. SFTP serving and the terminal aren't available here (the endpoints aren't proxied), so those claims are dropped — use standalone mode for them. Burn-in watermark works in both modes.

Usage

Blade Component

Generate Token

Enable Import from URL

Import-from-URL is off by default. There's nothing to install or configure server-side per tenant — enabling it is a token claim. Add the import claims to the override array:

The core then accepts POST /api/fm/import-url ({ "url": "…", "path": "…" }) for that token — SSRF-guarded and sharing the quota/dedup/variants pipeline. Server-wide defaults (when a claim is omitted) come from FLUXFILES_IMPORT_* env vars on the core service.

Per-tenant configuration

FluxFiles is stateless — the token is the per-tenant config. There's no config file or table per customer; you mint a different token, and FluxFiles enforces its claims server-side. Drive the values from the tenant's plan:

Always derive prefix from the authenticated tenant server-side — never from client input. For full isolation, give each tenant their own bucket with BYOB (byob_disks). See the root README's Multi-tenant section for the full claim list, and Permissions for the storage each tenant's _fluxfiles/ index needs.

The ai_auto_tag, rate_read / rate_write and variants overrides are enforced by core ≥ 0.2.8 — on an older core they're simply ignored (the adapter still issues a valid token, it just won't crash). Run composer update fluxfiles/fluxfiles to pick them up.

Blade Directives

Facade Methods

Configuration

After publishing, edit config/fluxfiles.php:

CSRF exclusion (proxy mode only)

In proxy mode the routes run under the web middleware group (needed for the session-based auth bridge), which includes Laravel's CSRF protection. The FluxFiles SDK authenticates every call with an Authorization: Bearer <jwt> header — not a Laravel CSRF token — so the mutating routes (upload, delete, move, rename, …) return 419 Page Expired until you exclude the FluxFiles route prefix from CSRF. Use the value of config('fluxfiles.route_prefix') (default api/fm) with a /* wildcard.

The file/location differs by Laravel version:

Laravel 11 / 12 — there is no VerifyCsrfToken.php; configure it in bootstrap/app.php:

Laravel 9 / 10 — add it to the $except array in app/Http/Middleware/VerifyCsrfToken.php:

Standalone mode is unaffected — the core runs as its own server with its own Origin-based CSRF check, and Laravel only mints tokens / embeds the iframe.

Permissions

FluxFiles keeps all of its state on disk (no database). Two locations must be writable by the user PHP-FPM runs as (usually www-data):

The _fluxfiles/ directory lives inside the disk root you configure (e.g. public_path('uploads') → public/uploads/_fluxfiles/). PHP creates it on the first write, so the safest rule is: let PHP create it — don't pre-create it as root or your deploy user.

Symptom → fix. A 500 with fopen(.../_fluxfiles/index.lock): Permission denied (or, on core ≥ 0.2.7, a clean storage_not_writable error naming the path) means the web server user can't write _fluxfiles/. Almost always the directory was pre-created by a different user — chown it back to the PHP-FPM user (or delete it and let PHP recreate it):

If the disk root is inside public/, make sure _fluxfiles/ is not served: its contents are internal (the index can reveal file names). For nginx:

On S3 / R2 disks there is nothing to chmod — _fluxfiles/ lives in the bucket as regular objects, governed by your IAM policy (s3:PutObject etc.). Run the Bucket Doctor to verify those grants.

Deployment & permissions (rate_limit.json)

In proxy mode the rate limiter keeps its counter in a JSON file at config('fluxfiles.storage_path') — by default storage/fluxfiles/rate_limit.json (override with FLUXFILES_STORAGE_PATH). PHP creates the directory 0755 and the file 0600 automatically on the first request.

What you need on the server:

• The directory must be writable by the user PHP-FPM runs as (usually www-data). Laravel's storage/ already requires this, so the standard deploy perms cover it:

• Let PHP create rate_limit.json itself. It's chmod-ed to 0600 (owner only), so it must be owned by the PHP-FPM user. If a deploy script or root pre-creates it as another user, PHP-FPM can't read it and every request fails with 500 "Rate limiter unavailable". Fix:

• No web-server rule needed. Unlike the standalone core, this file lives under Laravel's storage/ (outside the public/ web root), so it is never served. Keep the 0600 mode — don't loosen it.

• Read-only / immutable deploys (e.g. containers): point the path at a writable volume —

Standalone mode (running the core server directly) puts the file at packages/core/storage/rate_limit.json instead — there it is under the web root, so block it at the web server (location /storage/rate_limit.json { deny all; }).

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

In config/fluxfiles.php:

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:

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

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

This also covers the _fluxfiles/ index directory FluxFiles writes inside the root — see Permissions for the common _fluxfiles/index.lock permission-denied symptom and fix.

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:

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

• 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

• Blade component <x-fluxfiles> 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

MIT — see LICENSE for details.

Links

• FluxFiles — Main repository
• Documentation — Full docs
• Issues — Bug reports