# `Image.Plug.Provider.Imgix.URL`
[🔗](https://github.com/elixir-image/image_plug/blob/v0.1.0/lib/image/plug/provider/imgix/url.ex#L1)

URL-shape recognition for the [imgix URL grammar](https://docs.imgix.com/en/latest/setup/serving-images).

Two source modes per imgix's documentation:

* **Web folder source**: the path *is* the source key
  (`/photos/sunset.jpg`). The host's `Image.Plug.SourceResolver`
  (typically `File` or `Hosted`) maps the path to bytes.

* **Web proxy source**: the path is a percent-encoded absolute
  URL (`/https%3A%2F%2Fassets.example.com%2Fsunset.jpg`).
  Treated as a `:url` source; resolved by
  `Image.Plug.SourceResolver.HTTP`.

Unlike Cloudflare, imgix has no path marker — every request
under the configured mount is presumed to be a transform request.
Options come from the query string, not the path.

# `recognised`

```elixir
@type recognised() :: %{
  shape: :imgix,
  options: String.t(),
  source: Image.Plug.Source.t()
}
```

The recognised URL shape.

# `parse`

```elixir
@spec parse(
  Plug.Conn.t(),
  keyword()
) :: {:ok, recognised()} | {:error, Image.Plug.Error.t()}
```

Parses the request path of a `Plug.Conn` into a recognised URL
shape.

### Arguments

* `conn` is a `Plug.Conn` struct.

* `options` is a keyword list. The following keys are honoured:

### Options

* `:mount` — string path prefix the plug is mounted under.
  Stripped before treating the rest as the source path. Defaults
  to `""`.

### Returns

* `{:ok, recognised}` on a successful match.

* `{:error, %Image.Plug.Error{tag: :malformed_url}}` when the
  path does not sit under the configured mount.

* `{:error, %Image.Plug.Error{tag: :invalid_option}}` when the
  decoded source is malformed (e.g. relative path, unparseable
  URL).

### Examples

    iex> conn = %Plug.Conn{
    ...>   path_info: ["photos", "sunset.jpg"],
    ...>   request_path: "/photos/sunset.jpg",
    ...>   query_string: "w=200&fit=crop"
    ...> }
    iex> {:ok, %{shape: :imgix, options: "w=200&fit=crop", source: source}} =
    ...>   Image.Plug.Provider.Imgix.URL.parse(conn, [])
    iex> source.kind
    :path
    iex> source.ref
    "/photos/sunset.jpg"

---

*Consult [api-reference.md](api-reference.md) for complete listing*