waffle

# Waffle

<img align="right" width="160" alt="Waffle logo" src="https://elixir-waffle.github.io/waffle/assets/logo.svg">

Waffle is a flexible file upload library for Elixir with straightforward integrations for Amazon S3 and ImageMagick.

[Documentation](https://waffle.hexdocs.pm/readme.html)
 · [Hex](https://hex.pm/packages/waffle)

[Presentation at ElixirConf](https://www.youtube.com/watch?v=4iM-V9yELsE)
 · [Thinking Elixir Podcast 80](https://podcast.thinkingelixir.com/80)

---

Already using Waffle in your org? I'd love to learn more. Let's [have a chat](https://cal.com/achempion/meet) or just [send me an email](mailto:me@achempion.com?subject=Feedback%20on%20Waffle).

---

## Why use Waffle?

You want to apply file transformations, manage access rules, save files, or process files asynchronously.

## Quick start

Add the `:waffle` dependency to `mix.exs`.

**mix.exs**
```elixir
{:waffle, "~> 2.0"},
{:waffle_ecto, "~> 0.0"}
```

Configure file storage

```elixir
config :waffle, storage: Waffle.Storage.Local
```

_Read more about [storage configuration](https://waffle.hexdocs.pm/Waffle.Definition.Storage.html) and the supported adapters (including S3)._

Create an uploader module with `mix waffle.g avatar`

```elixir
defmodule MyApp.Avatar do
  use Waffle.Definition
  use Waffle.Ecto.Definition

  def storage_dir(_version, {_file, user}) do
    "users/#{user.id}/avatar/"
  end
end
```

Update the user schema

```elixir
schema "users" do
  field :avatar, Avatar.Type
end
```

Cast the file payload with a changeset

```elixir
changeset
|> cast_attachments(
  params,
  [:avatar],
  allow_paths: true,
  allow_urls: true
)
```

_Read more about Ecto integration in the [WaffleEcto documentation](https://waffle-ecto.hexdocs.pm/)._
_WaffleEcto supports changeset integration and versioned URLs for cache busting._

Check out [`Waffle.LiveView`](https://hexdocs.pm/waffle/Waffle.LiveView.html) on how to integrate Waffle with LiveView uploads.

## More Examples

* [An example for the Local storage driver](documentation/examples/local.md)
* [An example for the S3 storage driver](documentation/examples/s3.md)

## Attribution

This library was forked from [Arc](https://github.com/stavro/arc) at version `v0.11.0`. Special thanks to Sean Stavropoulos ([@stavro](https://github.com/stavro)) for creating Arc.

## Sponsors

- [Evrone](https://evrone.com?utm_source=waffle), custom software development company
- [Oficinaria](https://oficinaria.com.br?utm_source=waffle), marketplace for in-person creative workshops in Brazil
- [Tecotype](https://tecotype.com?utm_source=waffle), keyboard-first mail app

## License

Copyright 2019 Boris Kuznetsov <me@achempion.com>

Copyright 2015 Sean Stavropoulos

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to