Generates URLs for media files.

Options

All URL-generating functions accept the following options in addition to any adapter-specific options:

• :cache_bust — boolean — when true and the media item has a stored checksum, appends a ?v={checksum[0..7]} query parameter so that CDN edges serve a fresh object whenever the file changes. Defaults to false.

• :signed — boolean — when true, generates a signed/expiring URL. For S3 this is an AWS Signature V4 presigned GET URL. For local disk this is an HMAC-signed URL that can be verified by PhxMediaLibrary.Plug.MediaDownload. Requires :expires_in (see below). Defaults to false.

• :expires_in — integer — expiry window in seconds for signed URLs (default: 3600). Has no effect unless :signed is true.

• :download — boolean — when true, generates a URL suitable for file downloads. For S3, this attaches a Content-Disposition: attachment response header to the presigned URL. For local disk, the URL routes through PhxMediaLibrary.Plug.MediaDownload which sets the header. Implies :signed for S3 (a presigned URL is required). Defaults to false.

• :filename — String.t() — override the filename used in the Content-Disposition header when :download is true. Defaults to the media item's file_name.

CDN Cache-Busting

When assets are served through a CDN you typically want far-future Cache-Control headers and a content-fingerprint in the URL so the CDN picks up the new asset when you replace a file.

# Regular URL
PhxMediaLibrary.url(media)
#=> "/uploads/images/42/abc/photo.jpg"

# CDN URL with cache-busting checksum
PhxMediaLibrary.cdn_url(media)
#=> "/uploads/images/42/abc/photo.jpg?v=a1b2c3d4"

# Explicit option form
PhxMediaLibrary.url(media, nil, cache_bust: true)
#=> "/uploads/images/42/abc/photo.jpg?v=a1b2c3d4"

Signed / Expiring URLs

For S3 (already supported by the adapter):

PhxMediaLibrary.signed_url(media)
#=> "https://bucket.s3.amazonaws.com/...?X-Amz-Signature=..."

PhxMediaLibrary.signed_url(media, nil, expires_in: 300)

For local disk storage (requires PhxMediaLibrary.Plug.MediaDownload to be mounted in the app's router):

# router.ex
forward "/media", PhxMediaLibrary.Plug.MediaDownload, disk: :local

# config.exs
config :phx_media_library,
  disks: [
    local: [
      adapter: PhxMediaLibrary.Storage.Disk,
      root: "priv/static/uploads",
      base_url: "/uploads",
      download_base_url: "/media",
      secret_key_base: "long-random-secret"
    ]
  ]

Download Links

For S3, this generates a presigned URL with response-content-disposition:

PhxMediaLibrary.download_url(media)
#=> "https://bucket.s3.amazonaws.com/...?response-content-disposition=attachment..."

For local disk, the URL routes through PhxMediaLibrary.Plug.MediaDownload which serves the file with Content-Disposition: attachment.