@spec blurhash(t()) :: String.t() | nil

Get the BlurHash string for a media item, or nil if not generated.

Blurhash must be enabled in config and the :image library must be available. The hash is stored in media.responsive_images["blurhash"] after upload.

Use the <PhxMediaLibrary.Components.blurhash> component to render the decoded placeholder client-side.

Examples

iex> Media.blurhash(media)
"LKO2?V%2Tw=w]~RBVZRi};RPxuwH"

iex> Media.blurhash(media_without_hash)
nil

@spec cdn_url(t(), atom() | nil) :: String.t()

Get a CDN-friendly URL with a cache-busting fingerprint query parameter.

Appends ?v={checksum[0..7]} when the media item has a stored checksum, so CDN edges serve a fresh object whenever the file is replaced. Falls back to a plain URL when no checksum is available.

Equivalent to url(media, conversion, cache_bust: true).

Examples

iex> Media.cdn_url(media)
"/uploads/images/1/uuid/photo.jpg?v=a1b2c3d4"

@spec compute_checksum(binary(), String.t()) :: String.t()

Compute a checksum for binary content using the given algorithm.

Supported algorithms: "sha256" (default), "md5", "sha1".

@spec delete(t()) :: :ok | {:ok, t()} | {:error, term()}

Delete a media item.

When soft deletes are enabled (config :phx_media_library, soft_deletes: true), this sets the deleted_at timestamp instead of removing the record and files. Use permanently_delete/1 to force a hard delete.

When soft deletes are disabled (the default), this permanently removes the record and all associated files from storage.

@spec download_url(t(), atom() | nil, keyword()) :: String.t()

Get a download URL that triggers a Content-Disposition: attachment header.

For S3 storage this generates a presigned GET URL with the response-content-disposition query parameter. For local disk storage the URL routes through PhxMediaLibrary.Plug.MediaDownload.

Equivalent to url(media, conversion, download: true).

@spec exclude_trashed(Ecto.Query.t()) :: Ecto.Query.t()

Adds a WHERE deleted_at IS NULL clause to the query when soft deletes are enabled. Returns the query unchanged otherwise.

@spec for_model(Ecto.Schema.t(), atom() | nil) :: [t()]

Query media for a given model, optionally filtered by collection.

By default, soft-deleted records are excluded when soft deletes are enabled. Pass include_trashed: true to include them.

@spec has_conversion?(t(), atom()) :: boolean()

Check if a conversion has been generated.

@spec only_trashed(Ecto.Query.t()) :: Ecto.Query.t()

Adds a WHERE deleted_at IS NOT NULL clause to only return trashed items.

@spec path(t(), atom() | nil) :: String.t() | nil

Get the filesystem path for this media item (local storage only).

@spec permanently_delete(t()) :: :ok | {:error, term()}

Permanently delete a media item and all its files from storage.

This always performs a hard delete regardless of the soft deletes configuration. Use this for:

• Permanently removing soft-deleted items
• Force-deleting when soft deletes are enabled

See also delete/1 which respects the soft deletes configuration.

@spec placeholder(t(), atom() | nil) :: String.t() | nil

Get the tiny placeholder data URI for progressive loading.

@spec restore(t()) :: {:ok, t()} | {:error, Ecto.Changeset.t()}

Restore a soft-deleted media item by clearing deleted_at.

Returns {:ok, media} with the restored record, or {:error, changeset}.

@spec signed_url(t(), atom() | nil, keyword()) :: String.t()

Get a signed, time-limited URL for a media item.

For S3 this is an AWS Signature V4 presigned GET URL. For local disk storage this is an HMAC-signed URL verified by PhxMediaLibrary.Plug.MediaDownload.

Equivalent to url(media, conversion, signed: true).

Options

• :expires_in — seconds until the URL expires (default: 3600).
• :download — also force Content-Disposition: attachment.

@spec soft_delete(t()) :: {:ok, t()} | {:error, Ecto.Changeset.t()}

Soft-delete a media item by setting deleted_at.

When soft deletes are enabled globally (config :phx_media_library, soft_deletes: true), this is called automatically by delete/1 instead of permanently removing the record. Files are not removed from storage until permanently_delete/1 is called.

Returns {:ok, media} with the updated record, or {:error, changeset}.

@spec soft_deletes_enabled?() :: boolean()

Returns whether soft deletes are enabled globally.

@spec srcset(t(), atom() | nil) :: String.t() | nil

Get the srcset attribute value for responsive images.

@spec trashed?(t()) :: boolean()

Check whether a media item has been soft-deleted.

@spec url(t(), atom() | nil, keyword()) :: String.t()

Get the URL for this media item.

Pass opts to forward adapter-specific options such as signed: true, download: true, or cache_bust: true. See PhxMediaLibrary.UrlGenerator for the full list.

@spec verify_integrity(t()) ::
  :ok | {:error, :checksum_mismatch | :no_checksum | term()}

Verify the integrity of a stored media file by comparing its checksum against the stored value.

Returns :ok if the checksums match, {:error, :checksum_mismatch} if they don't, or {:error, :no_checksum} if no checksum was stored.