[![Build Status][shield-travis]][travis-ci]
[![Coverage Status][shield-inch]][docs]

> Cleaner request parameters in Elixir web applications 🙌

`BetterParams` is a simple Elixir [Plug][plug] that allows passed
request parameters to be called as `atoms` instead of Strings. The
sole purpose of this Plug is to pattern match on maps with atom keys
instead of string keys in routers/controllers to calm my OCD down.


## Usage

Once installed, it lets you pattern match request parameters like
`%{id: id}` instead of `%{"id" => id}` in Phoenix applications:

# web/controllers/some_controller.ex

def show(conn, %{id: id}) do
  # do something

def create(conn, %{id: id, post: %{title: title, body: body}}) do
  # do something

#### Notes

 - Implementation uses [`String.to_existing_atom`][string-atom] to prevent
   against [DoS attacks][gh-issue-ddos], so it only converts those params
   to atoms that you use in your application.
 - You can continue to use String keys without breaking your existing
   matches if you want. All request parameters are available for both
   `String` and `Atom` keys (that have already been defined in the
 - This doesn't pollute your Request Logs with duplicate params.
 - For other `Plug.Router` based applications, you can also access request
   params similarly by calling them like `conn.params[:id]` or


## Installation

Add `better_params` to your project dependencies in `mix.exs`:

def deps do
  [{:better_params, "~> 0.5.0"}]

### Phoenix Framework

For Phoenix applications, call the plug at the end of the `controller`
method in `web/web.ex` (inside the `quote` block):

# web/web.ex

def controller do
  quote do
    use Phoenix.Controller

    # Other stuff...

    plug BetterParams

Alternatively, you can also call it your Router Pipelines or in
individual controllers directly.

### Other Plug.Router Apps

For other applications using `Plug.Router`, call the Plug anytime after
calling the `:match` and `:dispatch` plugs:

defmodule MyApp.Router do
  use Plug.Router

  plug :match
  plug :dispatch
  plug BetterParams

  # Rest of the router...


### Removing String Keys Entirely

If your use case calls for a params object with _only_ `Atom` keys, you
may pass the option `drop_string_keys` to the plug. Much as it says on
the can, this will replace the `String`-type keys altogether, rather
than preserving them alongside the `Atom` keys.

plug BetterParams, drop_string_keys: true


## Roadmap

 - [x] Write Tests
 - [x] Write Documentation
 - [x] Symbolize the collective `params` map
 - [x] Option to remove string keys entirely
 - [ ] Symbolize [individual parameter maps][plug-params] (if the need arises)
    - [ ] `path_params`
    - [ ] `body_params`
    - [ ] `query_params`


## Contributing

 - [Fork][github-fork], Enhance, Send PR
 - Lock issues with any bugs or feature requests
 - Implement something from Roadmap
 - Spread the word :heart:


## License

This package is available as open source under the terms of the [MIT License][license].