phoenix_image

defmodule PhoenixImage do
  @moduledoc """
  On-the-fly image resizing for Phoenix with disk caching and responsive components.

  ## Setup

  1. Configure your OTP app:

      ```elixir
      # config/config.exs
      config :phoenix_image, otp_app: :my_app
      ```

  2. Add to your supervision tree:

      ```elixir
      # lib/my_app/application.ex
      children = [
        PhoenixImage,
        MyAppWeb.Endpoint
      ]
      ```

  3. Forward requests in your router:

      ```elixir
      # lib/my_app_web/router.ex
      forward "/images", PhoenixImage.Plug
      ```

  4. Import the component:

      ```elixir
      # lib/my_app_web.ex, in html_helpers/0
      import PhoenixImage.Component
      ```

  ## Configuration

  All options are set via application config:

      config :phoenix_image,
        otp_app: :my_app,            # Required
        prefix: "/images",            # Default: "/images"
        allowed_dims: [64, 96, ...],  # Default: see `allowed_dims/0`
        quality: 90,                  # Default: 90
        source_dir: "priv/static",    # Default: "priv/static"
        cache_dir: "priv/static/cache/images"  # Default: "priv/static/cache/images"
  """

  @default_allowed_dims [64, 96, 100, 150, 192, 200, 288, 300, 400, 600, 800, 900, 1200, 1536]
  @default_quality 90
  @default_prefix "/images"
  @default_source_dir "priv/static"
  @default_cache_dir "priv/static/cache/images"

  @doc """
  Returns a child spec for the `PhoenixImage.Dimensions` GenServer.

  Add `PhoenixImage` to your application's supervision tree to start
  the ETS-backed dimension cache.
  """
  def child_spec(_opts) do
    %{
      id: PhoenixImage.Dimensions,
      start: {PhoenixImage.Dimensions, :start_link, [[]]},
      type: :worker
    }
  end

  @doc """
  Returns the configured OTP app name.

  Raises if `:otp_app` is not configured.
  """
  def otp_app do
    Application.get_env(:phoenix_image, :otp_app) ||
      raise "phoenix_image :otp_app not configured"
  end

  @doc """
  Returns the configured URL prefix. Default: `"/images"`.

  Must match the `forward` path in your router.
  """
  def prefix, do: Application.get_env(:phoenix_image, :prefix, @default_prefix)

  @doc """
  Returns the list of allowed dimension values.

  Default: `#{inspect(@default_allowed_dims)}`

  Requests with dimensions not in this list return a 400 error.
  """
  def allowed_dims, do: Application.get_env(:phoenix_image, :allowed_dims, @default_allowed_dims)

  @doc """
  Returns the JPEG output quality (1-100). Default: `90`.
  """
  def quality, do: Application.get_env(:phoenix_image, :quality, @default_quality)

  @doc """
  Returns the source directory for original images, relative to the OTP app's priv.

  Default: `"priv/static"`.
  """
  def source_dir, do: Application.get_env(:phoenix_image, :source_dir, @default_source_dir)

  @doc """
  Returns the cache directory for resized images, relative to the OTP app's priv.

  Default: `"priv/static/cache/images"`.
  """
  def cache_dir, do: Application.get_env(:phoenix_image, :cache_dir, @default_cache_dir)
end