Skip to content

File Storage

David Ciulla edited this page Nov 7, 2026 · 2 revisions

File Storage

Laravex's filesystem abstraction is provided by Laravex.Filesystem.Storage. It supports the local driver only — files are read and written to disk paths configured under filesystems.disks. All disk operations are routed through a unified API regardless of which disk you target.

Note: Cloud storage drivers (S3, GCS, etc.) are not implemented in Laravex. Set FILESYSTEM_DISK=local and use the local or public disk for all storage needs.


Configuration

Configure disks in config/filesystems.exs:

%{
  "default" => Laravex.Env.get("FILESYSTEM_DISK", "local"),
  "disks" => %{
    "local" => %{
      "driver" => "local",
      "root"   => Path.join(base_path, "storage/app/private")
    },
    "public" => %{
      "driver"     => "local",
      "root"       => Path.join(base_path, "storage/app/public"),
      "url"        => Laravex.Env.get("APP_URL") <> "/storage",
      "visibility" => "public"
    }
  },
  "links" => %{
    Path.join(base_path, "public/storage") =>
      Path.join(base_path, "storage/app/public")
  }
}

If no root key is provided, Laravex uses a default:

  • public disk → storage/app/public
  • any other disk → storage/app/private

Obtaining a Disk

# Use the default disk
Laravex.Filesystem.Storage.disk()

# Use a specific disk
Laravex.Filesystem.Storage.disk("public")
Laravex.Filesystem.Storage.disk("local")

The returned map contains :name, :root, and :cfg keys and is used internally. You typically don't need to work with it directly — pass the disk name as the last argument to storage functions instead.


Reading and Writing Files

# Write a file (creates parent directories automatically)
Laravex.Filesystem.Storage.put("images/avatar.png", binary_content)

# Write to a specific disk
Laravex.Filesystem.Storage.put("images/avatar.png", binary_content, "public")

# Write with explicit visibility
Laravex.Filesystem.Storage.put("reports/secret.pdf", pdf_data, "local",
  visibility: "private"
)

# Read a file (raises on missing file)
contents = Laravex.Filesystem.Storage.get("images/avatar.png", "public")

# Check existence
Laravex.Filesystem.Storage.exists?("images/avatar.png", "public")
# => true | false

File Visibility

Laravex supports "public" and "private" visibility. For the local driver, "private" applies a 0o600 file mode as a best-effort permission.

# Write a file and mark it private
Laravex.Filesystem.Storage.put("exports/data.csv", csv, "local", visibility: "private")

Visibility can also be set at the disk level in config ("visibility" => "public"), in which case every file written to that disk inherits that visibility unless overridden per-call.


Other File Operations

# Delete a file
Laravex.Filesystem.Storage.delete("old-report.pdf", "local")

# Get a file's size in bytes
Laravex.Filesystem.Storage.size("images/avatar.png", "public")

# Copy a file within a disk
Laravex.Filesystem.Storage.copy("original.png", "backup.png", "public")

# Move / rename a file within a disk
Laravex.Filesystem.Storage.move("temp/upload.png", "images/avatar.png", "public")

# List files in a directory (non-recursive, returns relative paths)
Laravex.Filesystem.Storage.files("images", "public")
# => ["images/avatar.png", "images/banner.jpg"]

# Delete a directory and its contents
Laravex.Filesystem.Storage.delete_directory("temp", "public")

# Get the absolute filesystem path for a file
Laravex.Filesystem.Storage.path("images/avatar.png", "public")
# => "/var/www/app/storage/app/public/images/avatar.png"

Storing Uploaded Files

When handling a file upload, pass the %Laravex.Http.UploadedFile{} struct to store/3 or put_file/3. A random 40-character filename is generated automatically.

# store(file, directory, disk) → returns relative path
path = Laravex.Filesystem.Storage.store(uploaded_file, "avatars", "public")
# => "avatars/wq8Xm3kJn7Yv2Pz0dT6Rl4sCeAbUiOh1Q5fNgK9.png"

# Equivalent helper
path = Laravex.Filesystem.Storage.put_file("avatars", uploaded_file, "public")

File URLs

Generate a URL to a file on the public disk using url/2. The URL is derived from the url key in the disk config, or defaults to /storage/{path}.

url = Laravex.Filesystem.Storage.url("images/avatar.png", "public")
# => "https://example.com/storage/images/avatar.png"
# or "/storage/images/avatar.png" if APP_URL is not set

The storage_url/2 Helpers delegates to this function:

import Laravex.Support.Helpers
storage_url("images/avatar.png")            # uses "public" disk
storage_url("reports/data.csv", "local")

Downloading Files

download/2 reads a file from storage and returns a response that triggers a browser download prompt:

def download(request) do
  Laravex.Filesystem.Storage.download("reports/annual.pdf",
    disk: "local",
    as: "Annual Report 2026.pdf"
  )
end

Options:

Option Description
:disk Disk name to read from (default: default disk)
:as Download filename shown to the browser (default: basename of the path)

Public Disk and storage:link

The public disk is typically made web-accessible by symlinking public/storage → storage/app/public. Run:

./artisan storage:link

The links to create are configured under filesystems.links in your config. The command reads that map and calls File.ln_s!/2 for each pair, removing any existing link first.

After running storage:link, files in storage/app/public are accessible via /storage/{path}.


Asset URL Helper

The asset/1 Helpers builds a URL for a public asset (not a stored file):

import Laravex.Support.Helpers

asset("js/app.js")
# => "https://example.com/js/app.js" (when APP_URL is set)
# => "/js/app.js" (without APP_URL)

Use storage_url/2 for files managed by Storage, and asset/1 for files in the public/ directory.


See Also

Clone this wiki locally