{"id":13507970,"url":"https://github.com/trenpixster/addict","last_synced_at":"2025-10-21T14:48:42.391Z","repository":{"id":25993826,"uuid":"29436169","full_name":"trenpixster/addict","owner":"trenpixster","description":"User management lib for Phoenix Framework","archived":false,"fork":false,"pushed_at":"2019-10-04T20:38:47.000Z","size":345,"stargazers_count":643,"open_issues_count":28,"forks_count":99,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-03-03T13:19:47.563Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trenpixster.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-01-18T18:36:10.000Z","updated_at":"2025-02-05T12:44:03.000Z","dependencies_parsed_at":"2022-08-24T03:00:26.827Z","dependency_job_id":null,"html_url":"https://github.com/trenpixster/addict","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trenpixster%2Faddict","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trenpixster%2Faddict/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trenpixster%2Faddict/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trenpixster%2Faddict/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trenpixster","download_url":"https://codeload.github.com/trenpixster/addict/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246301963,"owners_count":20755512,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T02:00:44.574Z","updated_at":"2025-10-21T14:48:37.355Z","avatar_url":"https://github.com/trenpixster.png","language":"Elixir","funding_links":[],"categories":["Framework Components","Elixir"],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/trenpixster/addict.svg)](https://travis-ci.org/trenpixster/addict) [![Hex.pm](http://img.shields.io/hexpm/v/addict.svg)](https://hex.pm/packages/addict) [![Hex.pm](http://img.shields.io/hexpm/dt/addict.svg)](https://hex.pm/packages/addict)\n[![Deps Status](https://beta.hexfaktor.org/badge/all/github/trenpixster/addict.svg)](https://beta.hexfaktor.org/github/trenpixster/addict)\n[![Inline docs](http://inch-ci.org/github/trenpixster/addict.svg)](http://inch-ci.org/github/trenpixster/addict)\n\n# Addict\n\nAddict allows you to manage users registration and authentication on your [Phoenix Framework](http://www.phoenixframework.org) app easily.\n\n## What does it do?\nFor now, it enables your users to register, login, logout and recover/reset their passwords.\n\n## Requirements\n\nAddict is dependent on an ecto *User* [model](https://github.com/elixir-ecto/ecto/blob/v2.0/examples/friends/lib/friends/person.ex#L4) and a [database connection interface](https://github.com/elixir-ecto/ecto/blob/v2.0/examples/friends/lib/friends/repo.ex#L1).\n\nThe user model must have at least the following schema:\n```elixir\n  field :email, :string\n  field :encrypted_password, :string\n```\n\n## Plug and go\n1 - Add Addict to your dependencies:\n```\n {:addict, \"~\u003e 0.3\"}\n```\n1a - Note that mailgun locks Poison to an old 1.4 version, which may cause conflicts (Poison). There's a fix in place that just hasn't been pushed to hex. Resolve by also adding to your dependencies:\n```\n {:mailgun, github: \"chrismccord/mailgun\", branch: \"master\", override: true}\n```\n2 - Generate Addict [configs](https://github.com/trenpixster/addict/blob/master/configs.md) via:\n```\nmix addict.generate.configs\n```\n3 - Generate ([opinionated](#gen_boilerplate)) boilerplate:\n```\nmix addict.generate.boilerplate\n```\n4 - Add Addict routes to your `router.ex`:\n```elixir\ndefmodule YourApp.Router do\n  (...)\n  use Addict.RoutesHelper\n  (...)\n  scope \"/\" do\n    # Note that the `addict :routes` call should be inside the global\n    # scope rather than your app's scope:\n    # (i.e.: `scope \"/\", YourApp do: ...` vs `scope \"/\", do ...`)\n    # otherwise Phoenix won't be able to find Addict's controllers.\n    addict :routes\n  end\nend\n```\n5 - Visit any of these paths on your app\n```\n/login\n/register\n/recover_password\n/reset_password\n```\n\n## On what does it depend?\nAddict depends on:\n- [Phoenix Framework](http://www.phoenixframework.org)\n- [Ecto](https://github.com/elixir-lang/ecto)\n\nOptionally you can make Addict send e-mails for you too. At the moment only [Mailgun](https://mailgun.com) is supported. Feel free to contribute with [another service](#adding-custom-mailer)!\n\n## Addict Configs\n\nSee all available configurations [here](https://github.com/trenpixster/addict/blob/master/configs.md).\n\n## How can I use it?\n\n### Routes\n\nAdd the following to your `router.ex`:\n\n```elixir\ndefmodule ExampleApp.Router do\n  use Phoenix.Router\n  use Addict.RoutesHelper\n\n  ...\n\n  scope \"/\" do\n    addict :routes\n  end\nend\n```\n\nThis will generate the following routes:\n\n```\n        register_path  POST   / register          Addict.Controller.register/2\n           login_path  POST   / login             Addict.Controller.login/2\n          logout_path  DELETE / logout            Addict.Controller.logout/2\nrecover_password_path  POST   / recover_password  Addict.Controller.recover_password/2\n  reset_password_path  POST   / reset_password    Addict.Controller.reset_password/2\n```\n\nYou can also override the `path` or `controller`/`action` for a given route:\n\n```elixir\naddict :routes,\n  logout: [path: \"/sign-out\", controller: ExampleApp.UserController, action: :sign_out],\n  recover_password: \"/password/recover\",\n  reset_password: \"/password/reset\"\n```\n\nThese overrides will generate the following routes:\n\n```\n        register_path  POST   / register          Addict.Controller.register/2\n           login_path  POST   / login             Addict.Controller.login/2\n          logout_path  DELETE / sign-out          ExampleApp.UserController.sign_out/2\nrecover_password_path  POST   / password/recover  Addict.Controller.recover_password/2\n  reset_password_path  POST   / password/reset    Addict.Controller.reset_password/2\n```\n\n### Interacting with Addict\n\nAfter you've added the router and generated the configs, please take look at the optional boilerplate and the Example App. Here are the interesting bits:\n- [Example AJAX interactions](https://github.com/trenpixster/addict/blob/master/boilerplate/addict.js)\n- [AJAX Error Handling](https://github.com/trenpixster/addict/blob/master/boilerplate/addict.js#L67)\n- [Restricted login path](https://github.com/trenpixster/addict/blob/master/example_app/web/controllers/page_controller.ex#L3)\n- [Login Form](https://github.com/trenpixster/addict/blob/master/boilerplate/login.html.eex)\n\n### Addict Helper\n\nAddict saves information on the logged in user by setting `current_user` on the user's Session.\nYou might want to use the `Addict.Helper` module that encapsulates this logic:\n\n- [`Addict.Helper.current_user/1`](https://hexdocs.pm/addict/Addict.Helper.html#current_user/1): Provided the `conn`, it returns the user model's hash representation, without any associations.\n- [`Addict.Helper.is_logged_in/1`](https://hexdocs.pm/addict/Addict.Helper.html#is_logged_in/1): Provided the `conn`, it returns `true` if the user is logged in, `false` otherwise.\n\n## Checking for authentication\nUse `Addict.Plugs.Authenticated` plug to validate requests on your controllers:\n```elixir\ndefmodule MyAwesomeApp.PageController do\n  use Phoenix.Controller\n\n  plug Addict.Plugs.Authenticated when action in [:foobar]\n  plug :action\n\n  def foobar(conn, _params) do\n    render conn, \"index.html\"\n  end\n\nend\n```\n\nIf the user is not logged in and requests for the above action, they will be redirected to `not_logged_in_url`.\n\n## Adding Custom Mailer\n\nFor adding a custom Mailer just follow the conventions:\n- Module must be `Addict.Mailers.TheEmailProvider`\n- Add the Mailer file in `/lib/addict/mailers`\n- Make sure the mailer implements the behaviour defined [here](https://github.com/trenpixster/addict/blob/master/lib/addict/mailers/generic.ex)\n\nOnce that is done, just set `mail_service` configuration to `:the_email_provider`.\n\n## TODO\nCheck the [issues](https://github.com/trenpixster/addict/issues) on this repository to check or track the ongoing improvements and new features.\n\n## Contributing\n\nFeel free to send your PR with improvements or corrections!\n\nSpecial thanks to the folks at #elixir-lang on freenet for being so helpful every damn time!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrenpixster%2Faddict","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrenpixster%2Faddict","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrenpixster%2Faddict/lists"}