\n \n\n```\n\n`` is a function component defined inside `lib/hello_web/components/layouts.ex`. If you open the file up, you will find:\n\n```elixir\n def app(assigns) do\n ~H\"\"\"\n \n ...\n```\n\nSo far, all of the function components we have defined also worked as templates. Let's learn more about them by defining our own component with the intent of encapsulating some HTML markup.\n\nImagine we want to refactor our `show.html.heex` to move the rendering of `
Hello World, from {@messenger}!
` to its own function. Remember that `show.html.heex` is embedded within the `HelloHTML` module. Let's open it up:\n\n```elixir\ndefmodule HelloWeb.HelloHTML do\n use HelloWeb, :html\n\n embed_templates \"hello_html/*\"\nend\n```\n\nThat's simple enough. There's only two lines, `use HelloWeb, :html`. This line calls the `html/0` function defined in `HelloWeb` which sets up the basic imports and configuration for our function components and templates. All of the imports and aliases in our module will also be available in our templates. Similarly, if we want to write a function component to be invoked from `show.html.heex`, we can simply add it to `HelloHTML`. Let's do so:\n\n```elixir\ndefmodule HelloWeb.HelloHTML do\n use HelloWeb, :html\n\n embed_templates \"hello_html/*\"\n\n attr :messenger, :string, required: true\n\n def greet(assigns) do\n ~H\"\"\"\n
Hello World, from {@messenger}!
\n \"\"\"\n end\nend\n```\n\nWe declared the attributes we accept via the [`Phoenix.Component.attr/3`](https://hexdocs.pm/phoenix_live_view/Phoenix.Component.html#attr/3) macro, then we defined our `greet/1` function which returns the HEEx template.\n\nNext we need to update `show.html.heex`:\n\n```heex\n\n \n <.greet messenger={@messenger} />\n \n\n```\n\nWhen we reload `http://localhost:4000/hello/Frank`, we should see the same content as before! The `show.html.heex` is now invoking two different function components:\n\n * ``. If the component was defined elsewhere, we would need to give its full name, such as: ``.\n\nBy declaring attributes as required, Phoenix will warn if we call the `<.greet />` component without passing attributes. If an attribute is optional, you can specify the `:default` option with a value:\n\n```\nattr :messenger, :string, default: nil\n```\n\nOverall, function components are the essential building block of Phoenix rendering stack. Next, let's fully understand the expressive power behind the HEEx template language.\n\n## HEEx\n\nFunction components and templates files are powered by [the HEEx template language](https://hexdocs.pm/phoenix_live_view/Phoenix.Component.html#sigil_H/2), which stands for \"HTML + Embedded Elixir\". We can write Elixir code inside `{...}` for HTML-aware interpolation inside tag attributes and the body, as done above. For example, we use `@name` to access the key `name` defined inside `assigns`.\n\nWe can also interpolate arbitrary HEEx blocks using `<%= ... %>`. This is often used for block constructs. For example, in order to have conditionals:\n\n```heex\n<%= if some_condition? do %>\n
Some condition is true for user: {@messenger}
\n<% else %>\n
Some condition is false for user: {@messenger}
\n<% end %>\n```\n\nor even loops:\n\n```heex\n
\n
\n
Number
\n
Power
\n
\n <%= for number <- 1..10 do %>\n
\n
{number}
\n
{number * number}
\n
\n <% end %>\n
\n```\n\nHEEx also comes with handy HTML extensions we will learn next.\n\n### HTML extensions\n\nBesides allowing interpolation of Elixir expressions, `.heex` templates come with HTML-aware extensions. For example, let's see what happens if you try to interpolate a value with \"<\" or \">\" in it, which would lead to HTML injection:\n\n```heex\n{\"Bold?\"}\n```\n\nOnce you render the template, you will see the literal `` on the page. This means users cannot inject HTML content on the page. If you want to allow them to do so, you can call `raw`, but do so with extreme care:\n\n```heex\n{raw(\"Bold?\")}\n```\n\nAnother super power of HEEx templates is validation of HTML and interpolation syntax of attributes. You can write:\n\n```heex\n
\n
Hello {@username}
\n
\n```\n\nNotice how you could simply use `key={value}`. HEEx will automatically handle special values such as `false` to remove the attribute or a list of classes.\n\nTo interpolate a dynamic number of attributes in a keyword list or map, do:\n\n```heex\n
\n
Hello {@username}
\n
\n```\n\nAlso, try removing the closing `` or renaming it to ``. HEEx templates will let you know about your error.\n\nHEEx also supports shorthand syntax for `if` and `for` expressions via the special `:if` and `:for` attributes. For example, rather than this:\n\n```heex\n<%= if @some_condition do %>\n
...
\n<% end %>\n```\n\nYou can write:\n\n```heex\n
...
\n```\n\nLikewise, for comprehensions may be written as:\n\n```heex\n
\n
{item.name}
\n
\n```\n\n## CoreComponents\n\nIn a new Phoenix application, you will also find a `core_components.ex` module inside the `components` folder. This module is a great example of defining function components to be reused throughout our application. This guarantees that, as our application evolves, our components will look consistent.\n\nIf you look inside `def html` in `HelloWeb` placed at `lib/hello_web.ex`, you will see that `CoreComponents` are automatically imported into all HTML views via `use HelloWeb, :html`. This is also the reason why `CoreComponents` itself performs `use Phoenix.Component` instead of `use HelloWeb, :html` at the top: doing the latter would cause a deadlock as we would try to import `CoreComponents` into itself.\n\nCoreComponents also play an important role in Phoenix code generators, as the code generators assume those components are available in order to quickly scaffold your application. In case you want to learn more about all of these pieces, you may:\n\n * Explore the generated `CoreComponents` module to learn more from practical examples\n\n * Read the official documentation for [`Phoenix.Component`](https://hexdocs.pm/phoenix_live_view/Phoenix.Component.html)\n\n * Read the official documentation for [HEEx and the ~H sigils](https://hexdocs.pm/phoenix_live_view/Phoenix.Component.html#sigil_H/2)\n\n * If you are looking for higher level components beyond the minimal ones included by Phoenix, [the LiveView project keeps a list of component systems](https://github.com/phoenixframework/phoenix_live_view#component-systems)\n\n## Layouts\n\nWhen talking about components and rendering in Phoenix, it is important to understand the concept of layouts.\n\nAll Phoenix applications have one component called the \"root layout\". This page is where you will find the `` and `` tags of your HTML page. The root layout is configured in your `lib/hello_web/router.ex` file:\n\n```elixir\n plug :put_root_layout, html: {HelloWeb.Layouts, :root}\n```\n\nIn a newly generated app, the template itself can be found at `lib/hello_web/components/layouts/root.html.heex`. Open it up and, just about at the end of the ``, you will see this:\n\n```heex\n{@inner_content}\n```\n\nThat's where our templates are injected once they are rendered. The root layout is reused by controllers and live views alike.\n\nAny dynamic functionality of your application is then implemented as function components. For example, your application menu and sidebar is typically part of the `app` component in `lib/hello_web/components/layouts.ex`, which is invoked in every template:\n\n```heex\n\n ...\n\n```\n\nThis mechanism is also very flexible. For example, if you want to create an admin layout, you can simply add a new function in the `Layouts` module, and then invoke `Layouts.admin` instead of `Layouts.app`:\n\n```heex\n\n ...\n\n```\n\n> Previous Phoenix versions used a nested layout mechanism, by passing the `:layouts` to `Phoenix.Controller` and `:layout` to `Phoenix.LiveView`, but this mechanism is discouraged in new Phoenix applications.\n"
},
{
"path": "guides/controllers.md",
"content": "# Controllers\n\n> **Requirement**: This guide expects that you have gone through the [introductory guides](installation.html) and got a Phoenix application [up and running](up_and_running.html).\n\n> **Requirement**: This guide expects that you have gone through the [request life-cycle guide](request_lifecycle.html).\n\nPhoenix controllers act as intermediary modules. Their functions — called actions — are invoked from the router in response to HTTP requests. The actions, in turn, gather all the necessary data and perform all the necessary steps before invoking the view layer to render a template or returning a JSON response.\n\nPhoenix controllers also build on the Plug package, and are themselves plugs. Controllers provide the functions to do almost anything we need to in an action. If we do find ourselves looking for something that Phoenix controllers don't provide, we might find what we're looking for in Plug itself. Please see the [Plug guide](plug.html) or the [Plug documentation](`Plug`) for more information.\n\nA newly generated Phoenix app will have a single controller named `PageController`, which can be found at `lib/hello_web/controllers/page_controller.ex` which looks like this:\n\n```elixir\ndefmodule HelloWeb.PageController do\n use HelloWeb, :controller\n\n def home(conn, _params) do\n render(conn, :home)\n end\nend\n```\n\nThe first line below the module definition invokes the `__using__/1` macro of the `HelloWeb` module, which imports some useful modules.\n\n`PageController` gives us the `home` action to display the Phoenix [welcome page] associated with the default route Phoenix defines in the router.\n\n## Actions\n\nController actions are just functions. We can name them anything we like as long as they follow Elixir's naming rules. The only requirement we must fulfill is that the action name matches a route defined in the router.\n\nFor example, in `lib/hello_web/router.ex` we could change the action name in the default route that Phoenix gives us in a new app from `home`:\n\n```elixir\nget \"/\", PageController, :home\n```\n\nto `index`:\n\n```elixir\nget \"/\", PageController, :index\n```\n\nas long as we change the action name in `PageController` to `index` as well, the [welcome page] will load as before.\n\n```elixir\ndefmodule HelloWeb.PageController do\n ...\n\n def index(conn, _params) do\n render(conn, :home)\n end\nend\n```\n\nWhile we can name our actions whatever we like, there are conventions for action names which we should follow whenever possible. We went over these in the [routing guide](routing.html), but we'll take another quick look here.\n\n- index - renders a list of all items of the given resource type\n- show - renders an individual item by ID\n- new - renders a form for creating a new item\n- create - receives parameters for one new item and saves it in a data store\n- edit - retrieves an individual item by ID and displays it in a form for editing\n- update - receives parameters for one edited item and saves the item to a data store\n- delete - receives an ID for an item to be deleted and deletes it from a data store\n\nEach of these actions takes two parameters, which will be provided by Phoenix behind the scenes.\n\nThe first parameter is always `conn`, a struct which holds information about the request such as the host, path elements, port, query string, and much more. `conn` comes to Phoenix via Elixir's Plug middleware framework. More detailed information about `conn` can be found in the [Plug.Conn documentation](`Plug.Conn`).\n\nThe second parameter is `params`. Not surprisingly, this is a map which holds any parameters passed along in the HTTP request. It is a good practice to pattern match against parameters in the function signature to provide data in a simple package we can pass on to rendering. We saw this in the [request life-cycle guide](request_lifecycle.html) when we added a messenger parameter to our `show` route in `lib/hello_web/controllers/hello_controller.ex`.\n\n```elixir\ndefmodule HelloWeb.HelloController do\n ...\n\n def show(conn, %{\"messenger\" => messenger}) do\n render(conn, :show, messenger: messenger)\n end\nend\n```\n\nIn some cases — often in `index` actions, for instance — we don't care about parameters because our behavior doesn't depend on them. In those cases, we don't use the incoming parameters, and simply prefix the variable name with an underscore, calling it `_params`. This will keep the compiler from complaining about the unused variable while still keeping the correct arity.\n\n## Rendering\n\nControllers can render content in several ways. The simplest is to render some plain text using the [`text/2`] function which Phoenix provides.\n\nFor example, let's rewrite the `show` action from `HelloController` to return text instead. For that, we could do the following.\n\n```elixir\ndef show(conn, %{\"messenger\" => messenger}) do\n text(conn, \"From messenger #{messenger}\")\nend\n```\n\nNow [`/hello/Frank`] in your browser should display `From messenger Frank` as plain text without any HTML.\n\nA step beyond this is rendering pure JSON with the [`json/2`] function. We need to pass it something that the [Jason library](`Jason`) can decode into JSON, such as a map. (Jason is one of Phoenix's dependencies.)\n\n```elixir\ndef show(conn, %{\"messenger\" => messenger}) do\n json(conn, %{id: messenger})\nend\n```\n\nIf we again visit [`/hello/Frank`] in the browser, we should see a block of JSON with the key `id` mapped to the string `\"Frank\"`.\n\n```json\n{\"id\": \"Frank\"}\n```\n\nThe [`json/2`] function is useful for writing APIs and there is also the [`html/2`] function for rendering HTML, but most of the times we use Phoenix views to build our responses. For this, Phoenix includes the [`render/3`] function. It is specially important for HTML responses, as Phoenix Views provide performance and security benefits.\n\nLet's rollback our `show` action to what we originally wrote in the [request life-cycle guide](request_lifecycle.html):\n\n```elixir\ndefmodule HelloWeb.HelloController do\n use HelloWeb, :controller\n\n def show(conn, %{\"messenger\" => messenger}) do\n render(conn, :show, messenger: messenger)\n end\nend\n```\n\nIn order for the [`render/3`] function to work correctly, the controller and view must share the same root name (in this case `Hello`), and the `HelloHTML` module must include an `embed_templates` definition specifying where its templates live. By default the controller, view module, and templates are collocated together in the same controller directory. In other words, `HelloController` requires `HelloHTML`, and `HelloHTML` requires the existence of the `lib/hello_web/controllers/hello_html/` directory, which must contain the `show.html.heex` template.\n\n[`render/3`] will also pass the value which the `show` action received for `messenger` from the parameters as an assign.\n\nIf we need to pass values into the template when using `render`, that's easy. We can pass a keyword like we've seen with `messenger: messenger`, or we can use `Plug.Conn.assign/3`, which conveniently returns `conn`.\n\n```elixir\n def show(conn, %{\"messenger\" => messenger}) do\n conn\n |> Plug.Conn.assign(:messenger, messenger)\n |> render(:show)\n end\n```\n\nNote: Using `Phoenix.Controller` imports `Plug.Conn`, so shortening the call to [`assign/3`] works just fine.\n\nPassing more than one value to our template is as simple as connecting [`assign/3`] functions together:\n\n```elixir\n def show(conn, %{\"messenger\" => messenger}) do\n conn\n |> assign(:messenger, messenger)\n |> assign(:receiver, \"Dweezil\")\n |> render(:show)\n end\n```\n\nOr you can pass the assigns directly to `render` instead:\n\n```elixir\n def show(conn, %{\"messenger\" => messenger}) do\n render(conn, :show, messenger: messenger, receiver: \"Dweezil\")\n end\n```\n\nGenerally speaking, once all assigns are configured, we invoke the view layer. The view layer (`HelloWeb.HelloHTML`) then renders `show.html` alongside the layout and a response is sent back to the browser.\n\n## New rendering formats\n\nRendering HTML through a template is fine, but what if we need to change the rendering format on the fly? Let's say that sometimes we need HTML, sometimes we need plain text, and sometimes we need JSON. Then what?\n\nThe view's job is not only to render HTML templates. Views are about data presentation. Given a bag of data, the view's purpose is to present that in a meaningful way given some format, be it HTML, JSON, CSV, or others. Many web apps today return JSON to remote clients, and Phoenix views are *great* for JSON rendering.\n\nAs an example, let's take `PageController`'s `home` action from a newly generated app. Out of the box, this has the right view `PageHTML`, the embedded templates from (`lib/hello_web/controllers/page_html`), and the right template for rendering HTML (`home.html.heex`.)\n\n```elixir\ndef home(conn, _params) do\n render(conn, :home)\nend\n```\n\nWhat it doesn't have is a view for rendering JSON. Phoenix Controller hands off to a view module to render templates, and it does so per format. We already have a view for the HTML format, but we need to instruct Phoenix how to render the JSON format as well. By default, you can see which formats your controllers support in `lib/hello_web.ex`:\n\n```elixir\n def controller do\n quote do\n use Phoenix.Controller,\n formats: [:html, :json]\n ...\n end\n end\n```\n\nSo out of the box Phoenix will look for a `HTML` and `JSON` view modules based on the request format and the controller name. We can also explicitly tell Phoenix in our controller which view(s) to use for each format. For example, what Phoenix does by default can be explicitly set with the following in your controller:\n\n```elixir\nplug :put_view, html: HelloWeb.PageHTML, json: HelloWeb.PageJSON\n```\n\nLet's add a `PageJSON` view module at `lib/hello_web/controllers/page_json.ex`:\n\n```elixir\ndefmodule HelloWeb.PageJSON do\n def home(_assigns) do\n %{message: \"this is some JSON\"}\n end\nend\n```\n\nSince the Phoenix View layer is simply a function that the controller renders, passing connection assigns, we can define a regular `home/1` function and return a map to be serialized as JSON.\n\nThere are just a few more things we need to do to make this work. Because we want to render both HTML and JSON from the same controller, we need to tell our router that it should accept the `json` format. We do that by adding `json` to the list of accepted formats in the `:browser` pipeline. Let's open up `lib/hello_web/router.ex` and change `plug :accepts` to include `json` as well as `html` like this.\n\n```elixir\ndefmodule HelloWeb.Router do\n use HelloWeb, :router\n\n pipeline :browser do\n plug :accepts, [\"html\", \"json\"]\n plug :fetch_session\n plug :fetch_live_flash\n plug :put_root_layout, html: {HelloWeb.LayoutView, :root}\n plug :protect_from_forgery\n plug :put_secure_browser_headers\n end\n...\n```\n\nPhoenix allows us to change formats on the fly with the `_format` query string parameter. If we go to [`http://localhost:4000/?_format=json`](http://localhost:4000/?_format=json), we will see `%{\"message\": \"this is some JSON\"}`.\n\nIn practice, however, applications that need to render both formats typically use two distinct pipelines for each, such as the `pipeline :api` already defined in your router file. To learn more, see [our JSON and APIs guide](json_and_apis.md).\n\n### Sending responses directly\n\nIf none of the rendering options above quite fits our needs, we can compose our own using some of the functions that `Plug` gives us. Let's say we want to send a response with a status of \"201\" and no body whatsoever. We can do that with the `Plug.Conn.send_resp/3` function.\n\nEdit the `home` action of `PageController` in `lib/hello_web/controllers/page_controller.ex` to look like this:\n\n```elixir\ndef home(conn, _params) do\n send_resp(conn, 201, \"\")\nend\n```\n\nReloading [http://localhost:4000](http://localhost:4000) should show us a completely blank page. The network tab of our browser's developer tools should show a response status of \"201\" (Created). Some browsers (Safari) will download the response, as the content type is not set.\n\nTo be specific about the content type, we can use [`put_resp_content_type/2`] in conjunction with [`send_resp/3`].\n\n```elixir\ndef home(conn, _params) do\n conn\n |> put_resp_content_type(\"text/plain\")\n |> send_resp(201, \"\")\nend\n```\n\nUsing `Plug` functions in this way, we can craft just the response we need.\n\n### Setting the content type\n\nAnalogous to the `_format` query string param, we can render any sort of format we want by modifying the HTTP Content-Type Header and providing the appropriate template.\n\nIf we wanted to render an XML version of our `home` action, we might implement the action like this in `lib/hello_web/controllers/page_controller.ex`.\n\n```elixir\ndef home(conn, _params) do\n conn\n |> put_resp_content_type(\"text/xml\")\n |> put_format(:xml)\n |> render(:home, content: some_xml_content)\nend\n```\n\nThen we would need to provide a `home.xml.eex` template that creates XML and a `PageXML` view that embeds the template, and that would be it.\n\nNote: The `home.xml.eex` template uses the `.eex` extension. `.eex` templates are rendered by [`EEx`](https://hexdocs.pm/eex/main/EEx.html).\n\nFor a list of valid content mime-types, please see the `MIME` library.\n\n### Setting the HTTP Status\n\nWe can also set the HTTP status code of a response similarly to the way we set the content type. The `Plug.Conn` module, imported into all controllers, has a `put_status/2` function to do this.\n\n`Plug.Conn.put_status/2` takes `conn` as the first parameter and as the second parameter either an integer or a \"friendly name\" used as an atom for the status code we want to set. The list of status code atom representations can be found in `Plug.Conn.Status.code/1` documentation.\n\nLet's change the status in our `PageController` `home` action.\n\n```elixir\ndef home(conn, _params) do\n conn\n |> put_status(202)\n |> render(:home)\nend\n```\n\nThe status code we provide must be a valid number.\n\n## Redirection\n\nOften, we need to redirect to a new URL in the middle of a request. A successful `create` action, for instance, will usually redirect to the `show` action for the resource we just created. Alternately, it could redirect to the `index` action to show all the things of that same type. There are plenty of other cases where redirection is useful as well.\n\nWhatever the circumstance, Phoenix controllers provide the handy [`redirect/2`] function to make redirection easy. Phoenix differentiates between redirecting to a path within the application and redirecting to a URL — either within our application or external to it.\n\nIn order to try out [`redirect/2`], let's create a new route in `lib/hello_web/router.ex`.\n\n```elixir\ndefmodule HelloWeb.Router do\n ...\n\n scope \"/\", HelloWeb do\n ...\n get \"/\", PageController, :home\n get \"/redirect_test\", PageController, :redirect_test\n ...\n end\nend\n```\n\nThen we'll change `PageController`'s `home` action of our controller to do nothing but to redirect to our new route.\n\n```elixir\ndefmodule HelloWeb.PageController do\n use HelloWeb, :controller\n\n def home(conn, _params) do\n redirect(conn, to: ~p\"/redirect_test\")\n end\nend\n\n```\n\nWe made use of `Phoenix.VerifiedRoutes.sigil_p/2` to build our redirect path, which is the preferred approach to reference any path within our application. We learned about verified routes in the [routing guide](routing.html).\n\nFinally, let's define in the same file the action we redirect to, which simply renders the home, but now under a new address:\n\n```elixir\ndef redirect_test(conn, _params) do\n render(conn, :home)\nend\n```\n\nWhen we reload our [welcome page], we see that we've been redirected to `/redirect_test` which shows the original welcome page. It works!\n\nIf we care to, we can open up our developer tools, click on the network tab, and visit our root route again. We see two main requests for this page - a get to `/` with a status of `302`, and a get to `/redirect_test` with a status of `200`.\n\nNotice that the redirect function takes `conn` as well as a string representing a relative path within our application. For security reasons, the `:to` option can only redirect to paths within your application. If you want to redirect to a fully-qualified path or an external URL, you should use `:external` instead:\n\n```elixir\ndef home(conn, _params) do\n redirect(conn, external: \"https://elixir-lang.org/\")\nend\n```\n\n## Flash messages\n\nSometimes we need to communicate with users during the course of an action. Maybe there was an error updating a schema, or maybe we just want to welcome them back to the application. For this, we have flash messages.\n\nThe `Phoenix.Controller` module provides the [`put_flash/3`] to set flash messages as a key-value pair and placing them into a `@flash` assign in the connection. Let's set two flash messages in our `HelloWeb.PageController` to try this out.\n\nTo do this we modify the `home` action as follows:\n\n```elixir\ndefmodule HelloWeb.PageController do\n ...\n def home(conn, _params) do\n conn\n |> put_flash(:error, \"Let's pretend we have an error.\")\n |> render(:home)\n end\nend\n```\n\nIn order to see our flash messages, we need to be able to retrieve them and display them in a template layout. We can do that using [`Phoenix.Flash.get/2`] which takes the flash data and the key we care about. It then returns the value for that key.\n\nFor our convenience, a `flash_group` component is already available and added to the beginning of our [welcome page]\n\n```heex\n<.flash_group flash={@flash} />\n```\n\nWhen we reload the [welcome page], our message should appear in the top right corner of the page.\n\nThe flash functionality is handy when mixed with redirects. Perhaps you want to redirect to a page with some extra information. If we reuse the redirect action from the previous section, we can do:\n\n```elixir\n def home(conn, _params) do\n conn\n |> put_flash(:error, \"Let's pretend we have an error.\")\n |> redirect(to: ~p\"/redirect_test\")\n end\n```\n\nNow if you reload the [welcome page], you will be redirected and the flash message will be shown once more.\n\nBesides [`put_flash/3`], the `Phoenix.Controller` module has another useful function worth knowing about. [`clear_flash/1`] takes only `conn` and removes any flash messages which might be stored in the session.\n\nPhoenix does not enforce which keys are stored in the flash. As long as we are internally consistent, all will be well. `:info` and `:error`, however, are common and are handled by default in our templates.\n\n## Error pages\n\nPhoenix has two views called `ErrorHTML` and `ErrorJSON` which live in `lib/hello_web/controllers/`. The purpose of these views is to handle errors in a general way for incoming HTML or JSON requests. Similar to the views we built in this guide, error views can return both HTML and JSON responses. See the [Custom Error Pages How-To](custom_error_pages.html) for more information.\n\n[`render/4`]: `Phoenix.Template.render/4`\n[`/hello/Frank`]: http://localhost:4000/hello/Frank\n[`assign/3`]: `Plug.Conn.assign/3`\n[`clear_flash/1`]: `Phoenix.Controller.clear_flash/1`\n[`Phoenix.Flash.get/2`]: `Phoenix.Flash.get/2`\n[`html/2`]: `Phoenix.Controller.html/2`\n[`json/2`]: `Phoenix.Controller.json/2`\n[`put_flash/3`]: `Phoenix.Controller.put_flash/3`\n[`put_resp_content_type/2`]: `Plug.Conn.put_resp_content_type/2`\n[`put_root_layout/2`]: `Phoenix.Controller.put_root_layout/2`\n[`redirect/2`]: `Phoenix.Controller.redirect/2`\n[`render/3`]: `Phoenix.Controller.render/3`\n[`send_resp/3`]: `Plug.Conn.send_resp/3`\n[`text/2`]: `Phoenix.Controller.text/2`\n[welcome page]: http://localhost:4000/\n"
},
{
"path": "guides/data_modelling/contexts.md",
"content": "# 1. Intro to Contexts\n\nPhoenix guides are broken into several major sections. The main building blocks are outlined under the \"Core Concepts\" section, where we explored [the request life-cycle](request_lifecycle.html), wired up controller actions through our routers, and learned how Ecto allows data to be validated and persisted. Now it's time to tie it all together by writing web-facing features that interact with our greater Elixir application.\n\nWhen building a Phoenix project, we are first and foremost building an Elixir application. Phoenix's job is to provide a web interface into our Elixir application. Naturally, we compose our applications with modules and functions, but we often assign specific responsibilities to certain modules and give them names: such as controllers, routers, and live views.\n\nHowever, the most important part of your web application is often where we encapsulate data access and data validation. We call these modules **contexts**. They often talk to a database, using `Ecto`, or APIs, using an HTTP client such as `Req`. By giving these modules a name, we help developers identify these patterns and talk about them. At the end of the day, contexts are just modules, as are your controllers, views, etc.\n\nIf you have used `mix phx.gen.html`, `mix phx.gen.json`, or `mix phx.gen.live`, you have already used contexts. For example, run the following generator in a Phoenix application:\n\n```console\n$ mix phx.gen.live Post posts title body:text\n```\n\nThe command above will output a few files, among them, a `MyApp.Posts.Post` schema in `lib/my_app/posts/post.ex`, which outlines how the resource is represented in the database, and a **context** module named `MyApp.Posts` that encapsulates all the database access to said schema. The `MyApp.Posts` module centralizes all functionality related to posts, instead of scattering logic around controllers, LiveViews, etc.\n\nContexts are also useful to nest resources. For example, if you are adding comments to your posts, you can colocate their schemas, since comments belong to posts, like this:\n\n```console\n$ mix phx.gen.live Posts Comment comments post_id:references:posts body:text\n```\n\nThe first argument to the generator above is the context module, instructing Phoenix to colocate the comments functionality with posts. There is also a `post_id` attribute which specifies a foreign key reference to the posts table. As your application grows, contexts help you group related schemas, instead of having several dozens of schemas with no insights on how they relate to each other.\n\nDevelopers may also use contexts to intentionally name parts of their application. For example, `mix phx.gen.auth` requires a context name to be explicitly given. It is often invoked as:\n\n```console\n$ mix phx.gen.auth Accounts User users\n```\n\nor, using whatever name you prefer, such as:\n\n```console\n$ mix phx.gen.auth Identity Client clients\n```\n\nThe generated `Accounts` (or `Identity`) context will encapsulate all functionality for managing users (or clients) and their tokens. You could, if you wanted, name the context `Users` too, but given account/identity management has well defined name and boundary in most applications, giving it an explicit name makes its purposes clear. And, at the end of the day, they are just plain modules.\n\nIn this guide, we will use these ideas to build out our web application. Our goal is to build an ecommerce system where we can showcase products, allow users to add products to their cart, and complete their orders. We will do so by intentionally designing and naming our contexts. Opposite to other Phoenix guides, **these guides are meant to be read in order**.\n\n## Our ecommerce application\n\nLet's start an application from scratch to build our ecommerce, using Phoenix Express. We will call the application `hello`.\n\nFor macOS/Ubuntu:\n\n```bash\n$ curl https://new.phoenixframework.org/hello | sh\n```\n\nFor Windows PowerShell:\n\n```bash\ncurl.exe -fsSO https://new.phoenixframework.org/hello.bat; .\\hello.bat\n```\n\nIf those commands do not work, see the [Installation Guide](installation.html) and then run `mix phx.new`:\n\n```console\n$ mix phx.new hello\n```\n\nFollow any of the steps printed on the screen and open up the generated `hello` project in your editor.\n\nWe are ready to move to the next chapter.\n"
},
{
"path": "guides/data_modelling/cross_context_boundaries.md",
"content": "# 4. Cross-context Boundaries\n\nNow that we have the beginnings of our product catalog features, let's begin to work on the other main features of our application – carting products from the catalog. In order to properly track products that have been added to a user's cart, we'll need a new place to persist this information, along with point-in-time product information like the price at time of carting. This is necessary so we can detect product price changes in the future. We know what we need to build, but now we need to decide where the cart functionality lives in our application.\n\nIf we take a step back and think about the isolation of our application, the exhibition of products in our catalog distinctly differs from the responsibilities of managing a user's cart. A product catalog shouldn't care about the rules of our shopping cart system, and vice-versa. There's a clear need here for a separate context to handle the new cart responsibilities. Let's call it `ShoppingCart`.\n\nLet's create a `ShoppingCart` context to handle basic cart duties. Before we write code, let's imagine we have the following feature requirements:\n\n 1. Add products to a user's cart from the product show page\n 2. Store point-in-time product price information at time of carting\n 3. Store and update quantities in cart\n 4. Calculate and display sum of cart prices\n\nFrom the description, it's clear we need a `Cart` resource for storing the user's cart, along with a `CartItem` to track products in the cart. With our plan set, let's get to work.\n\n## Adding authentication\n\nMost of the cart functionality is tied to a specific user. Therefore, in order to allow each user to manage their own cart (and only their own carts), we must be able to authenticate users. To do so, we will use Phoenix's built-in `mix phx.gen.auth` generator to scaffold a solution for us:\n\n```console\nmix phx.gen.auth Accounts User users\n```\n\nYou will see output similar to the following: \n\n```console\nAn authentication system can be created in two different ways:\n- Using Phoenix.LiveView (default)\n- Using Phoenix.Controller only\nDo you want to create a LiveView based authentication system? [Yn]\n```\n\nType `n` followed by `Return` key,\nyou will see output similar to:\n\n```console\n...\n* creating lib/hello/accounts/scope.ex\n...\n* injecting config/config.exs\n...\n\nPlease re-fetch your dependencies with the following command:\n\n $ mix deps.get\n\nRemember to update your repository by running migrations:\n\n $ mix ecto.migrate\n\nOnce you are ready, visit \"/users/register\"\nto create your account and then access \"/dev/mailbox\" to\nsee the account confirmation email.\n```\n\nAfter following the instructions to re-fetch dependencies and migrating the database, we can start the server with `mix phx.server` and re-visit the home page [`http://localhost:4000/`](http://localhost:4000/). There, we should see new registration and login links at the top of the page. On the registration page, create a new user. In development, a confirmation email is sent to the dev mailbox, which is accessible at [`http://localhost:4000/dev/mailbox`](http://localhost:4000/dev/mailbox). After clicking the confirmation link, you should be successfully logged in.\n\nOne of the benefits of `mix phx.gen.auth` is that it also generates a scope file at `lib/hello/accounts/scope.ex`. In a nutshell, authentication tells us who a user is based on their email address, but it doesn't tell us the resources the user owns or has access to. In order to do so, we need authorization. Scopes help us tie generated resources, such as the Cart we will create, to users. Let's open up the file:\n\n```elixir\ndefmodule Hello.Accounts.Scope do\n ...\n alias Hello.Accounts.User\n\n defstruct user: nil\n\n @doc \"\"\"\n Creates a scope for the given user.\n\n Returns nil if no user is given.\n \"\"\"\n def for_user(%User{} = user) do\n %__MODULE__{user: user}\n end\n\n def for_user(nil), do: nil\nend\n```\n\nWe can see that it is simply a struct with a `user` field. The authentication system ensures that the `current_scope` assign is accordingly set with the current user. Let's see it in practice.\n\n## Generating scoped resources\n\nLet's generate our new context:\n\n```console\n$ mix phx.gen.context ShoppingCart Cart carts\n\n* creating lib/hello/shopping_cart/cart.ex\n* creating priv/repo/migrations/20250205203128_create_carts.exs\n* creating lib/hello/shopping_cart.ex\n* injecting lib/hello/shopping_cart.ex\n* creating test/hello/shopping_cart_test.exs\n* injecting test/hello/shopping_cart_test.exs\n* creating test/support/fixtures/shopping_cart_fixtures.ex\n* injecting test/support/fixtures/shopping_cart_fixtures.ex\n\nRemember to update your repository by running migrations:\n\n $ mix ecto.migrate\n```\n\nWe generated our new context `ShoppingCart`, with a new `ShoppingCart.Cart` schema. Open up the generated schema and migration files and you will see it has automatically included a `user_id` field, thanks to the scope. Furthermore, when we explore the code later on, we will learn all queries to the carts table have been properly scoped.\n\nWith our cart in place, let's generate our cart items. This time we will pass the `--no-scope` flag, because we will associate `cart_items` to `carts` and the `carts` are already scoped to the user:\n\n```console\n$ mix phx.gen.context ShoppingCart CartItem cart_items \\\ncart_id:references:carts product_id:references:products \\\nprice_when_carted:decimal quantity:integer --no-scope\n\nYou are generating into an existing context.\n...\nWould you like to proceed? [Yn] y\n* creating lib/hello/shopping_cart/cart_item.ex\n* creating priv/repo/migrations/20250205213410_create_cart_items.exs\n* injecting lib/hello/shopping_cart.ex\n* injecting test/hello/shopping_cart_test.exs\n* injecting test/support/fixtures/shopping_cart_fixtures.ex\n\nRemember to update your repository by running migrations:\n\n $ mix ecto.migrate\n```\n\nWe generated a new resource inside our `ShoppingCart` named `CartItem`. This schema and table will hold references to a cart and product, along with the price at the time we added the item to our cart, and the quantity the user wishes to purchase. Let's touch up the generated migration file in `priv/repo/migrations/*_create_cart_items.ex`:\n\n```diff\n create table(:cart_items) do\n- add :price_when_carted, :decimal\n+ add :price_when_carted, :decimal, precision: 15, scale: 6, null: false\n add :quantity, :integer\n- add :cart_id, references(:carts, on_delete: :nothing)\n+ add :cart_id, references(:carts, on_delete: :delete_all)\n- add :product_id, references(:products, on_delete: :nothing)\n+ add :product_id, references(:products, on_delete: :delete_all)\n\n timestamps(type: :utc_datetime)\n end\n\n- create index(:cart_items, [:cart_id])\n create index(:cart_items, [:product_id])\n+ create unique_index(:cart_items, [:cart_id, :product_id])\n```\n\nWe used the `:delete_all` strategy again to enforce data integrity. This way, when a cart or product is deleted from the application, we don't have to rely on application code in our `ShoppingCart` or `Catalog` contexts to worry about cleaning up the records. This keeps our application code decoupled and the data integrity enforcement where it belongs – in the database. We also added a unique constraint to ensure a duplicate product is not allowed to be added to a cart. As with the `product_categories` table, using a multi-column index lets us remove the separate index for the leftmost field (`cart_id`). With our database tables in place, we can now migrate up:\n\n```console\n$ mix ecto.migrate\n\n16:59:51.941 [info] == Running 20250205203342 Hello.Repo.Migrations.CreateCarts.change/0 forward\n\n16:59:51.945 [info] create table carts\n\n16:59:51.952 [info] == Migrated 20250205203342 in 0.0s\n\n16:59:51.988 [info] == Running 20250205213410 Hello.Repo.Migrations.CreateCartItems.change/0 forward\n\n16:59:51.988 [info] create table cart_items\n\n16:59:52.000 [info] create index cart_items_product_id_index\n\n16:59:52.001 [info] create index cart_items_cart_id_product_id_index\n\n16:59:52.002 [info] == Migrated 20250205213410 in 0.0s\n```\n\nOur database is ready to go with new `carts` and `cart_items` tables, but now we need to map that back into application code. You may be wondering how we can mix database foreign keys across different tables and how that relates to the context pattern of isolated, grouped functionality. Let's jump in and discuss the approaches and their tradeoffs.\n\n## Cross-context data\n\nSo far, we've done a great job isolating the two main contexts of our application from each other, but now we have a necessary dependency to handle.\n\nOur `Catalog.Product` resource serves to keep the responsibilities of representing a product inside the catalog, but ultimately for an item to exist in the cart, a product from the catalog must be present. Given this, our `ShoppingCart` context will have a data dependency on the `Catalog` context. With that in mind, we have two options. One is to expose APIs on the `Catalog` context that allows us to efficiently fetch product data for use in the `ShoppingCart` system, which we would manually stitch together. Or we can use database joins to fetch the dependent data. Both are valid options given your tradeoffs and application size, but joining data from the database when you have a hard data dependency is just fine for a large class of applications and is the approach we will take here.\n\nNow that we know where our data dependencies exist, let's add our schema associations so we can tie shopping cart items to products. First, let's make a quick change to our cart schema in `lib/hello/shopping_cart/cart.ex` to associate a cart to its items:\n\n```diff\n schema \"carts\" do\n- field :user_id, :id\n+ belongs_to :user, Hello.Accounts.User\n+ has_many :items, Hello.ShoppingCart.CartItem\n\n timestamps(type: :utc_datetime)\n end\n```\n\nNow that our cart is associated to the items we place in it, let's set up the cart item associations inside `lib/hello/shopping_cart/cart_item.ex`:\n\n```diff\n schema \"cart_items\" do\n field :price_when_carted, :decimal\n field :quantity, :integer\n- field :cart_id, :id\n- field :product_id, :id\n\n+ belongs_to :cart, Hello.ShoppingCart.Cart\n+ belongs_to :product, Hello.Catalog.Product\n\n timestamps(type: :utc_datetime)\n end\n\n @doc false\n def changeset(cart_item, attrs) do\n cart_item\n- |> cast(attrs, [:price_when_carted, :quantity])\n+ |> cast(attrs, [:quantity])\n- |> validate_required([:price_when_carted, :quantity])\n+ |> validate_required([:quantity])\n+ |> validate_number(:quantity, greater_than_or_equal_to: 0, less_than: 100)\n end\n```\n\nFirst, we replaced the `cart_id` field with a standard `belongs_to` pointing at our `ShoppingCart.Cart` schema. Next, we replaced our `product_id` field by adding our first cross-context data dependency with a `belongs_to` for the `Catalog.Product` schema. Here, we intentionally coupled the data boundaries because it provides exactly what we need: an isolated context API with the bare minimum knowledge necessary to reference a product in our system. Second, we remove `price_when_carted` from the list of permitted attributes to ensure any price provided by user input is discarded. Finally, we added a new validation to our changeset. With `validate_number/3`, we ensure any quantity provided by user input is between 0 and 100.\n\nWith our schemas in place, we can start integrating the new data structures and `ShoppingCart` context APIs into our web-facing features.\n\n## Adding Cart functions\n\nAs we mentioned before, the context generators are only a starting point for our application. We can and should write well-named, purpose built functions to accomplish the goals of our context. We have a few new features to implement. First, we need to ensure every user of our application is granted a cart if one does not yet exist. From there, we can then allow users to add items to their cart, update item quantities, and calculate cart totals. Let's get started!\n\nBecause we used `mix phx.gen.auth`, we already have a real authentication system in place. We can use the `current_scope` assign to access the currently authenticated user. Let's add a new plug that assigns a cart if there is an authenticated user:\n\n```diff\n pipeline :browser do\n plug :accepts, [\"html\"]\n plug :fetch_session\n plug :fetch_live_flash\n plug :put_root_layout, html: {HelloWeb.LayoutView, :root}\n plug :protect_from_forgery\n plug :put_secure_browser_headers\n plug :fetch_current_scope_for_user\n+ plug :fetch_current_cart\n end\n\n+ alias Hello.ShoppingCart\n+\n+ defp fetch_current_cart(%{assigns: %{current_scope: scope}} = conn, _opts) when not is_nil(scope) do\n+ if cart = ShoppingCart.get_cart(scope) do\n+ assign(conn, :cart, cart)\n+ else\n+ {:ok, new_cart} = ShoppingCart.create_cart(scope, %{})\n+ assign(conn, :cart, new_cart)\n+ end\n+ end\n+\n+ defp fetch_current_cart(conn, _opts), do: conn\n```\n\nWe added a new `:fetch_current_cart` plug which either finds a cart for the user UUID or creates a cart for the current user and assigns the result in the connection assigns. We'll need to implement our `ShoppingCart.get_cart/1`, but let's add our routes first.\n\nWe'll need to implement a cart controller for handling cart operations like viewing a cart, updating quantities, and initiating the checkout process, as well as a cart items controller for adding and removing individual items to and from the cart. The authentication system already generated different router scopes that have different authentication requirements:\n\n```elixir\n...\n ## Authentication routes\n\n scope \"/\", HelloWeb do\n pipe_through [:browser, :redirect_if_user_is_authenticated]\n\n get \"/user/register\", UserRegistrationController, :new\n post \"/user/register\", UserRegistrationController, :create\n end\n\n scope \"/\", HelloWeb do\n pipe_through [:browser, :require_authenticated_user]\n\n get \"/user/settings\", UserSettingsController, :edit\n put \"/user/settings\", UserSettingsController, :update\n get \"/user/settings/confirm-email/:token\", UserSettingsController, :confirm_email\n end\n...\n```\n\nAs you can see, the registration route has a `:redirect_if_user_is_authenticated` plug, which means it will redirect to the home page if the user is already authenticated. The user settings routes use a `:require_authenticated_user` plug, which means they will redirect to the log in page if the user is not authenticated. These plugs are defined in the `lib/hello_web/user_auth.ex` module.\n\nFor our cart routes, we want to only allow access to authenticated users. Add the following routes to your router in `lib/hello_web/router.ex`:\n\n```diff\n scope \"/\", HelloWeb do\n pipe_through :browser\n\n get \"/\", PageController, :index\n resources \"/products\", ProductController\n end\n\n+ scope \"/\", HelloWeb do\n+ pipe_through [:browser, :require_authenticated_user]\n+\n+ resources \"/cart_items\", CartItemController, only: [:create, :delete]\n+\n+ get \"/cart\", CartController, :show\n+ put \"/cart\", CartController, :update\n+ end\n```\n\nWe added a `resources` declaration for a `CartItemController`, which will wire up the routes for a create and delete action for adding and removing individual cart items. Next, we added two new routes pointing at a `CartController`. The first route, a GET request, will map to our show action, to show the cart contents. The second route, a PUT request, will handle the submission of a form for updating our cart quantities.\n\nWith our routes in place, let's add the ability to add an item to our cart from the product show page. Create a new file at `lib/hello_web/controllers/cart_item_controller.ex` and key this in:\n\n```elixir\ndefmodule HelloWeb.CartItemController do\n use HelloWeb, :controller\n\n alias Hello.ShoppingCart\n\n def create(conn, %{\"product_id\" => product_id}) do\n case ShoppingCart.add_item_to_cart(conn.assigns.current_scope, conn.assigns.cart, product_id) do\n {:ok, _item} ->\n conn\n |> put_flash(:info, \"Item added to your cart\")\n |> redirect(to: ~p\"/cart\")\n\n {:error, _changeset} ->\n conn\n |> put_flash(:error, \"There was an error adding the item to your cart\")\n |> redirect(to: ~p\"/cart\")\n end\n end\n\n def delete(conn, %{\"id\" => product_id}) do\n {:ok, _cart} = ShoppingCart.remove_item_from_cart(conn.assigns.current_scope, conn.assigns.cart, product_id)\n redirect(conn, to: ~p\"/cart\")\n end\nend\n```\n\nWe defined a new `CartItemController` with the create and delete actions that we declared in our router. For `create`, we call a `ShoppingCart.add_item_to_cart/3` function which we'll implement in a moment. If successful, we show a flash successful message and redirect to the cart show page; else, we show a flash error message and redirect to the cart show page. For `delete`, we'll call a `remove_item_from_cart` function which we'll implement on our `ShoppingCart` context and then redirect back to the cart show page. We haven't implemented these two shopping cart functions yet, but notice how their names scream their intent: `add_item_to_cart` and `remove_item_from_cart` make it obvious what we are accomplishing here. It also allows us to spec out our web layer and context APIs without thinking about all the implementation details at once.\n\nLet's implement the new interface for the `ShoppingCart` context API in `lib/hello/shopping_cart.ex`:\n\n```diff\n+ alias Hello.Catalog\n- alias Hello.ShoppingCart.Cart\n+ alias Hello.ShoppingCart.{Cart, CartItem}\n alias Hello.Accounts.Scope\n\n+ def get_cart(%Scope{} = scope) do\n+ Repo.one(\n+ from(c in Cart,\n+ where: c.user_id == ^scope.user.id,\n+ left_join: i in assoc(c, :items),\n+ left_join: p in assoc(i, :product),\n+ order_by: [asc: i.inserted_at],\n+ preload: [items: {i, product: p}]\n+ )\n+ )\n+ end\n\n def create_cart(%Scope{} = scope, attrs) do\n with {:ok, cart = %Cart{}} <-\n %Cart{}\n |> Cart.changeset(attrs, scope)\n |> Repo.insert() do\n broadcast(scope, {:created, cart})\n- {:ok, cart}\n+ {:ok, get_cart(scope)}\n end\n end\n+\n+ def add_item_to_cart(%Scope{} = scope, %Cart{} = cart, product_id) do\n+ true = cart.user_id == scope.user.id\n+ product = Catalog.get_product!(product_id)\n+\n+ %CartItem{quantity: 1, price_when_carted: product.price}\n+ |> CartItem.changeset(%{})\n+ |> Ecto.Changeset.put_assoc(:cart, cart)\n+ |> Ecto.Changeset.put_assoc(:product, product)\n+ |> Repo.insert(\n+ on_conflict: [inc: [quantity: 1]],\n+ conflict_target: [:cart_id, :product_id]\n+ )\n+ end\n+\n+ def remove_item_from_cart(%Scope{} = scope, %Cart{} = cart, product_id) do\n+ true = cart.user_id == scope.user.id\n+\n+ {1, _} =\n+ Repo.delete_all(\n+ from(i in CartItem,\n+ where: i.cart_id == ^cart.id,\n+ where: i.product_id == ^product_id\n+ )\n+ )\n+\n+ {:ok, get_cart(scope)}\n+ end\n```\n\nWe started by implementing `get_cart/1` which fetches our cart and joins the cart items, and their products so that we have the full cart populated with all preloaded data. Next, we modified our `create_cart` function to use `get_cart` to reload the cart contents.\n\nNext, we wrote our new `add_item_to_cart/3` function which accepts a scope, a cart struct and a product id. We proceed to fetch the product with `Catalog.get_product!/1`, showing how contexts can naturally invoke other contexts if required. You could also have chosen to receive the product as argument and you would achieve similar results. Then we used an upsert operation against our repo to either insert a new cart item into the database, or increase the quantity by one if it already exists in the cart. This is accomplished via the `on_conflict` and `conflict_target` options, which tells our repo how to handle an insert conflict.\n\nFinally, we implemented `remove_item_from_cart/3` where we simply issue a `Repo.delete_all` call with a query to delete the cart item in our cart that matches the product ID. Finally, we reload the cart contents by calling `get_cart/1`.\n\nWith our new cart functions in place, we can now expose the \"Add to cart\" button on the product catalog show page. Open up your template in `lib/hello_web/controllers/product_html/show.html.heex` and make the following changes:\n\n```diff\n...\n <.button variant=\"primary\" navigate={~p\"/products/#{@product}/edit?return_to=show\"}>\n <.icon name=\"hero-pencil-square\" /> Edit product\n \n+ <.button href={~p\"/cart_items?product_id=#{@product.id}\"} method=\"post\">\n+ Add to cart\n+ \n...\n```\n\nThe `link` function component from `Phoenix.Component` accepts a `:method` attribute to issue an HTTP verb when clicked, instead of the default GET request. With this link in place, the \"Add to cart\" link will issue a POST request, which will be matched by the route we defined in router which dispatches to the `CartItemController.create/2` function.\n\nLet's try it out. Start your server with `mix phx.server` and visit a product page. If we try clicking the add to cart link, we'll be greeted by an error page. If you are authenticated the following logs should be visible in the console:\n\n```text\n[info] POST /cart_items\n[debug] Processing with HelloWeb.CartItemController.create/2\n Parameters: %{\"_method\" => \"post\", \"product_id\" => \"1\", ...}\n Pipelines: [:browser, :require_authenticated_user]\n[debug] QUERY OK source=\"user_tokens\" db=2.4ms idle=1340.8ms\n...\n[debug] QUERY OK source=\"cart_items\" db=2.5ms\nINSERT INTO \"cart_items\" ...\n[info] Sent 302 in 24ms\n[info] GET /cart\n[debug] Processing with HelloWeb.CartController.show/2\n Parameters: %{}\n Pipelines: [:browser, :require_authenticated_user]\n[debug] QUERY OK source=\"user_tokens\" db=1.6ms idle=430.2ms\n...\n[debug] QUERY OK source=\"carts\" db=1.9ms idle=1798.5ms\n...\n[info] Sent 500 in 18ms\n[error] ** (UndefinedFunctionError) function HelloWeb.CartController.init/1 is undefined (module HelloWeb.CartController is not available)\n ...\n```\n\nIt's working! Kind of. If we follow the logs, we see our POST to the `/cart_items` path. Next, we can see our `ShoppingCart.add_item_to_cart` function successfully inserted a row into the `cart_items` table, and then we issued a redirect to `/cart`. Before our error, we also see a query to the `carts` table, which means we're fetching the current user's cart. So far so good. We know our `CartItem` controller and new `ShoppingCart` context functions are doing their jobs, but we've hit our next unimplemented feature when the router attempts to dispatch to a nonexistent cart controller. Let's create the cart controller, view, and template to display and manage user carts.\n\nCreate a new file at `lib/hello_web/controllers/cart_controller.ex` and key this in:\n\n```elixir\ndefmodule HelloWeb.CartController do\n use HelloWeb, :controller\n\n alias Hello.ShoppingCart\n\n def show(conn, _params) do\n render(conn, :show, changeset: ShoppingCart.change_cart(conn.assigns.current_scope, conn.assigns.cart))\n end\nend\n```\n\nWe defined a new cart controller to handle the `get \"/cart\"` route. For showing a cart, we render a `\"show.html\"` template which we'll create in a moment. We know we need to allow the cart items to be changed by quantity updates, so right away we know we'll need a cart changeset. Fortunately, the context generator included a `ShoppingCart.change_cart/1` function, which we'll use. We pass it our cart struct which is already in the connection assigns thanks to the `fetch_current_cart` plug we defined in the router.\n\nNext, we can implement the view and template. Create a new view file at `lib/hello_web/controllers/cart_html.ex` with the following content:\n\n```elixir\ndefmodule HelloWeb.CartHTML do\n use HelloWeb, :html\n\n alias Hello.ShoppingCart\n\n embed_templates \"cart_html/*\"\n\n def currency_to_str(%Decimal{} = val), do: \"$#{Decimal.round(val, 2)}\"\nend\n```\n\nWe created a view to render our `show.html` template and aliased our `ShoppingCart` context so it will be in scope for our template. We'll need to display the cart prices like product item price, cart total, etc, so we defined a `currency_to_str/1` which takes our decimal struct, rounds it properly for display, and prepends a USD dollar sign.\n\nNext we can create the template at `lib/hello_web/controllers/cart_html/show.html.heex`:\n\n```heex\n\n <.header>\n My Cart\n <:subtitle :if={@cart.items == []}>Your cart is empty\n \n\n
\n\n <.button navigate={~p\"/products\"}>Back to products\n\n```\n\nWe started by showing the empty cart message if our preloaded `cart.items` is empty. If we have items, we use the `form` component provided by our `HelloWeb.CoreComponents` to take our cart changeset that we assigned in the `CartController.show/2` action and create a form which maps to our cart controller `update/2` action. Within the form, we use the [`inputs_for`](https://hexdocs.pm/phoenix_live_view/Phoenix.Component.html#inputs_for/1) component to render inputs for the nested cart items. This will allow us to map item inputs back together when the form is submitted. Next, we display a number input for the item quantity and label it with the product title. We finish the item form by converting the item price to string. We haven't written the `ShoppingCart.total_item_price/1` function yet, but again we employed the idea of clear, descriptive public interfaces for our contexts. After rendering inputs for all the cart items, we show an \"update cart\" submit button, along with the total price of the entire cart. This is accomplished with another new `ShoppingCart.total_cart_price/1` function which we'll implement in a moment. Finally, we added a `back` component to go back to our products page.\n\nWe're almost ready to try out our cart page, but first we need to implement our new currency calculation functions. Open up your shopping cart context at `lib/hello/shopping_cart.ex` and add these new functions:\n\n```elixir\n def total_item_price(%CartItem{} = item) do\n Decimal.mult(item.product.price, item.quantity)\n end\n\n def total_cart_price(%Cart{} = cart) do\n Enum.reduce(cart.items, 0, fn item, acc ->\n item\n |> total_item_price()\n |> Decimal.add(acc)\n end)\n end\n```\n\nWe implemented `total_item_price/1` which accepts a `%CartItem{}` struct. To calculate the total price, we simply take the preloaded product's price and multiply it by the item's quantity. We used `Decimal.mult/2` to take our decimal currency struct and multiply it with proper precision. Similarly for calculating the total cart price, we implemented a `total_cart_price/1` function which accepts the cart and sums the preloaded product prices for items in the cart. We again make use of the `Decimal` functions to add our decimal structs together.\n\nNow that we can calculate price totals, let's try it out! Visit [`http://localhost:4000/cart`](http://localhost:4000/cart) and you should already see your first item in the cart. Going back to the same product and clicking \"add to cart\" will show our upsert in action. Your quantity should now be two. Nice work!\n\nOur cart page is almost complete, but submitting the form will yield yet another error.\n\n```text\n[info] POST /cart\n...\n[error] ** (UndefinedFunctionError) function HelloWeb.CartController.update/2 is undefined or private\n```\n\nLet's head back to our `CartController` at `lib/hello_web/controllers/cart_controller.ex` and implement the update action:\n\n```elixir\n def update(conn, %{\"cart\" => cart_params}) do\n case ShoppingCart.update_cart(conn.assigns.current_scope, conn.assigns.cart, cart_params) do\n {:ok, _cart} ->\n redirect(conn, to: ~p\"/cart\")\n\n {:error, _changeset} ->\n conn\n |> put_flash(:error, \"There was an error updating your cart\")\n |> redirect(to: ~p\"/cart\")\n end\n end\n```\n\nWe started by plucking out the cart params from the form submit. Next, we call our existing `ShoppingCart.update_cart/2` function which was added by the context generator. We'll need to make some changes to this function, but the interface is good as is. If the update is successful, we redirect back to the cart page, otherwise we show a flash error message and send the user back to the cart page to fix any mistakes. Out-of-the-box, our `ShoppingCart.update_cart/2` function only concerned itself with casting the cart params into a changeset and updates it against our repo. For our purposes, we now need it to handle nested cart item associations, and most importantly, business logic for how to handle quantity updates like zero-quantity items being removed from the cart.\n\nHead back over to your shopping cart context in `lib/hello/shopping_cart.ex` and replace your `update_cart/2` function with the following implementation:\n\n```elixir\n def update_cart(%Scope{} = scope, %Cart{} = cart, attrs) do\n true = cart.user_id == scope.user.id\n\n changeset =\n cart\n |> Cart.changeset(attrs, scope)\n |> Ecto.Changeset.cast_assoc(:items, with: &CartItem.changeset/2)\n \n Repo.transact(fn ->\n with {:ok, cart} <- Repo.update(changeset),\n {_count, _cart_items} = Repo.delete_all(from(i in CartItem, where: i.cart_id == ^cart.id and i.quantity == 0)) do\n {:ok, cart}\n end\n end)\n |> case do\n {:ok, cart} ->\n broadcast_cart(scope, {:updated, cart})\n {:ok, cart}\n\n {:error, reason} ->\n {:error, reason}\n end\n end\n```\n\nWe started much like how our out-of-the-box code started – we take the cart struct and cast the user input to a cart changeset, except this time we use `Ecto.Changeset.cast_assoc/3` to cast the nested item data into `CartItem` changesets. Remember the [`<.inputs_for />`](https://hexdocs.pm/phoenix_live_view/Phoenix.Component.html#inputs_for/1) call in our cart form template? That hidden ID data is what allows Ecto's `cast_assoc` to map item data back to existing item associations in the cart. \n\nOnce the `changeset` is ready, we wrap everything in `Repo.transact/2` so the operations run safely as one. Inside the transaction, we update the cart using `Repo.update/1`. If the update succeeds, we follow up with a cleanup step using `Repo.delete_all/2` to remove any cart items with zero quantity. Running both steps in the same transaction prevents partial updates and keeps the cart data accurate. Finally, we broadcast the updated cart so that any connected LiveViews can instantly show the changes.\n\nLet's head back to the browser and try it out. Add a few products to your cart, update the quantities, and watch the values changes along with the price calculations. Setting any quantity to 0 will also remove the item. You can also try logging out and registering a new user to see how the carts are scoped to the current user. Pretty neat!\n"
},
{
"path": "guides/data_modelling/faq.md",
"content": "# 6. FAQ\n\nHere we list frequently asked questions about contexts.\n\n## When to use code generators?\n\nIn this guide, we have used code generators for schemas, contexts, controllers, and more. If you are happy to move forward with Phoenix defaults, feel free to rely on generators to scaffold large parts of your application. When using Phoenix generators, the main question you need to answer is: does this new functionality (with its schema, table, and fields) belong to one of the existing contexts or a new one?\n\nThis way, Phoenix generators guide you to use contexts to group related functionality, instead of having several dozens of schemas laying around without any structure. And remember: if you're stuck when trying to come up with a context name, you can simply use the plural form of the resource you're creating.\n\n## How do I structure code inside contexts?\n\nYou may wonder how to organize the code inside contexts. For example, should you define a module for changesets (such as ProductChangesets) and another module for queries (such as ProductQueries)?\n\nOne important benefit of contexts is that this decision does not matter much. The context is your public API, the other modules are private. Contexts isolate these modules into small groups so the surface area of your application is the context and not _all of your code_.\n\nSo while you and your team could establish patterns for organizing these private modules, it is also our opinion that it is completely fine for them to be different. The major focus should be on how the contexts are defined and how they interact with each other (and with your web application).\n\nThink about it as a well-kept neighbourhood. Your contexts are houses, you want to keep them well-preserved, well-connected, etc. Inside the houses, they may all be a little bit different, and that's fine.\n\n## Returning Ecto structures from context APIs\n\nAs we explored the context API, you might have wondered:\n\n> If one of the goals of our context is to encapsulate Ecto Repo access, why does `create_user/1` return an `Ecto.Changeset` struct when we fail to create a user?\n\nAlthough Changesets are part of Ecto, they are not tied to the database, and they can be used to map data from and to any source, which makes it a general and useful data structure for tracking field changes, perform validations, and generate error messages.\n\nFor those reasons, `%Ecto.Changeset{}` is a good choice to model the data changes between your contexts and your web layer - regardless if you are talking to an API or the database.\n\nFinally, note that your controllers and views are not hardcoded to work exclusively with Ecto either. Instead, Phoenix defines protocols such as `Phoenix.Param` and `Phoenix.HTML.FormData`, which allow any library to extend how Phoenix generates URL parameters or renders forms. Conveniently for us, the `phoenix_ecto` project implements those protocols, but you could as well bring your own data structures and implement them yourself.\n"
},
{
"path": "guides/data_modelling/in_context_relationships.md",
"content": "# 3. In-context Relationships\n\nOur basic catalog features are nice, but let's take it up a notch by categorizing products. Many ecommerce solutions allow products to be categorized in different ways, such as a product being marked for fashion, power tools, and so on. Starting with a one-to-one relationship between product and categories will cause major code changes later if we need to start supporting multiple categories. Let's set up a category association that will allow us to start off tracking a single category per product, but easily support more later as we grow our features.\n\nFor now, categories will contain only textual information. Our first order of business is to decide where categories live in the application. We have our `Catalog` context, which manages the exhibition of our products. Product categorization is a natural fit here. Phoenix is also smart enough to generate code inside an existing context, which makes adding new resources to a context a breeze. Run the following command at your project root:\n\n> Sometimes it may be tricky to determine if two resources belong to the same context or not. In those cases, prefer distinct contexts per resource and refactor later if necessary. Otherwise you can easily end up with large contexts of loosely related entities. Also keep in mind that the fact two resources are related does not necessarily mean they belong to the same context, otherwise you would quickly end up with one large context, as the majority of resources in an application are connected to each other. To sum it up: if you are unsure, you should prefer separate modules (contexts).\n\n```console\nmix phx.gen.context Catalog Category categories \\\ntitle:string:unique --no-scope\n```\n\nYou will see the following output in your terminal: \n\n```console\nYou are generating into an existing context.\n\nThe Hello.Catalog context currently has 7 functions and 1 file in its directory.\n\n * It's OK to have multiple resources in the same context as long as they are closely related. \n\n...\n\nWould you like to proceed? [Yn]\n```\n\nType `y` followed by the `Return` key.\nYou should see output similar to:\n\n```console\n* creating lib/hello/catalog/category.ex\n* creating priv/repo/migrations/20250203192325_create_categories.exs\n* injecting lib/hello/catalog.ex\n* injecting test/hello/catalog_test.exs\n* injecting test/support/fixtures/catalog_fixtures.ex\n\nRemember to update your repository by running migrations:\n\n $ mix ecto.migrate\n```\n\nThis time around, we used `mix phx.gen.context`, which is just like `mix phx.gen.html`, except it doesn't generate the web files for us. Since we already have controllers and templates for managing products, we can integrate the new category features into our existing web form and product show page. We can see we now have a new `Category` schema alongside our product schema at `lib/hello/catalog/category.ex`, and Phoenix told us it was *injecting* new functions in our existing Catalog context for the category functionality. The injected functions will look very familiar to our product functions, with new functions like `create_category`, `list_categories`, and so on. Before we migrate up, we need to do a second bit of code generation. Our category schema is great for representing an individual category in the system, but we need to support a many-to-many relationship between products and categories. Fortunately, ecto allows us to do this simply with a join table, so let's generate that now with the `ecto.gen.migration` command:\n\n```console\nmix ecto.gen.migration create_product_categories\n```\n\nYou will see output confirming the migration file was created:\n\n```console\n* creating priv/repo/migrations/20250203192958_create_product_categories.exs\n```\n\nNext, let's open up the new migration file and add the following code to the `change` function:\n\n```elixir\ndefmodule Hello.Repo.Migrations.CreateProductCategories do\n use Ecto.Migration\n\n def change do\n create table(:product_categories, primary_key: false) do\n add :product_id, references(:products, on_delete: :delete_all)\n add :category_id, references(:categories, on_delete: :delete_all)\n end\n\n create index(:product_categories, [:product_id])\n create unique_index(:product_categories, [:category_id, :product_id])\n end\nend\n```\n\nWe created a `product_categories` table and used the `primary_key: false` option since our join table does not need a primary key. Next we defined our `:product_id` and `:category_id` foreign key fields, and passed `on_delete: :delete_all` to ensure the database prunes our join table records if a linked product or category is deleted. By using a database constraint, we enforce data integrity at the database level, rather than relying on ad-hoc and error-prone application logic.\n\nNext, we created indexes for our foreign keys, one of which is a unique index to ensure a product cannot have duplicate categories. Note that we do not necessarily need single-column index for `category_id` because it is in the leftmost prefix of multicolumn index, which is enough for the database optimizer. Adding a redundant index, on the other hand, only adds overhead on write.\n\nWith our migrations in place, we can migrate up.\n\n```console\nmix ecto.migrate\n```\n\nYou will see the following output confirming migration success:\n\n```\n18:20:36.489 [info] == Running 20250222231834 Hello.Repo.Migrations.CreateCategories.change/0 forward\n\n18:20:36.493 [info] create table categories\n\n18:20:36.508 [info] create index categories_title_index\n\n18:20:36.512 [info] == Migrated 20250222231834 in 0.0s\n\n18:20:36.547 [info] == Running 20250222231930 Hello.Repo.Migrations.CreateProductCategories.change/0 forward\n\n18:20:36.547 [info] create table product_categories\n\n18:20:36.557 [info] create index product_categories_product_id_index\n\n18:20:36.560 [info] create index product_categories_category_id_product_id_index\n\n18:20:36.562 [info] == Migrated 20250222231930 in 0.0s\n```\n\nNow that we have a `Catalog.Product` schema and a join table to associate products and categories, we're nearly ready to start wiring up our new features. Before we dive in, we first need real categories to select in our web UI. Let's quickly seed some new categories in the application. Add the following code to your seeds file in `priv/repo/seeds.exs`:\n\n```elixir\nfor title <- [\"Home Improvement\", \"Power Tools\", \"Gardening\", \"Books\", \"Education\"] do\n {:ok, _} = Hello.Catalog.create_category(%{title: title})\nend\n```\n\nWe simply enumerate over a list of category titles and use the generated `create_category/1` function of our catalog context to persist the new records. We can run the seeds with `mix run`:\n\n```console\nmix run priv/repo/seeds.exs\n```\n\nThe output in the terminal confirms the `seeds.exs` executed successfully: \n\n```console\n[debug] QUERY OK db=3.1ms decode=1.1ms queue=0.7ms idle=2.2ms\nINSERT INTO \"categories\" (\"title\",\"inserted_at\",\"updated_at\") VALUES ($1,$2,$3) RETURNING \"id\" [\"Home Improvement\", ~N[2025-02-03 19:39:53], ~N[2025-02-03 19:39:53]]\n[debug] QUERY OK db=1.2ms queue=1.3ms idle=12.3ms\nINSERT INTO \"categories\" (\"title\",\"inserted_at\",\"updated_at\") VALUES ($1,$2,$3) RETURNING \"id\" [\"Power Tools\", ~N[2025-02-03 19:39:53], ~N[2025-02-03 19:39:53]]\n[debug] QUERY OK db=1.1ms queue=1.1ms idle=15.1ms\nINSERT INTO \"categories\" (\"title\",\"inserted_at\",\"updated_at\") VALUES ($1,$2,$3) RETURNING \"id\" [\"Gardening\", ~N[2025-02-03 19:39:53], ~N[2025-02-03 19:39:53]]\n[debug] QUERY OK db=2.4ms queue=1.0ms idle=17.6ms\nINSERT INTO \"categories\" (\"title\",\"inserted_at\",\"updated_at\") VALUES ($1,$2,$3) RETURNING \"id\" [\"Books\", ~N[2025-02-03 19:39:53], ~N[2025-02-03 19:39:53]]\n```\n\nPerfect. Before we integrate categories in the web layer, we need to let our context know how to associate products and categories. First, open up `lib/hello/catalog/product.ex` and add the following association:\n\n```diff\n+ alias Hello.Catalog.Category\n\n schema \"products\" do\n field :description, :string\n field :price, :decimal\n field :title, :string\n field :views, :integer\n\n+ many_to_many :categories, Category, join_through: \"product_categories\", on_replace: :delete\n\n timestamps(type: :utc_datetime)\n end\n\n```\n\nWe used `Ecto.Schema`'s `many_to_many` macro to let Ecto know how to associate our product to multiple categories through the `\"product_categories\"` join table. We also used the `on_replace: :delete` option to declare that any existing join records should be deleted when we are changing our categories.\n\nWith our schema associations set up, we can implement the selection of categories in our product form. To do so, we need to translate the user input of catalog IDs from the front-end to our many-to-many association. Fortunately Ecto makes this a breeze now that our schema is set up. Open up your catalog context and make the following changes:\n\n```diff\n+ alias Hello.Catalog.Category\n\n- def get_product!(id), do: Repo.get!(Product, id)\n+ def get_product!(id) do\n+ Product\n+ |> Repo.get!(id)\n+ |> Repo.preload(:categories)\n+ end\n\n def create_product(attrs) do\n %Product{}\n- |> Product.changeset(attrs)\n+ |> change_product(attrs)\n |> Repo.insert()\n end\n\n def update_product(%Product{} = product, attrs) do\n product\n- |> Product.changeset(attrs)\n+ |> change_product(attrs)\n |> Repo.update()\n end\n\n def change_product(%Product{} = product, attrs \\\\ %{}) do\n- Product.changeset(product, attrs)\n+ categories = list_categories_by_id(attrs[\"category_ids\"])\n\n+ product\n+ |> Repo.preload(:categories)\n+ |> Product.changeset(attrs)\n+ |> Ecto.Changeset.put_assoc(:categories, categories)\n end\n\n+ def list_categories_by_id(nil), do: []\n+ def list_categories_by_id(category_ids) do\n+ Repo.all(from c in Category, where: c.id in ^category_ids)\n+ end\n```\n\nFirst, we added `Repo.preload` to preload our categories when we fetch a product. This will allow us to reference `product.categories` in our controllers, templates, and anywhere else we want to make use of category information. Next, we modified our `create_product` and `update_product` functions to call into our existing `change_product` function to produce a changeset. Within `change_product` we added a lookup to find all categories if the `\"category_ids\"` attribute is present. Then we preloaded categories and called `Ecto.Changeset.put_assoc` to place the fetched categories into the changeset. Finally, we implemented the `list_categories_by_id/1` function to query the categories matching the category IDs, or return an empty list if no `\"category_ids\"` attribute is present. Now our `create_product` and `update_product` functions receive a changeset with the category associations all ready to go once we attempt an insert or update against our repo.\n\nNext, let's expose our new feature to the web by adding the category input to our product form. To keep our form template tidy, let's write a new function to wrap up the details of rendering a category select input for our product. Open up your `ProductHTML` view in `lib/hello_web/controllers/product_html.ex` and key this in:\n\n```elixir\n def category_opts(changeset) do\n existing_ids =\n changeset\n |> Ecto.Changeset.get_change(:categories, [])\n |> Enum.map(& &1.data.id)\n\n for cat <- Hello.Catalog.list_categories() do\n [key: cat.title, value: cat.id, selected: cat.id in existing_ids]\n end\n end\n```\n\nWe added a new `category_opts/1` function which generates the select options for a multiple select tag we will add soon. We calculated the existing category IDs from our changeset, then used those values when we generate the select options for the input tag. We did this by enumerating over all of our categories and returning the appropriate `key`, `value`, and `selected` values. We marked an option as selected if the category ID was found in those category IDs in our changeset.\n\nWith our `category_opts` function in place, we can open up `lib/hello_web/controllers/product_html/product_form.html.heex` and add:\n\n```diff\n ...\n <.input field={f[:views]} type=\"number\" label=\"Views\" />\n\n+ <.input field={f[:category_ids]} type=\"select\" multiple options={category_opts(@changeset)} />\n\n <.button>Save Product\n```\n\nWe added a `category_select` above our save button. Now let's try it out. Next, let's show the product's categories in the product show template. Add the following code to the list in `lib/hello_web/controllers/product_html/show.html.heex`:\n\n```diff\n<.list>\n ...\n+ <:item title=\"Categories\">\n+
\n+
{cat.title}
\n+
\n+ \n\n```\n\nNow if we start the server with `mix phx.server` and visit [http://localhost:4000/products/new](http://localhost:4000/products/new), we'll see the new category multiple select input. Enter some valid product details, select a category or two, and click save.\n\n```text\nTitle: Elixir Flashcards\nDescription: Flash card set for the Elixir programming language\nPrice: 5.000000\nViews: 0\nCategories:\nEducation\nBooks\n```\n\nIt's not much to look at yet, but it works! We added relationships within our context complete with data integrity enforced by the database. Not bad. Let's keep building!\n"
},
{
"path": "guides/data_modelling/more_examples.md",
"content": "# 5. Bringing It Home\n\nWith our `Catalog` and `ShoppingCart` contexts, we're seeing first-hand how our well-considered modules and function names are yielding clear and maintainable code. Our last order of business is to allow the user to initiate the checkout process. We won't go as far as integrating payment processing or order fulfillment, but we'll get you started in that direction. This will be a great opportunity to put what we have learned so far in practice.\n\nLike before, we need to decide where code for completing an order should live. Is it part of the catalog? Clearly not, but what about the shopping cart? Shopping carts are related to orders – after all, the user has to add items in order to purchase any products – but should the order checkout process be grouped here?\n\nIf we stop and consider the order process, we'll see that orders involve related, but distinctly different data from the cart contents. Also, business rules around the checkout process are much different than carting. For example, we may allow a user to add a back-ordered item to their cart, but we could not allow an order with no inventory to be completed. Additionally, we need to capture point-in-time product information when an order is completed, such as the price of the items *at payment transaction time*. This is essential because a product price may change in the future, but the line items in our order must always record and display what we charged at time of purchase. For these reasons, we can start to see that ordering can stand on its own with its own data concerns and business rules.\n\nNaming wise, `Orders` clearly defines our context, so let's get started by again taking advantage of the context generators. Note that the `user` scope generated by `mix phx.gen.auth` is marked as default scope (in your `config/config.exs`), therefore we don't need to specify it in our command. There can be different scopes in an application, in which case the `--scope` option can be used when running the generators. Run the following command in your console:\n\n```console\n$ mix phx.gen.context Orders Order orders total_price:decimal\n\n* creating lib/hello/orders/order.ex\n* creating priv/repo/migrations/20250209214612_create_orders.exs\n* creating lib/hello/orders.ex\n* injecting lib/hello/orders.ex\n* creating test/hello/orders_test.exs\n* injecting test/hello/orders_test.exs\n* creating test/support/fixtures/orders_fixtures.ex\n* injecting test/support/fixtures/orders_fixtures.ex\n\nRemember to update your repository by running migrations:\n\n $ mix ecto.migrate\n```\n\nWe generated an `Orders` context. The order is automatically scoped to the current user and added a `total_price` column. With our starting point in place, let's open up the newly created migration in `priv/repo/migrations/*_create_orders.exs` and make the following changes:\n\n```diff\n def change do\n create table(:orders) do\n- add :total_price, :decimal\n+ add :total_price, :decimal, precision: 15, scale: 6, null: false\n add :user_id, references(:users, type: :id, on_delete: :delete_all)\n\n timestamps(type: :utc_datetime)\n end\n end\n```\n\nLike we did previously, we gave appropriate precision and scale options for our decimal column which will allow us to store currency without precision loss. We also added a not-null constraint to enforce all orders to have a price.\n\nThe orders table alone doesn't hold much information, but we know we'll need to store point-in-time product price information of all the items in the order. For that, we'll add an additional struct for this context named `LineItem`. Line items will capture the price of the product *at payment transaction time*. Please run the following command:\n\n```console\n$ mix phx.gen.context Orders LineItem order_line_items \\\nprice:decimal quantity:integer \\\norder_id:references:orders product_id:references:products --no-scope\n\nYou are generating into an existing context.\n...\nWould you like to proceed? [Yn] y\n* creating lib/hello/orders/line_item.ex\n* creating priv/repo/migrations/20250209215050_create_order_line_items.exs\n* injecting lib/hello/orders.ex\n* injecting test/hello/orders_test.exs\n* injecting test/support/fixtures/orders_fixtures.ex\n\nRemember to update your repository by running migrations:\n\n $ mix ecto.migrate\n```\n\nWe used the `phx.gen.context` command to generate the `LineItem` Ecto schema and inject supporting functions into our orders context. Like before, let's modify the migration in `priv/repo/migrations/*_create_order_line_items.exs` and make the following decimal field changes:\n\n```diff\n def change do\n create table(:order_line_items) do\n- add :price, :decimal\n+ add :price, :decimal, precision: 15, scale: 6, null: false\n add :quantity, :integer\n add :order_id, references(:orders, on_delete: :nothing)\n add :product_id, references(:products, on_delete: :nothing)\n\n timestamps(type: :utc_datetime)\n end\n\n create index(:order_line_items, [:order_id])\n create index(:order_line_items, [:product_id])\n end\n```\n\nWith our migration in place, let's wire up our orders and line items associations in `lib/hello/orders/order.ex`:\n\n```diff\n schema \"orders\" do\n field :total_price, :decimal\n- field :user_id, :id\n\n+ belongs_to :user, Hello.Accounts.User\n+ has_many :line_items, Hello.Orders.LineItem\n+ has_many :products, through: [:line_items, :product]\n\n timestamps(type: :utc_datetime)\n end\n```\n\nWe used `has_many :line_items` to associate orders and line items, just like we've seen before. Next, we used the `:through` feature of `has_many`, which allows us to instruct ecto how to associate resources across another relationship. In this case, we can associate products of an order by finding all products through associated line items. Next, let's wire up the association in the other direction in `lib/hello/orders/line_item.ex`:\n\n```diff\n schema \"order_line_items\" do\n field :price, :decimal\n field :quantity, :integer\n- field :order_id, :id\n- field :product_id, :id\n\n+ belongs_to :order, Hello.Orders.Order\n+ belongs_to :product, Hello.Catalog.Product\n\n timestamps(type: :utc_datetime)\n end\n```\n\nWe used `belongs_to` to associate line items to orders and products. With our associations in place, we can start integrating the web interface into our order process. Open up your router `lib/hello_web/router.ex` and add the following line:\n\n```diff\n scope \"/\", HelloWeb do\n pipe_through [:browser, :require_authenticated_user]\n\n resources \"/cart_items\", CartItemController, only: [:create, :delete]\n\n get \"/cart\", CartController, :show\n put \"/cart\", CartController, :update\n\n+ resources \"/orders\", OrderController, only: [:create, :show]\n end\n```\n\nWe wired up `create` and `show` routes for our generated `OrderController`, since these are the only actions we need at the moment. With our routes in place, we can now migrate up:\n\n```console\n$ mix ecto.migrate\n\n17:14:37.715 [info] == Running 20250209214612 Hello.Repo.Migrations.CreateOrders.change/0 forward\n\n17:14:37.720 [info] create table orders\n\n17:14:37.755 [info] == Migrated 20250209214612 in 0.0s\n\n17:14:37.784 [info] == Running 20250209215050 Hello.Repo.Migrations.CreateOrderLineItems.change/0 forward\n\n17:14:37.785 [info] create table order_line_items\n\n17:14:37.795 [info] create index order_line_items_order_id_index\n\n17:14:37.796 [info] create index order_line_items_product_id_index\n\n17:14:37.798 [info] == Migrated 20250209215050 in 0.0s\n```\n\nBefore we render information about our orders, we need to ensure our order data is fully populated and can be looked up by a current user. Open up your orders context in `lib/hello/orders.ex` and adjust your `get_order!/2` to include a preload:\n\n```diff\n def get_order!(%Scope{} = scope, id) do\n- Repo.get_by!(Order, id: id, user_id: scope.user.id)\n+ Order\n+ |> Repo.get_by!(id: id, user_id: scope.user.id)\n+ |> Repo.preload([line_items: [:product]])\n end\n```\n\nTo complete an order, our cart page can issue a POST to the `OrderController.create` action, but we need to implement the operations and logic to actually complete an order. Like before, we'll start at the web interface. Create a new file at `lib/hello_web/controllers/order_controller.ex` and key this in:\n\n```elixir\ndefmodule HelloWeb.OrderController do\n use HelloWeb, :controller\n\n alias Hello.Orders\n\n def create(conn, _) do\n case Orders.complete_order(conn.assigns.current_scope, conn.assigns.cart) do\n {:ok, order} ->\n conn\n |> put_flash(:info, \"Order created successfully.\")\n |> redirect(to: ~p\"/orders/#{order}\")\n\n {:error, _reason} ->\n conn\n |> put_flash(:error, \"There was an error processing your order\")\n |> redirect(to: ~p\"/cart\")\n end\n end\nend\n```\n\nWe wrote the `create` action to call an as-yet-implemented `Orders.complete_order/2` function. Our code is technically \"creating\" an order, but it's important to step back and consider the naming of your interfaces. The act of *completing* an order is extremely important in our system. Money changes hands in a transaction, physical goods could be automatically shipped, etc. Such an operation deserves a better, more obvious function name, such as `complete_order`. If the order is completed successfully we redirect to the show page, otherwise a flash error is shown as we redirect back to the cart page.\n\nHere is also a good opportunity to highlight that contexts can naturally work with data defined by other contexts too. This will be especially common with data that is used throughout the application, such as the cart here (but it can also be the current user or the current project, and so forth, depending on your project).\n\nNow we can implement our `Orders.complete_order/2` function. To complete an order, our job will require a few operations:\n\n 1. A new order record must be persisted with the total price of the order\n 2. All items in the cart must be transformed into new order line items records\n with quantity and point-in-time product price information\n 3. After successful order insert (and eventual payment), items must be pruned\n from the cart\n\nFrom our requirements alone, we can start to see why a generic `create_order` function doesn't cut it. Let's implement this new function in `lib/hello/orders.ex`:\n\n```elixir\n alias Hello.Orders.LineItem\n alias Hello.ShoppingCart\n\n def complete_order(%Scope{} = scope, %ShoppingCart.Cart{} = cart) do\n true = cart.user_id == scope.user.id\n\n line_items =\n Enum.map(cart.items, fn item ->\n %{\n product_id: item.product_id,\n price: item.product.price,\n quantity: item.quantity\n }\n end)\n\n order_changeset =\n Ecto.Changeset.change(%Order{}, %{\n user_id: scope.user.id,\n total_price: ShoppingCart.total_cart_price(cart),\n line_items: line_items\n })\n\n Repo.transact(fn ->\n with {:ok, order} <- Repo.insert(order_changeset),\n {:ok, _cart} <- ShoppingCart.prune_cart_items(scope, cart) do\n {:ok, order}\n end\n end)\n |> case do\n {:ok, order} ->\n broadcast_order(scope, {:created, order})\n {:ok, order}\n \n {:error, reason} ->\n {:error, reason}\n end\n end\n```\n\nWe started by mapping the `%ShoppingCart.CartItem{}`'s in our shopping cart into a map of order line items structs. The job of the order line item record is to capture the price of the product *at payment transaction time*, so we reference the product's price here. Next, we create a bare order changeset with `Ecto.Changeset.change/2` and associate our user UUID, set our total price calculation, and place our order line items in the changeset. With a fresh order changeset ready to be inserted, we now make use of `Repo.transact/2` to execute our operations in a database transaction. We start by inserting the order, followed by a step that prunes all items from the user’s cart. The function wrapped inside `Repo.transact/2` must either return `{:ok, result}` or error, which halts and rolls back the transaction. Running the transaction will execute these operations in sequence, and we return the result to the caller once completed.\n\nTo close out our order completion, we need to implement the `ShoppingCart.prune_cart_items/1` function in `lib/hello/shopping_cart.ex`:\n\n```elixir\n def prune_cart_items(%Scope{} = scope, %Cart{} = cart) do\n {_, _} = Repo.delete_all(from(i in CartItem, where: i.cart_id == ^cart.id))\n {:ok, get_cart(scope)}\n end\n```\n\nOur new function accepts the cart struct and issues a `Repo.delete_all` which accepts a query of all items for the provided cart. We return a success result by simply reloading the pruned cart to the caller. With our context complete, we now need to show the user their completed order. Head back to your order controller and add the `show/2` action:\n\n```elixir\n def show(conn, %{\"id\" => id}) do\n order = Orders.get_order!(conn.assigns.current_scope, id)\n render(conn, :show, order: order)\n end\n```\n\nWe added the show action to pass our `conn.assigns.current_scope` to `get_order!` which authorizes orders to be viewable only by the owner of the order. Next, we can implement the view and template. Create a new view file at `lib/hello_web/controllers/order_html.ex` with the following content:\n\n```elixir\ndefmodule HelloWeb.OrderHTML do\n use HelloWeb, :html\n\n embed_templates \"order_html/*\"\nend\n```\nNext we can create the template at `lib/hello_web/controllers/order_html/show.html.heex`:\n\n```heex\n\n <.header>\n Thank you for your order!\n <:subtitle>\n Email: {@current_scope.user.email}\n \n \n\n <.table id=\"items\" rows={@order.line_items}>\n <:col :let={item} label=\"Title\">{item.product.title}\n <:col :let={item} label=\"Quantity\">{item.quantity}\n <:col :let={item} label=\"Price\">\n {HelloWeb.CartHTML.currency_to_str(item.price)}\n \n \n\n Total price:\n {HelloWeb.CartHTML.currency_to_str(@order.total_price)}\n\n <.button navigate={~p\"/products\"}>Back to products\n\n```\n\nTo show our completed order, we displayed the order's user, followed by the line item listing with product title, quantity, and the price we \"transacted\" when completing the order, along with the total price.\n\nOur last addition will be to add the \"complete order\" button to our cart page to allow completing an order. Add the following button to the <.header> of the cart show template in `lib/hello_web/controllers/cart_html/show.html.heex`:\n\n```diff\n <.header>\n My Cart\n+ <:actions>\n+ <.button href={~p\"/orders\"} method=\"post\">\n+ Complete order\n+ \n+ \n \n```\n\nWe added a link with `method=\"post\"` to send a POST request to our `OrderController.create` action. If we head back to our cart page at [`http://localhost:4000/cart`](http://localhost:4000/cart) and complete an order, we'll be greeted by our rendered template:\n\n```text\nThank you for your order!\n\nUser uuid: 08964c7c-908c-4a55-bcd3-9811ad8b0b9d\nTitle Quantity Price\nMetaprogramming Elixir 2 $15.00\n\nTotal price: $30.00\n```\n\nWe haven't added payments, but we can already see how our `ShoppingCart` and `Orders` context splitting is driving us towards a maintainable solution. With our cart items separated from our order line items, we are well equipped in the future to add payment transactions, cart price detection, and more.\n\nGreat work!\n"
},
{
"path": "guides/data_modelling/your_first_context.md",
"content": "# 2. Your First Context\n\nAn ecommerce platform has wide-reaching coupling across a codebase so it's important to think about writing well-defined modules. With that in mind, our goal is to build a product catalog API that handles creating, updating, and deleting the products available in our system. We'll start off with the basic features of showcasing our products, and we will add shopping cart features later. We'll see how starting with a solid foundation with isolated boundaries allows us to grow our application naturally as we add functionality.\n\nPhoenix includes the `mix phx.gen.html`, `mix phx.gen.json`, `mix phx.gen.live`, and `mix phx.gen.context` generators that apply the ideas of isolating functionality in our applications into contexts. These generators are a great way to hit the ground running while Phoenix nudges you in the right direction to grow your application. Let's put these tools to use for our new product catalog context.\n\nWhen we run the generators, the context name is optional, and Phoenix will automatically use the plural name as the context module. This allows us to keep moving forward when starting out or when it is not yet clear how the different parts of our system relate to each other. Luckily, the needs of ecommerce systems are well defined nowadays, so it provides an excellent ground for us to design with intent. So let's take a step back and think about the different parts of our system.\n\nWe know that we'll have products to showcase on pages for sale, along with descriptions, pricing, etc. Along with selling products, we know we'll need to support carting, order checkout, and so on. While the products being purchased are related to the cart and checkout processes, showcasing a product and managing the *exhibition* of our products is distinctly different than tracking what a user has placed in their cart or how an order is placed. A `Catalog` context is a natural place for the management of our product details and the showcasing of those products we have for sale.\n\n## Starting with generators\n\nTo jump-start our catalog context, we'll use `mix phx.gen.html` which creates a context module that wraps up Ecto access for creating, updating, and deleting products, along with web files like controllers and templates for the web interface into our context. Run the following command at your project root:\n\n```console\n$ mix phx.gen.html Catalog Product products title:string \\\ndescription:string price:decimal views:integer\n```\nAfter executing the command, you should see output similar to the following:\n\n```console\n* creating lib/hello_web/controllers/product_controller.ex\n* creating lib/hello_web/controllers/product_html/edit.html.heex\n* creating lib/hello_web/controllers/product_html/index.html.heex\n* creating lib/hello_web/controllers/product_html/new.html.heex\n* creating lib/hello_web/controllers/product_html/show.html.heex\n* creating lib/hello_web/controllers/product_html/product_form.html.heex\n* creating lib/hello_web/controllers/product_html.ex\n* creating test/hello_web/controllers/product_controller_test.exs\n* creating lib/hello/catalog/product.ex\n* creating priv/repo/migrations/20250201185747_create_products.exs\n* creating lib/hello/catalog.ex\n* injecting lib/hello/catalog.ex\n* creating test/hello/catalog_test.exs\n* injecting test/hello/catalog_test.exs\n* creating test/support/fixtures/catalog_fixtures.ex\n* injecting test/support/fixtures/catalog_fixtures.ex\n\nAdd the resource to your browser scope in lib/hello_web/router.ex:\n\n resources \"/products\", ProductController\n\nRemember to update your repository by running migrations:\n\n $ mix ecto.migrate\n```\n\nPhoenix generated the web files as expected in `lib/hello_web/`. We can also see our context functions were generated inside a `lib/hello/catalog.ex` file and our product schema file is placed in the directory of the same name. Note the difference between `lib/hello` and `lib/hello_web`. We have a `Catalog` module to serve as the public API for product catalog functionality, as well as a `Catalog.Product` struct, which is an Ecto schema for casting and validating product data. Phoenix also provided web and context tests for us, it also included test helpers for creating entities via the `Hello.Catalog` context, which we'll look at later. For now, let's follow the instructions and add the route according to the console instructions, in `lib/hello_web/router.ex`:\n\n```diff\n scope \"/\", HelloWeb do\n pipe_through :browser\n\n get \"/\", PageController, :index\n+ resources \"/products\", ProductController\n end\n```\n\nWith the new route in place, Phoenix reminds us to update our repo by running `mix ecto.migrate`, but first we need to make a few tweaks to the generated migration in `priv/repo/migrations/*_create_products.exs`:\n\n```diff\n def change do\n create table(:products) do\n add :title, :string\n add :description, :string\n- add :price, :decimal\n+ add :price, :decimal, precision: 15, scale: 6, null: false\n- add :views, :integer\n+ add :views, :integer, default: 0, null: false\n\n timestamps(type: :utc_datetime)\n end\n```\n\nWe modified our price column to a specific precision of 15, scale of 6, along with a not-null constraint. This ensures we store currency with proper precision for any mathematical operations we may perform. Next, we added a default value and not-null constraint to our views count. With our changes in place, we're ready to migrate up our database. Let's do that now:\n\n```console\n$ mix ecto.migrate\n14:09:02.260 [info] == Running 20250201185747 Hello.Repo.Migrations.CreateProducts.change/0 forward\n\n14:09:02.262 [info] create table products\n\n14:09:02.273 [info] == Migrated 20250201185747 in 0.0s\n```\n\nBefore we jump into the generated code, let's start the server with `mix phx.server` and visit [http://localhost:4000/products](http://localhost:4000/products). Let's follow the \"New Product\" link and click the \"Save\" button without providing any input. When we submit the form, we can see all the validation errors inline with the inputs. Nice! Out of the box, the context generator included the schema fields in our form template and we can see our default validations for required inputs are in effect. Let's enter some example product data and resubmit the form:\n\n```text\nProduct created successfully.\n\nTitle: Metaprogramming Elixir\nDescription: Write Less Code, Get More Done (and Have Fun!)\nPrice: 15.000000\nViews: 0\n```\n\nIf we follow the \"Back\" link, we get a list of all products, which should contain the one we just created. Likewise, we can update this record or delete it. Now that we've seen how it works in the browser, it's time to take a look at the generated code.\n\n> #### Naming things is hard {: .tip}\n>\n> When starting a web application, it may be hard to draw lines or name its different contexts, especially when the business domain you are working with is not as well established as ecommerce.\n>\n> For those reasons, Phoenix generators allow you to skip the context name, which is really helpful when you're stuck or still exploring your business domain. For example, our code above would work the same if we used the default `Products` context for managing products and it would still allow us to organically discover other resources that belong to the `Products` context, such as categories or image galleries.\n>\n> We also advise against being too smart when naming your contexts. Pick a name that is clear and obvious to everyone who works (and might work) in the project. As your application grows and the different parts of your system become clear, you can simply rename the context or move resources around. The beauty of Elixir modules is moving them around should be simply a matter of renaming the module names and their callers (and renaming the files for consistency).\n\n## Grokking generated code\n\nThat little `mix phx.gen.html` command packed a surprising punch. We got a lot of functionality out-of-the-box for creating, updating, and deleting products in our catalog. This is far from a full-featured app, but remember, generators are first and foremost learning tools and a starting point for you to begin building real features. Code generation can't solve all your problems, but it will teach you the ins and outs of Phoenix and nudge you towards the proper mindset when designing your application.\n\nLet's first check out the `ProductController` that was generated in `lib/hello_web/controllers/product_controller.ex`:\n\n```elixir\ndefmodule HelloWeb.ProductController do\n use HelloWeb, :controller\n\n alias Hello.Catalog\n alias Hello.Catalog.Product\n\n def index(conn, _params) do\n products = Catalog.list_products()\n render(conn, :index, products: products)\n end\n\n def new(conn, _params) do\n changeset = Catalog.change_product(%Product{})\n render(conn, :new, changeset: changeset)\n end\n\n def create(conn, %{\"product\" => product_params}) do\n case Catalog.create_product(product_params) do\n {:ok, product} ->\n conn\n |> put_flash(:info, \"Product created successfully.\")\n |> redirect(to: ~p\"/products/#{product}\")\n\n {:error, %Ecto.Changeset{} = changeset} ->\n render(conn, :new, changeset: changeset)\n end\n end\n\n def show(conn, %{\"id\" => id}) do\n product = Catalog.get_product!(id)\n render(conn, :show, product: product)\n end\n ...\nend\n```\n\nWe've seen how controllers work in our [controller guide](controllers.html), so the code probably isn't too surprising. What is worth noticing is how our controller calls into the `Catalog` context. We can see that the `index` action fetches a list of products with `Catalog.list_products/0`, and how products are persisted in the `create` action with `Catalog.create_product/1`. We haven't yet looked at the catalog context, so we don't yet know how product fetching and creation is happening under the hood – *but that's the point*. Our Phoenix controller is the web interface into our greater application. It shouldn't be concerned with the details of how products are fetched from the database or persisted into storage. We only care about telling our application to perform some work for us. This is great because our business logic and storage details are decoupled from the web layer of our application. If we move to a full-text storage engine later for fetching products instead of a SQL query, our controller doesn't need to be changed. Likewise, we can reuse our context code from any other interface in our application, be it a channel, mix task, or long-running process importing CSV data.\n\nIn the case of our `create` action, when we successfully create a product, we use `Phoenix.Controller.put_flash/3` to show a success message, and then we redirect to the router's product show page. Conversely, if `Catalog.create_product/1` fails, we render our `\"new.html\"` template and pass along the Ecto changeset for the template to lift error messages from.\n\nNext, let's dig deeper and check out our `Catalog` context in `lib/hello/catalog.ex`:\n\n```elixir\ndefmodule Hello.Catalog do\n @moduledoc \"\"\"\n The Catalog context.\n \"\"\"\n\n import Ecto.Query, warn: false\n alias Hello.Repo\n\n alias Hello.Catalog.Product\n\n @doc \"\"\"\n Returns the list of products.\n\n ## Examples\n\n iex> list_products()\n [%Product{}, ...]\n\n \"\"\"\n def list_products do\n Repo.all(Product)\n end\n ...\nend\n```\n\nThis module will be the public API for all product catalog functionality in our system. For example, in addition to product detail management, we may also handle product category classification and product variants for things like optional sizing, trims, etc. If we look at the `list_products/0` function, we can see the private details of product fetching. And it's super simple. We have a call to `Repo.all(Product)`. We saw how Ecto repo queries worked in the [Ecto guide](ecto.html), so this call should look familiar. Our `list_products` function is a generalized function name specifying the *intent* of our code – namely to list products. The details of that intent where we use our Repo to fetch the products from our PostgreSQL database, are hidden from our callers. This is a common theme we'll see reiterated as we use the Phoenix generators. Phoenix will push us to think about where we have different responsibilities in our application, and then to wrap up those different areas behind well-named modules and functions that make the intent of our code clear, while encapsulating the details.\n\nNow we know how data is fetched, but how are products persisted? Let's take a look at the `Catalog.create_product/1` function:\n\n```elixir\n @doc \"\"\"\n Creates a product.\n\n ## Examples\n\n iex> create_product(%{field: value})\n {:ok, %Product{}}\n\n iex> create_product(%{field: bad_value})\n {:error, %Ecto.Changeset{}}\n\n \"\"\"\n def create_product(attrs) do\n %Product{}\n |> Product.changeset(attrs)\n |> Repo.insert()\n end\n```\n\nThere's more documentation than code here, but a couple of things are important to highlight. First, we can see again that our Ecto Repo is used under the hood for database access. You probably also noticed the call to `Product.changeset/2`. We talked about changesets before, and now we see them in action in our context.\n\nIf we open up the `Product` schema in `lib/hello/catalog/product.ex`, it will look immediately familiar:\n\n```elixir\ndefmodule Hello.Catalog.Product do\n use Ecto.Schema\n import Ecto.Changeset\n\n schema \"products\" do\n field :description, :string\n field :price, :decimal\n field :title, :string\n field :views, :integer\n\n timestamps(type: :utc_datetime)\n end\n\n @doc false\n def changeset(product, attrs) do\n product\n |> cast(attrs, [:title, :description, :price, :views])\n |> validate_required([:title, :description, :price, :views])\n end\nend\n```\n\nThis is just what we saw before when we ran `mix phx.gen.schema`, except here we see a `@doc false` above our `changeset/2` function. This tells us that while this function is publicly callable, it's not part of the public context API. Callers that build changesets do so via the context API. For example, `Catalog.create_product/1` calls into our `Product.changeset/2` to build the changeset from user input. Callers, such as our controller actions, do not access `Product.changeset/2` directly. All interaction with our product changesets is done through the public `Catalog` context.\n\n## Adding Catalog functions\n\nAs we've seen, your context modules are dedicated modules that expose and group related functionality. Phoenix generates generic functions, such as `list_products` and `update_product`, but they only serve as a basis for you to grow your business logic and application from. Let's add one of the basic features of our catalog by tracking product page view count.\n\nFor any ecommerce system, the ability to track how many times a product page has been viewed is essential for marketing, suggestions, ranking, etc. While we could try to use the existing `Catalog.update_product` function, along the lines of `Catalog.update_product(product, %{views: product.views + 1})`, this would not only be prone to race conditions, but it would also require the caller to know too much about our Catalog system. To see why the race condition exists, let's walk through the possible execution of events:\n\nIntuitively, you would assume the following events:\n\n 1. User 1 loads the product page with count of 13\n 2. User 1 saves the product page with count of 14\n 3. User 2 loads the product page with count of 14\n 4. User 2 saves the product page with count of 15\n\nWhile in practice this would happen:\n\n 1. User 1 loads the product page with count of 13\n 2. User 2 loads the product page with count of 13\n 3. User 1 saves the product page with count of 14\n 4. User 2 saves the product page with count of 14\n\nThe race conditions would make this an unreliable way to update the existing table since multiple callers may be updating out of date view values. There's a better way.\n\nLet's think of a function that describes what we want to accomplish. Here's how we would like to use it:\n\n```elixir\nproduct = Catalog.inc_page_views(product)\n```\n\nThat looks great. Our callers will have no confusion over what this function does, and we can wrap up the increment in an atomic operation to prevent race conditions.\n\nOpen up your catalog context (`lib/hello/catalog.ex`), and add this new function:\n\n```elixir\n def inc_page_views(%Product{} = product) do\n {1, [%Product{views: views}]} =\n from(p in Product, where: p.id == ^product.id, select: [:views])\n |> Repo.update_all(inc: [views: 1])\n\n put_in(product.views, views)\n end\n```\n\nWe built a query for fetching the current product given its ID which we pass to `Repo.update_all`. Ecto's `Repo.update_all` allows us to perform batch updates against the database, and is perfect for atomically updating values, such as incrementing our views count. The result of the repo operation returns the number of updated records, along with the selected schema values specified by the `select` option. When we receive the new product views, we use `put_in(product.views, views)` to place the new view count within the product struct.\n\nWith our context function in place, let's make use of it in our product controller. Update your `show` action in `lib/hello_web/controllers/product_controller.ex` to call our new function:\n\n```elixir\n def show(conn, %{\"id\" => id}) do\n product =\n id\n |> Catalog.get_product!()\n |> Catalog.inc_page_views()\n\n render(conn, :show, product: product)\n end\n```\n\nWe modified our `show` action to pipe our fetched product into `Catalog.inc_page_views/1`, which will return the updated product. Then we rendered our template just as before. Let's try it out. Refresh one of your product pages a few times and watch the view count increase.\n\nWe can also see our atomic update in action in the ecto debug logs:\n\n```text\n[debug] QUERY OK source=\"products\" db=0.5ms idle=834.5ms\nUPDATE \"products\" AS p0 SET \"views\" = p0.\"views\" + $1 WHERE (p0.\"id\" = $2) RETURNING p0.\"views\" [1, 1]\n```\n\nGood work!\n\nAs we've seen, designing with contexts gives you a solid foundation to grow your application from. Using discrete, well-defined APIs that expose the intent of your system allows you to write more maintainable applications with reusable code. Now that we know how to start extending our context API, let's explore handling relationships within a context.\n"
},
{
"path": "guides/deployment/deployment.md",
"content": "# Introduction to Deployment\n\nOnce we have a working application, we're ready to deploy it. If you're not quite finished with your own application, don't worry. Just follow the [Up and Running Guide](up_and_running.html) to create a basic application to work with.\n\nWhen preparing an application for deployment, there are three main steps:\n\n * Handling of your application secrets\n * Compiling your application assets\n * Starting your server in production\n\nIn this guide, we will learn how to get the production environment running locally. You can use the same techniques in this guide to run your application in production, but depending on your deployment infrastructure, extra steps will be necessary.\n\nAs an example of deploying to other infrastructures, we also discuss four different approaches in our guides: using [Elixir's releases](releases.html) with `mix release`, [using Gigalixir](gigalixir.html), [using Fly](fly.html), and [using Heroku](heroku.html). We've also included links to deploying Phoenix on other platforms under [Community Deployment Guides](#community-deployment-guides). Finally, the release guide has a sample Dockerfile you can use if you prefer to deploy with container technologies.\n\nLet's explore those steps above one by one.\n\n## Handling of your application secrets\n\nAll Phoenix applications have data that must be kept secure, for example, the username and password for your production database, and the secret Phoenix uses to sign and encrypt important information. The general recommendation is to keep those in environment variables and load them into your application. This is done in `config/runtime.exs` (formerly `config/prod.secret.exs` or `config/releases.exs`), which is responsible for loading secrets and configuration from environment variables at boot time.\n\nTherefore, you need to make sure the proper relevant variables are set in production:\n\n```console\n$ mix phx.gen.secret\nREALLY_LONG_SECRET\n$ export SECRET_KEY_BASE=REALLY_LONG_SECRET\n$ export DATABASE_URL=ecto://USER:PASS@HOST/database\n```\n\nDo not copy those values directly, set `SECRET_KEY_BASE` according to the result of `mix phx.gen.secret` and `DATABASE_URL` according to your database address.\n\nIf for some reason you do not want to rely on environment variables, you can hard code the secrets in your `config/runtime.exs` but make sure not to check the file into your version control system.\n\nWith your secret information properly secured, it is time to configure assets!\n\nBefore taking this step, we need to do one bit of preparation. Since we will be readying everything for production, we need to do some setup in that environment by getting our dependencies and compiling.\n\n```console\n$ mix deps.get --only prod\n$ MIX_ENV=prod mix compile\n```\n\n## Compiling your application assets\n\nThis step is required only if you have compilable assets like JavaScript and stylesheets. By default, Phoenix uses `esbuild` but everything is encapsulated in a single `mix assets.deploy` task defined in your `mix.exs`:\n\n```console\n$ MIX_ENV=prod mix assets.deploy\nCheck your digested files at \"priv/static\".\n```\n\nAnd that is it! The Mix task by default builds the assets and then generates digests with a cache manifest file so Phoenix can quickly serve assets in production.\n\n> Note: if you run the task above in your local machine, it will generate many digested assets in `priv/static`. You can prune them by running `mix phx.digest.clean --all`.\n\nKeep in mind that, if you by any chance forget to run the steps above, Phoenix will show an error message:\n\n```console\n$ PORT=4001 MIX_ENV=prod mix phx.server\n10:50:18.732 [info] Running MyAppWeb.Endpoint with Cowboy on http://example.com\n10:50:18.735 [error] Could not find static manifest at \"my_app/_build/prod/lib/foo/priv/static/cache_manifest.json\". Run \"mix phx.digest\" after building your static files or remove the configuration from \"config/prod.exs\".\n```\n\nThe error message is quite clear: it says Phoenix could not find a static manifest. Just run the commands above to fix it or, if you are not serving or don't care about assets at all, you can just remove the `cache_static_manifest` configuration from your config.\n\n## Starting your server in production\n\nTo run Phoenix in production, we need to set the `PORT` and `MIX_ENV` environment variables when invoking `mix phx.server`:\n\n```console\n$ PORT=4001 MIX_ENV=prod mix phx.server\n10:59:19.136 [info] Running MyAppWeb.Endpoint with Cowboy on http://example.com\n```\n\nTo run in detached mode so that the Phoenix server does not stop and continues to run even if you close the terminal:\n\n```console\n$ PORT=4001 MIX_ENV=prod elixir --erl \"-detached\" -S mix phx.server\n```\n\nIn case you get an error message, please read it carefully, and open up a bug report if it is still not clear how to address it.\n\nYou can also run your application inside an interactive shell:\n\n```console\n$ PORT=4001 MIX_ENV=prod iex -S mix phx.server\n10:59:19.136 [info] Running MyAppWeb.Endpoint with Cowboy on http://example.com\n```\n\n## Putting it all together\n\nThe previous sections give an overview about the main steps required to deploy your Phoenix application. In practice, you will end-up adding steps of your own as well. For example, if you are using a database, you will also want to run `mix ecto.migrate` before starting the server to ensure your database is up to date.\n\nOverall, here is a script you can use as a starting point:\n\n```console\n# Initial setup\n$ mix deps.get --only prod\n$ MIX_ENV=prod mix compile\n\n# Compile assets\n$ MIX_ENV=prod mix assets.deploy\n\n# Custom tasks (like DB migrations)\n$ MIX_ENV=prod mix ecto.migrate\n\n# Finally run the server\n$ PORT=4001 MIX_ENV=prod mix phx.server\n```\n\nAnd that's it. Next, you can use one of our official guides to deploy:\n\n * [with Elixir's releases](releases.html)\n * [to Gigalixir](gigalixir.html), an Elixir-centric Platform as a Service (PaaS)\n * [to Fly.io](fly.html), a PaaS that deploys your servers close to your users with built-in distribution support\n * and [to Heroku](heroku.html), one of the most popular PaaS.\n\n## Clustering and Long-Polling Transports\n\nPhoenix supports two types of transports for its Socket implementation: WebSocket, and Long-Polling. When generating a Phoenix project, you can see the default configuration set in the generated `endpoint.ex` file:\n\n```elixir\nsocket \"/live\", Phoenix.LiveView.Socket,\n websocket: [connect_info: [session: @session_options]],\n longpoll: [connect_info: [session: @session_options]]\n```\n\nThis configuration tells Phoenix that both the WebSocket and the Long-Polling options are available, and based on the client's network conditions, Phoenix will first attempt to connect to the WebSocket, falling back to the Long-Poll option after the configured timeout found in the generated `app.js` file:\n\n```javascript\nlet liveSocket = new LiveSocket(\"/live\", Socket, {\n longPollFallbackMs: 2500,\n params: {_csrf_token: csrfToken}\n})\n```\n\nIf you are running more than one machine in production, which is the recommended approach in most cases, this automatic fallback comes with an important caveat. If you want Long-Polling to work properly, your application must either:\n\n1. Utilize the Erlang VM's clustering capabilities, so the default `Phoenix.PubSub` adapter can broadcast messages across nodes\n\n2. Choose a different `Phoenix.PubSub` adapter (such as `Phoenix.PubSub.Redis`)\n\n3. Or your deployment option must implement sticky sessions - ensuring that all requests for a specific session go to the same machine\n\nThe reason for this is simple. While a WebSocket is a long-lived open connection to the same machine, long-polling works by opening a request to the server, waiting for a timeout or until the open request is fulfilled, and repeating this process. In order to preserve the state of the user's connected socket and to preserve the behaviour of a socket being long-lived, the user's process is kept alive, and each long-poll request attempts to find the user's stateful process. If the stateful process is not reachable, every request will create a new process and a new state, thereby breaking the fact that the socket is long-lived and stateful.\n\n## Community Deployment Guides\n\n * [Render](https://render.com) has first class support for Phoenix applications. There are guides for hosting Phoenix with [Mix releases](https://render.com/docs/deploy-phoenix) and as a [Distributed Elixir Cluster](https://render.com/docs/deploy-elixir-cluster).\n * [Railway](https://railway.com) also provides support for Phoenix applications using [Mix releases](https://docs.railway.com/guides/phoenix).\n"
},
{
"path": "guides/deployment/fly.md",
"content": "# Deploying on Fly.io\n\nThe main goal for this guide is to get a Phoenix application running on [Fly.io](https://fly.io).\n\nFly.io maintains their own guide for Elixir/Phoenix here: [Fly.io/docs/elixir/getting-started/](https://fly.io/docs/elixir/getting-started/). We will keep this guide up but for the latest and greatest check with them!\n\n## What we'll need\n\nThe only thing we'll need for this guide is a working Phoenix application. For those of us who need a simple application to deploy, please follow the [Up and Running guide](https://hexdocs.pm/phoenix/up_and_running.html).\n\nYou can just:\n\n```console\n$ mix phx.new my_app\n```\n\n## Sections\n\nLet's separate this process into a few steps, so we can keep track of where we are.\n\n- Install the Fly.io CLI\n- Sign up for Fly.io\n- Deploy the app to Fly.io\n- Clustering your application\n- Extra Fly.io tips\n- Helpful Fly.io resources\n\n## Installing the Fly.io CLI\n\nFollow the instructions [here](https://fly.io/docs/getting-started/installing-flyctl/) to install Flyctl, the command-line interface for the Fly.io platform.\n\n## Sign up for Fly.io\n\nWe can [sign up for an account](https://fly.io/docs/getting-started/log-in-to-fly/) using the CLI.\n\n```console\n$ fly auth signup\n```\n\nOr sign in.\n\n```console\n$ fly auth login\n```\n\nFly has a [free tier](https://fly.io/docs/about/pricing/) for most applications. A credit card is required when setting up an account to help prevent abuse. See the [pricing](https://fly.io/docs/about/pricing/) page for more details.\n\n## Deploy the app to Fly.io\n\nTo tell Fly about your application, run `fly launch` in the directory with your source code. This creates and configures a Fly.io app.\n\n```console\n$ fly launch\n```\n\nThis scans your source, detects the Phoenix project, and runs `mix phx.gen.release --docker` for you! This creates a Dockerfile for you.\n\nThe `fly launch` command walks you through a few questions.\n\n- You can name the app or have it generate a random name for you.\n- Choose an organization (defaults to `personal`). Organizations are a way of sharing applications and resources between Fly.io users.\n- Choose a region to deploy to. Defaults to the nearest Fly.io region. You can check out the [complete list of regions here](https://fly.io/docs/reference/regions/).\n- Sets up a Postgres DB for you.\n- Builds the Dockerfile.\n- Deploys your application!\n\nThe `fly launch` command also created a `fly.toml` file for you. This is where you can set ENV values and other config.\n\n### Storing secrets on Fly.io\n\nYou may also have some secrets you'd like to set on your app.\n\nUse [`fly secrets`](https://fly.io/docs/reference/secrets/#setting-secrets) to configure those.\n\n```console\n$ fly secrets set MY_SECRET_KEY=my_secret_value\n```\n\n### Deploying again\n\nWhen you want to deploy changes to your application, use `fly deploy`.\n\n```console\n$ fly deploy\n```\n\nNote: On Apple Silicon (M1) computers, docker runs cross-platform builds using qemu which might not always work. If you get a segmentation fault error like the following:\n\n```console\n => [build 7/17] RUN mix deps.get --only\n => => # qemu: uncaught target signal 11 (Segmentation fault) - core dumped\n```\n\nYou can use fly's remote builder by adding the `--remote-only` flag:\n\n```console\n$ fly deploy --remote-only\n```\n\nYou can always check on the status of a deploy\n\n```console\n$ fly status\n```\n\nCheck your app logs\n\n```console\n$ fly logs\n```\n\nIf everything looks good, open your app on Fly\n\n```console\n$ fly open\n```\n\n## Clustering your application\n\nElixir and the Erlang VM have the incredible ability to be clustered together and pass messages seamlessly between nodes. Phoenix comes with all of the knobs in place, you only need to set the appropriate environment variables before deploying.\n\nIf you used `fly launch` to deploy your app, those environment variables are already in place, if not, open up `rel/env.ssh.eex` and add:\n\n```sh\nexport ERL_AFLAGS=\"-proto_dist inet6_tcp\"\nexport RELEASE_DISTRIBUTION=\"name\"\nexport RELEASE_NODE=\"${FLY_APP_NAME}-${FLY_IMAGE_REF##*-}@${FLY_PRIVATE_IP}\"\n\nexport ECTO_IPV6=\"true\"\nexport DNS_CLUSTER_QUERY=\"${FLY_APP_NAME}.internal\"\n```\n\nThe first three environment variables are managed by Elixir and the Erlang/VM:\n\n * `ERL_AFLAGS` - configures Erlang to use IPv6 for its distribution\n * `RELEASE_DISTRIBUTION` - configures Erlang to named nodes\n * `RELEASE_NODE` - attaches a name to the node, using Fly's app name and deploy reference\n\nThe last two are handled by your `config/runtime.exs`:\n\n * `ECTO_IPV6` - connect to the database using IPv6\n * `DNS_CLUSTER_QUERY` - configures your app to find other nodes using the given DNS query\n\n## Extra Fly.io tips\n\n### Getting an IEx shell into a running node\n\nElixir supports getting a IEx shell into a running production node.\n\nThere are a couple prerequisites, we first need to establish an [SSH Shell](https://fly.io/docs/flyctl/ssh/) to our machine on Fly.io.\n\nThis step sets up a root certificate for your account and then issues a certificate.\n\n```console\n$ fly ssh issue --agent\n```\n\nWith SSH configured, let's open a console.\n\n```console\n$ fly ssh console\nConnecting to my-app-1234.internal... complete\n/ #\n```\n\nIf all has gone smoothly, then you have a shell into the machine! Now we just need to launch our remote IEx shell. The deployment Dockerfile was configured to pull our application into `/app`. So the command for an app named `my_app` looks like this:\n\n```console\n$ app/bin/my_app remote\nErlang/OTP 23 [erts-11.2.1] [source] [64-bit] [smp:1:1] [ds:1:1:10] [async-threads:1]\n\nInteractive Elixir (1.11.2) - press Ctrl+C to exit (type h() ENTER for help)\niex(my_app@fdaa:0:1da8:a7b:ac4:b204:7e29:2)1>\n```\n\nNow we have a running IEx shell into our node! You can safely disconnect using CTRL+C, CTRL+C.\n\n#### Running multiple instances\n\nThere are two ways to run multiple instances.\n\n1. Scale our application to have multiple instances in one region.\n2. Add an instance to another region (multiple regions).\n\nLet's first start with a baseline of our single deployment.\n\n```console\n$ fly status\n...\nInstances\nID VERSION REGION DESIRED STATUS HEALTH CHECKS RESTARTS CREATED\nf9014bf7 26 sea run running 1 total, 1 passing 0 1h8m ago\n```\n\n#### Scaling in a single region\n\nLet's scale up to 2 instances in our current region.\n\n```console\n$ fly scale count 2\nCount changed to 2\n```\n\nChecking the status, we can see what happened.\n\n```console\n$ fly status\n...\nInstances\nID VERSION REGION DESIRED STATUS HEALTH CHECKS RESTARTS CREATED\neb4119d3 27 sea run running 1 total, 1 passing 0 39s ago\nf9014bf7 27 sea run running 1 total, 1 passing 0 1h13m ago\n```\n\nWe now have two instances in the same region.\n\nLet's make sure they are clustered together. From an IEx shell, we can ask the node we're connected to, what other nodes it can see.\n\n```console\n$ fly ssh console -C \"/app/bin/my_app remote\"\n```\n\n```elixir\niex(my-app-1234@fdaa:0:1da8:a7b:ac2:f901:4bf7:2)1> Node.list\n[:\"my-app-1234@fdaa:0:1da8:a7b:ac4:eb41:19d3:2\"]\n```\n\nThe IEx prompt is included to help show the IP address of the node we are connected to. Then getting the `Node.list` returns the other node. Our two instances are connected and clustered!\n\n#### Scaling to multiple regions\n\nFly makes it easy to deploy instances closer to your users. Through the magic of DNS, users are directed to the nearest region where your application is located. You can read more about [Fly.io regions here](https://fly.io/docs/reference/regions/).\n\nStarting back from our baseline of a single instance running in `sea` which is Seattle, Washington (US), let's add the region `ewr` which is Parsippany, NJ (US). This puts an instance on both coasts of the US.\n\n```console\n$ fly regions add ewr\nRegion Pool:\newr\nsea\nBackup Region:\niad\nlax\nsjc\nvin\n```\n\nLooking at the status shows that we're only in 1 region because our count is set to 1.\n\n```console\n$ fly status\n...\nInstances\nID VERSION REGION DESIRED STATUS HEALTH CHECKS RESTARTS CREATED\ncdf6c422 29 sea run running 1 total, 1 passing 0 58s ago\n```\n\nLet's add a 2nd instance and see it deploy to `ewr`.\n\n```console\n$ fly scale count 2\nCount changed to 2\n```\n\nNow the status shows we have two instances spread across 2 regions!\n\n```console\n$ fly status\n...\nInstances\nID VERSION REGION DESIRED STATUS HEALTH CHECKS RESTARTS CREATED\n0a8e6666 30 ewr run running 1 total, 1 passing 0 16s ago\ncdf6c422 30 sea run running 1 total, 1 passing 0 6m47s ago\n```\n\nLet's ensure they are clustered together.\n\n```console\n$ fly ssh console -C \"/app/bin/my_app remote\"\n```\n\n```elixir\niex(my-app-1234@fdaa:0:1da8:a7b:ac2:cdf6:c422:2)1> Node.list\n[:\"my-app-1234@fdaa:0:1da8:a7b:ab2:a8e:6666:2\"]\n```\n\nWe have two instances of our application deployed to the West and East coasts of the North American continent and they are clustered together! Our users will automatically be directed to the server nearest them.\n\nThe Fly.io platform has built-in distribution support making it easy to cluster distributed Elixir nodes in multiple regions.\n\n## Helpful Fly.io resources\n\nOpen the Dashboard for your account\n\n```console\n$ fly dashboard\n```\n\nDeploy your application\n\n```console\n$ fly deploy\n```\n\nShow the status of your deployed application\n\n```console\n$ fly status\n```\n\nAccess and tail the logs\n\n```console\n$ fly logs\n```\n\nScaling your application up or down\n\n```console\n$ fly scale count 2\n```\n\nRefer to the [Fly.io Elixir documentation](https://fly.io/docs/getting-started/elixir) for additional information.\n\n[The Fly.io docs](https://fly.io/docs/) covers things like:\n\n* [Status](https://fly.io/docs/flyctl/status/) and [logs](https://fly.io/docs/monitoring/logging-overview/)\n* [Custom domains](https://fly.io/docs/networking/custom-domain/)\n* [Certificates](https://fly.io/docs/networking/custom-domain-api/)\n\n## Troubleshooting\n\nSee [Troubleshooting](https://fly.io/docs/getting-started/troubleshooting/) and [Elixir Troubleshooting](https://fly.io/docs/elixir/the-basics/troubleshooting/)\n\nVisit the [Fly.io Community](https://community.fly.io/) to find solutions and ask questions.\n"
},
{
"path": "guides/deployment/gigalixir.md",
"content": "# Deploying on Gigalixir\n\nOur main goal for this guide is to get a Phoenix application running on Gigalixir.\n\n## What we'll need\n\nThe only thing we'll need for this guide is a working Phoenix application. For those of us who need a simple application to deploy, please follow the [Up and Running guide](https://hexdocs.pm/phoenix/up_and_running.html).\n\n## Steps\n\nLet's separate this process into a few steps, so we can keep track of where we are.\n\n- Initialize Git repository\n- Install the Gigalixir CLI\n- Sign up for Gigalixir\n- Create and set up Gigalixir application\n- Provision a database\n- Make our project ready for Gigalixir\n- Deploy time!\n- Useful Gigalixir commands\n\n## Initializing Git repository\n\nIf you haven't already, we'll need to commit our files to git. We can do so by running the following commands in our project directory:\n\n```console\n$ git init\n$ git add .\n$ git commit -m \"Initial commit\"\n```\n\n## Installing the Gigalixir CLI\n\nFollow the instructions [here](https://gigalixir.com/docs/getting-started-guide/) to install the command-line interface for your platform.\n\n## Signing up for Gigalixir\n\nWe can sign up for an account at [gigalixir.com](https://gigalixir.com) or with the CLI. Let's use the CLI.\n\n```console\n$ gigalixir signup\n\n# or with a Google account\n$ gigalixir signup:google\n```\n\nGigalixir’s free tier does not require a credit card and comes with 1 app instance and 1 PostgreSQL database for free, but please consider upgrading to a paid plan if you are running a production application.\n\nNext, let's login\n\n```console\n$ gigalixir login\n\n# or with a Google account\n$ gigalixir login:google\n```\n\nAnd verify\n\n```console\n$ gigalixir account\n```\n\n## Creating and setting up our Gigalixir application\n\nThere are two different ways to deploy a Phoenix app on Gigalixir: with mix or with Elixir's releases. In this guide, we'll be using Elixir's releases because it is the recommended way. For more information, see [Elixir Releases vs Mix](https://gigalixir.com/docs/modify-app/#elixir-releases-vs-mix). If you want to deploy with the mix method, follow the [Phoenix deploy with Mix Guide](https://gigalixir.com/docs/getting-started-guide/phoenix-mix-deploy).\n\n### Creating a Gigalixir application\n\nLet's create a Gigalixir application\n\n```console\n$ gigalixir create -n \"your-app-name\"\n```\n\nNote: the app name cannot be changed afterwards. A random name is used if you do not provide one.\n\n### Specifying versions\n\nGigalixir requires that you specify the Erlang and Elixir versions you intend to use. It's generally a good idea to run the same version in production as you do in development. For example:\n\n```console\n$ echo 'elixir_version=1.17.2' > elixir_buildpack.config\n$ echo 'erlang_version=27.0' >> elixir_buildpack.config\n$ git add elixir_buildpack.config\n```\n\nGigalixir will use the latest nodejs version if you do not specify a version. If you want to specify your nodejs version, you can do so like this:\n\n```console\n$ echo 'node_version=22.7.0' > phoenix_static_buildpack.config\n$ git add elixir_buildpack.config phoenix_static_buildpack.config assets/package.json\n```\n\nFinally, don't forget to commit:\n\n```console\n$ git commit -m \"Set versions\"\n```\n\n## Provisioning a database\n\nLet's provision a database for our app. For a free database, run the following command\n\n```console\n$ gigalixir pg:create --free\n```\n\nFor a production ready database, be sure to upgrade your account to the Standard Tier and create a Standard tier database\n```console\n$ gigalixir account:upgrade\n$ gigalixir pg:create\n```\n\nVerify the database was created\n\n```console\n$ gigalixir pg\n```\n\nVerify that a `DATABASE_URL` and `POOL_SIZE` were created\n\n```console\n$ gigalixir config\n```\n\n## Making our Project ready for Gigalixir\n\nThere's nothing we need to do to get our app running on Gigalixir, but for a production app, you probably want to enforce SSL.\n\n### Database Connection Security\n\nYou may also want to use SSL for your database connection. In your `config/runtime.exs`:\n\n```elixir\nssl: [\n verify: :verify_peer,\n cacerts: :public_key.cacerts_get()\n]\n```\n\n## Deploy Time!\n\nOur project is now ready to be deployed on Gigalixir.\nBe sure you have everything committed to git and run the following command:\n\n```console\n$ git push gigalixir\n```\n\nCheck the status of your deploy and wait until the app is `Healthy`\n\n```console\n$ gigalixir ps\n```\n\nRun migrations\n\n```console\n$ gigalixir ps:migrate\n```\n\nCheck your app logs\n\n```console\n$ gigalixir logs\n```\n\nIf everything looks good, let's take a look at your app running on Gigalixir\n\n```console\n$ gigalixir open\n```\n\n## Useful Gigalixir Commands\n\nOpen a remote console\n\n```console\n$ gigalixir account:ssh_keys:add \"$(cat ~/.ssh/id_rsa.pub)\"\n$ gigalixir ps:remote_console\n```\n\nTo set up clustering, see [Clustering Nodes](https://gigalixir.com/docs/cluster)\n\nFor custom domains, scaling, jobs and other features, see the [Gigalixir Documentation](https://gigalixir.com/docs/).\n\n## Troubleshooting\n\nSee [Troubleshooting](https://gigalixir.com/docs/troubleshooting) and the [FAQ](https://gigalixir.com/docs/faq)\n\nAlso, don't hesitate to email [help@gigalixir.com](mailto:help@gigalixir.com) or [request an invitation](https://elixir-lang.slack.com/join/shared_invite/zt-1f13hz7mb-N4KGjF523ONLCcHfb8jYgA#/shared-invite/email) and join the #gigalixir channel on [Slack](https://elixir-lang.slack.com).\n"
},
{
"path": "guides/deployment/heroku.md",
"content": "# Deploying on Heroku\n\nOur main goal for this guide is to get a Phoenix application running on Heroku.\n\n## What we'll need\n\nThe only thing we'll need for this guide is a working Phoenix application. For those of us who need a simple application to deploy, please follow the [Up and Running guide](https://hexdocs.pm/phoenix/up_and_running.html).\n\n## Limitations\n\nHeroku is a great platform and Elixir performs well on it. However, you may run into limitations if you plan to leverage advanced features provided by Elixir and Phoenix, such as:\n\n- Connections are limited.\n - Heroku [limits the number of simultaneous connections](https://devcenter.heroku.com/articles/http-routing#request-concurrency) as well as the [duration of each connection](https://devcenter.heroku.com/articles/limits#http-timeouts). It is common to use Elixir for real-time apps which need lots of concurrent, persistent connections, and Phoenix is capable of [handling over 2 million connections on a single server](https://www.phoenixframework.org/blog/the-road-to-2-million-websocket-connections).\n\n- Distributed clustering is not possible.\n - Heroku [firewalls dynos off from one another](https://devcenter.heroku.com/articles/dynos#networking). This means things like [distributed Phoenix channels](https://dockyard.com/blog/2016/01/28/running-elixir-and-phoenix-projects-on-a-cluster-of-nodes) and [distributed tasks](https://hexdocs.pm/elixir/distributed-tasks.html) will need to rely on something like Redis instead of Elixir's built-in distribution.\n\n- In-memory state such as those in [Agents](https://hexdocs.pm/elixir/agents.html), [GenServers](https://hexdocs.pm/elixir/genservers.html), and [ETS](https://hexdocs.pm/elixir/erlang-term-storage.html) will be lost every 24 hours.\n - Heroku [restarts dynos](https://devcenter.heroku.com/articles/dynos#restarting) every 24 hours regardless of whether the node is healthy.\n\n- [The built-in observer](https://hexdocs.pm/elixir/debugging.html#observer) can't be used with Heroku.\n - Heroku does allow for connection into your dyno, but you won't be able to use the observer to watch the state of your dyno.\n\nIf you are just getting started, or you don't expect to use the features above, Heroku should be enough for your needs. For instance, if you are migrating an existing application running on Heroku to Phoenix, keeping a similar set of features, Elixir will perform just as well or even better than your current stack.\n\nIf you want a platform-as-a-service without these limitations, there are alternatives listed in the sidebar and also generally available elsewhere. If you would rather deploy to a cloud platform, such as EC2, Google Cloud, etc, consider using `mix release`.\n\n## Steps\n\nLet's separate this process into a few steps, so we can keep track of where we are.\n\n- Initialize Git repository\n- Sign up for Heroku\n- Install the Heroku Toolbelt\n- Create and set up Heroku application\n- Make our project ready for Heroku\n- Deploy time!\n- Useful Heroku commands\n\n## Initializing Git repository\n\n[Git](https://git-scm.com/) is a popular decentralized revision control system and is also used to deploy apps to Heroku.\n\nBefore we can push to Heroku, we'll need to initialize a local Git repository and commit our files to it. We can do so by running the following commands in our project directory:\n\n```console\n$ git init\n$ git add .\n$ git commit -m \"Initial commit\"\n```\n\nHeroku offers some great information on how it is using Git [here](https://devcenter.heroku.com/articles/git#prerequisites-install-git-and-the-heroku-cli).\n\n## Signing up for Heroku\n\nSigning up to Heroku is very simple, just head over to [https://signup.heroku.com/](https://signup.heroku.com/) and fill in the form.\n\nThe Free plan will give us one web [dyno](https://devcenter.heroku.com/articles/dynos) and one worker dyno, as well as a PostgreSQL and Redis instance for free.\n\nThese are meant to be used for testing and development, and come with some limitations. In order to run a production application, please consider upgrading to a paid plan.\n\n## Installing the Heroku Toolbelt\n\nOnce we have signed up, we can download the correct version of the Heroku Toolbelt for our system [here](https://toolbelt.heroku.com/).\n\nThe Heroku CLI, part of the Toolbelt, is useful to create Heroku applications, list currently running dynos for an existing application, tail logs or run one-off commands (mix tasks for instance).\n\n## Create and Set Up Heroku Application\n\nThere are two different ways to deploy a Phoenix app on Heroku. We could use Heroku buildpacks or their container stack. The difference between these two approaches is in how we tell Heroku to treat our build. In buildpack case, we need to update our apps configuration on Heroku to use Phoenix/Elixir specific buildpacks. On container approach, we have more control on how we want to set up our app, and we can define our container image using `Dockerfile` and `heroku.yml`. This section will explore the buildpack approach. In order to use Dockerfile, it is often recommended to convert our app to use releases, which we will describe later on.\n\n### Create Application\n\nA [buildpack](https://devcenter.heroku.com/articles/buildpacks) is a convenient way of packaging framework and/or runtime support. Phoenix requires 2 buildpacks to run on Heroku, the first adds basic Elixir support and the second adds Phoenix specific commands.\n\nWith the Toolbelt installed, let's create the Heroku application. We will do so using the latest available version of the [Elixir buildpack](https://github.com/HashNuke/heroku-buildpack-elixir):\n\n```console\n$ heroku create --buildpack hashnuke/elixir\nCreating app... done, ⬢ mysterious-meadow-6277\nSetting buildpack to hashnuke/elixir... done\nhttps://mysterious-meadow-6277.herokuapp.com/ | https://git.heroku.com/mysterious-meadow-6277.git\n```\n\n> Note: the first time we use a Heroku command, it may prompt us to log in. If this happens, just enter the email and password you specified during signup.\n\n> Note: the name of the Heroku application is the random string after \"Creating\" in the output above (mysterious-meadow-6277). This will be unique, so expect to see a different name from \"mysterious-meadow-6277\".\n\n> Note: the URL in the output is the URL to our application. If we open it in our browser now, we will get the default Heroku welcome page.\n\n> Note: if we hadn't initialized our Git repository before we ran the `heroku create` command, we wouldn't have our Heroku remote repository properly set up at this point. We can set that up manually by running: `heroku git:remote -a [our-app-name].`\n\nThe buildpack uses a predefined Elixir and Erlang version, but to avoid surprises when deploying, it is best to explicitly list the Elixir and Erlang version we want in production to be the same we are using during development or in your continuous integration servers. This is done by creating a config file named `elixir_buildpack.config` in the root directory of your project with your target version of Elixir and Erlang:\n\n```console\n# Elixir version\nelixir_version=1.15.0\n\n# Erlang version\n# https://github.com/HashNuke/heroku-buildpack-elixir-otp-builds/blob/master/otp-versions\nerlang_version=25.3\n\n# Invoke assets.deploy defined in your mix.exs to deploy assets with esbuild\n# Note we nuke the esbuild executable from the image\nhook_post_compile=\"eval mix assets.deploy && rm -f _build/esbuild*\"\n```\n\nFinally, let's tell the build pack how to start our webserver. Create a file named `Procfile` at the root of your project:\n\n```console\nweb: mix phx.server\n```\n\n### Optional: Node, npm, and the Phoenix Static buildpack\n\nBy default, Phoenix uses `esbuild` and manages all assets for you. However, if you are using `node` and `npm`, you will need to install the [Phoenix Static buildpack](https://github.com/gigalixir/gigalixir-buildpack-phoenix-static) to handle them:\n\n```console\n$ heroku buildpacks:add https://github.com/gigalixir/gigalixir-buildpack-phoenix-static.git\nBuildpack added. Next release on mysterious-meadow-6277 will use:\n 1. https://github.com/HashNuke/heroku-buildpack-elixir.git\n 2. https://github.com/gigalixir/gigalixir-heroku-buildpack-phoenix-static.git\n```\n\nWhen using this buildpack, you want to delegate all asset bundling to `npm`. So you must remove the `hook_post_compile` configuration from your `elixir_buildpack.config` and move it to the deploy script of your `assets/package.json`. Something like this:\n\n```javascript\n{\n ...\n \"scripts\": {\n \"deploy\": \"cd .. && mix assets.deploy && rm -f _build/esbuild*\"\n }\n ...\n}\n```\n\nThe Phoenix Static buildpack uses a predefined Node.js version, but to avoid surprises when deploying, it is best to explicitly list the Node.js version we want in production to be the same we are using during development or in your continuous integration servers. This is done by creating a config file named `phoenix_static_buildpack.config` in the root directory of your project with your target version of Node.js:\n\n```text\n# Node.js version\nnode_version=10.20.1\n```\n\nPlease refer to the [configuration section](https://github.com/gigalixir/gigalixir-buildpack-phoenix-static#configuration) for full details. You can make your own custom build script, but for now we will use the [default one provided](https://github.com/gigalixir/gigalixir-buildpack-phoenix-static/blob/master/compile).\n\nFinally, note that since we are using multiple buildpacks, you might run into an issue where the sequence is out of order (the Elixir buildpack needs to run before the Phoenix Static buildpack). [Heroku's docs](https://devcenter.heroku.com/articles/using-multiple-buildpacks-for-an-app) explain this better, but you will need to make sure the Phoenix Static buildpack comes last.\n\n## Making our Project ready for Heroku\n\nEvery new Phoenix project ships with a config file `config/runtime.exs` which loads configuration and secrets from [environment variables](https://devcenter.heroku.com/articles/config-vars). This aligns well with Heroku best practices ([12-factor apps](https://12factor.net/)), so the only work left for us to do is to configure URLs and SSL.\n\nFirst let's tell Phoenix to only use the SSL version of the website. Find the endpoint config in your `config/prod.exs`:\n\n```elixir\nconfig :scaffold, ScaffoldWeb.Endpoint,\n url: [port: 443, scheme: \"https\"],\n```\n\n... and add `force_ssl`\n\n```elixir\nconfig :scaffold, ScaffoldWeb.Endpoint,\n url: [port: 443, scheme: \"https\"],\n force_ssl: [rewrite_on: [:x_forwarded_proto]],\n```\n\n`force_ssl` need to be set here because it is a _compile_ time config. It will not work when set from `runtime.exs`.\n\nThen in your `config/runtime.exs`:\n\n... add `host`\n\n```elixir\nconfig :scaffold, ScaffoldWeb.Endpoint,\n url: [host: host, port: 443, scheme: \"https\"]\n```\n\nand uncomment the `# ssl: true,` line in your repository configuration. It will look like this:\n\n```elixir\nconfig :hello, Hello.Repo,\n ssl: true,\n url: database_url,\n pool_size: String.to_integer(System.get_env(\"POOL_SIZE\") || \"10\")\n```\n\nFinally, if you plan on using websockets, then we will need to decrease the timeout for the websocket transport in `lib/hello_web/endpoint.ex`. If you do not plan on using websockets, then leaving it set to false is fine. You can find further explanation of the options available at the [documentation](https://hexdocs.pm/phoenix/Phoenix.Endpoint.html#socket/3-websocket-configuration).\n\n```elixir\ndefmodule HelloWeb.Endpoint do\n use Phoenix.Endpoint, otp_app: :hello\n\n socket \"/socket\", HelloWeb.UserSocket,\n websocket: [timeout: 45_000]\n\n ...\nend\n```\n\nAlso set the host in Heroku:\n\n```console\n$ heroku config:set PHX_HOST=\"mysterious-meadow-6277.herokuapp.com\"\n```\n\nThis ensures that any idle connections are closed by Phoenix before they reach Heroku's 55-second timeout window.\n\n## Creating Environment Variables in Heroku\n\nThe `DATABASE_URL` config var is automatically created by Heroku when we add the [Heroku Postgres add-on](https://elements.heroku.com/addons/heroku-postgresql). We can create the database via the Heroku toolbelt:\n\n```console\n$ heroku addons:create heroku-postgresql:mini\n```\n\nNow we set the `POOL_SIZE` config var:\n\n```console\n$ heroku config:set POOL_SIZE=18\n```\n\nThis value should be just under the number of available connections, leaving a couple open for migrations and mix tasks. The mini database allows 20 connections, so we set this number to 18. If additional dynos will share the database, reduce the `POOL_SIZE` to give each dyno an equal share.\n\nWhen running a mix task later (after we have pushed the project to Heroku) you will also want to limit its pool size like so:\n\n```console\n$ heroku run \"POOL_SIZE=2 mix hello.task\"\n```\n\nSo that Ecto does not attempt to open more than the available connections.\n\nWe still have to create the `SECRET_KEY_BASE` config based on a random string. First, use `mix phx.gen.secret` to get a new secret:\n\n```console\n$ mix phx.gen.secret\nxvafzY4y01jYuzLm3ecJqo008dVnU3CN4f+MamNd1Zue4pXvfvUjbiXT8akaIF53\n```\n\nYour random string will be different; don't use this example value.\n\nNow set it in Heroku:\n\n```console\n$ heroku config:set SECRET_KEY_BASE=\"xvafzY4y01jYuzLm3ecJqo008dVnU3CN4f+MamNd1Zue4pXvfvUjbiXT8akaIF53\"\nSetting config vars and restarting mysterious-meadow-6277... done, v3\nSECRET_KEY_BASE: xvafzY4y01jYuzLm3ecJqo008dVnU3CN4f+MamNd1Zue4pXvfvUjbiXT8akaIF53\n```\n\n## Deploy Time!\n\nOur project is now ready to be deployed on Heroku.\n\nLet's commit all our changes:\n\n```console\n$ git add elixir_buildpack.config\n$ git commit -a -m \"Use production config from Heroku ENV variables and decrease socket timeout\"\n```\n\nAnd deploy:\n\n```console\n$ git push heroku main\nCounting objects: 55, done.\nDelta compression using up to 8 threads.\nCompressing objects: 100% (49/49), done.\nWriting objects: 100% (55/55), 48.48 KiB | 0 bytes/s, done.\nTotal 55 (delta 1), reused 0 (delta 0)\nremote: Compressing source files... done.\nremote: Building source:\nremote:\nremote: -----> Multipack app detected\nremote: -----> Fetching custom git buildpack... done\nremote: -----> elixir app detected\nremote: -----> Checking Erlang and Elixir versions\nremote: WARNING: elixir_buildpack.config wasn't found in the app\nremote: Using default config from Elixir buildpack\nremote: Will use the following versions:\nremote: * Stack cedar-14\nremote: * Erlang 17.5\nremote: * Elixir 1.0.4\nremote: Will export the following config vars:\nremote: * Config vars DATABASE_URL\nremote: * MIX_ENV=prod\nremote: -----> Stack changed, will rebuild\nremote: -----> Fetching Erlang 17.5\nremote: -----> Installing Erlang 17.5 (changed)\nremote:\nremote: -----> Fetching Elixir v1.0.4\nremote: -----> Installing Elixir v1.0.4 (changed)\nremote: -----> Installing Hex\nremote: 2015-07-07 00:04:00 URL:https://s3.amazonaws.com/s3.hex.pm/installs/1.0.0/hex.ez [262010/262010] ->\n\"/app/.mix/archives/hex.ez\" [1]\nremote: * creating /app/.mix/archives/hex.ez\nremote: -----> Installing rebar\nremote: * creating /app/.mix/rebar\nremote: -----> Fetching app dependencies with mix\nremote: Running dependency resolution\nremote: Dependency resolution completed successfully\nremote: [...]\nremote: -----> Compiling\nremote: [...]\nremote: Generated phoenix_heroku app\nremote: [...]\nremote: Consolidated protocols written to _build/prod/consolidated\nremote: -----> Creating .profile.d with env vars\nremote: -----> Fetching custom git buildpack... done\nremote: -----> Phoenix app detected\nremote:\nremote: -----> Loading configuration and environment\nremote: Loading config...\nremote: [...]\nremote: Will export the following config vars:\nremote: * Config vars DATABASE_URL\nremote: * MIX_ENV=prod\nremote:\nremote: -----> Compressing... done, 82.1MB\nremote: -----> Launching... done, v5\nremote: https://mysterious-meadow-6277.herokuapp.com/ deployed to Heroku\nremote:\nremote: Verifying deploy... done.\nTo https://git.heroku.com/mysterious-meadow-6277.git\n * [new branch] master -> master\n```\n\nTyping `heroku open` in the terminal should launch a browser with the Phoenix welcome page opened. In the event that you are using Ecto to access a database, you will also need to run migrations after the first deploy:\n\n```console\n$ heroku run \"POOL_SIZE=2 mix ecto.migrate\"\n```\n\nAnd that's it!\n\n## Deploying to Heroku using the container stack\n\n### Create Heroku application\n\nSet the stack of your app to `container`, this allows us to use `Dockerfile` to define our app setup.\n\n```console\n$ heroku create\nCreating app... done, ⬢ mysterious-meadow-6277\n$ heroku stack:set container\n```\n\nAdd a new `heroku.yml` file to your root folder. In this file you can define addons used by your app, how to build the image and what configs are passed to the image. You can learn more about Heroku's `heroku.yml` options [here](https://devcenter.heroku.com/articles/build-docker-images-heroku-yml). Here is a sample:\n\n```yaml\nsetup:\n addons:\n - plan: heroku-postgresql\n as: DATABASE\nbuild:\n docker:\n web: Dockerfile\n config:\n MIX_ENV: prod\n SECRET_KEY_BASE: $SECRET_KEY_BASE\n DATABASE_URL: $DATABASE_URL\n```\n\n### Set up releases and Dockerfile\n\nNow we need to define a `Dockerfile` at the root folder of your project that contains your application. We recommend to use releases when doing so, as the release will allow us to build a container with only the parts of Erlang and Elixir we actually use. Follow the [releases docs](releases.html). At the end of the guide, there is a sample Dockerfile file you can use.\n\nOnce you have the image definition set up, you can push your app to heroku and you can see it starts building the image and deploy it.\n\n## Useful Heroku Commands\n\nWe can look at the logs of our application by running the following command in our project directory:\n\n```console\n$ heroku logs # use --tail if you want to tail them\n```\n\nWe can also start an IEx session attached to our terminal for experimenting in our app's environment:\n\n```console\n$ heroku run \"POOL_SIZE=2 iex -S mix\"\n```\n\nIn fact, we can run anything using the `heroku run` command, like the Ecto migration task from above:\n\n```console\n$ heroku run \"POOL_SIZE=2 mix ecto.migrate\"\n```\n\n## Connecting to your dyno\n\nHeroku gives you the ability to connect to your dyno with an IEx shell which allows running Elixir code such as database queries.\n\n- Modify the `web` process in your Procfile to run a named node:\n\n ```text\n web: elixir --sname server -S mix phx.server\n ```\n\n- Redeploy to Heroku\n- Connect to the dyno with `heroku ps:exec` (if you have several applications on the same repository you will need to specify the app name or the remote name with `--app APP_NAME` or `--remote REMOTE_NAME`)\n- Launch an iex session with `iex --sname console --remsh server`\n\nYou have an iex session into your dyno!\n\n## Troubleshooting\n\n### Compilation Error\n\nOccasionally, an application will compile locally, but not on Heroku. The compilation error on Heroku will look something like this:\n\n```console\nremote: == Compilation error on file lib/postgrex/connection.ex ==\nremote: could not compile dependency :postgrex, \"mix compile\" failed. You can recompile this dependency with \"mix deps.compile postgrex\", update it with \"mix deps.update postgrex\" or clean it with \"mix deps.clean postgrex\"\nremote: ** (CompileError) lib/postgrex/connection.ex:207: Postgrex.Connection.__struct__/0 is undefined, cannot expand struct Postgrex.Connection\nremote: (elixir) src/elixir_map.erl:58: :elixir_map.translate_struct/4\nremote: (stdlib) lists.erl:1353: :lists.mapfoldl/3\nremote: (stdlib) lists.erl:1354: :lists.mapfoldl/3\nremote:\nremote:\nremote: ! Push rejected, failed to compile elixir app\nremote:\nremote: Verifying deploy...\nremote:\nremote: ! Push rejected to mysterious-meadow-6277.\nremote:\nTo https://git.heroku.com/mysterious-meadow-6277.git\n```\n\nThis has to do with stale dependencies which are not getting recompiled properly. It's possible to force Heroku to recompile all dependencies on each deploy, which should fix this problem. The way to do it is to add a new file called `elixir_buildpack.config` at the root of the application. The file should contain this line:\n\n```text\nalways_rebuild=true\n```\n\nCommit this file to the repository and try to push again to Heroku.\n\n### Connection Timeout Error\n\nIf you are constantly getting connection timeouts while running `heroku run` this could mean that your internet provider has blocked port number 5000:\n\n```console\nheroku run \"POOL_SIZE=2 mix myapp.task\"\nRunning POOL_SIZE=2 mix myapp.task on mysterious-meadow-6277... !\nETIMEDOUT: connect ETIMEDOUT 50.19.103.36:5000\n```\n\nYou can overcome this by adding `detached` option to run command:\n\n```console\nheroku run:detached \"POOL_SIZE=2 mix ecto.migrate\"\nRunning POOL_SIZE=2 mix ecto.migrate on mysterious-meadow-6277... done, run.8089 (Free)\n```\n"
},
{
"path": "guides/deployment/releases.md",
"content": "# Deploying with Releases\n\nOur main goal for this guide is to package your Phoenix application into a self-contained directory that includes the Erlang VM, Elixir, all of your code and dependencies. This package can then be dropped into a production machine.\n\n## What we'll need\n\nThe only thing we'll need for this guide is a working Phoenix application. For those of us who need a simple application to deploy, please follow the [Up and Running guide](up_and_running.html).\n\n## Releases, assemble!\n\nIf you are not familiar with Elixir releases yet, we recommend you to read [Elixir's excellent docs](https://hexdocs.pm/mix/Mix.Tasks.Release.html) before continuing.\n\nOnce that is done, you can assemble a release by going through all of the steps in our general [deployment guide](deployment.html) with `mix release` at the end. Let's recap.\n\nFirst set the environment variables:\n\n```console\n$ mix phx.gen.secret\nREALLY_LONG_SECRET\n$ export SECRET_KEY_BASE=REALLY_LONG_SECRET\n$ export DATABASE_URL=ecto://USER:PASS@HOST/database\n```\n\nThen load dependencies to compile code and assets:\n\n```console\n# Initial setup\n$ mix deps.get --only prod\n$ MIX_ENV=prod mix compile\n\n# Compile assets\n$ MIX_ENV=prod mix assets.deploy\n```\n\nAnd now run `mix phx.gen.release`:\n\n```console\n$ mix phx.gen.release\n==> my_app\n* creating rel/overlays/bin/server\n* creating rel/overlays/bin/server.bat\n* creating rel/overlays/bin/migrate\n* creating rel/overlays/bin/migrate.bat\n* creating lib/my_app/release.ex\n\nYour application is ready to be deployed in a release!\n\n # To start your system\n _build/dev/rel/my_app/bin/my_app start\n\n # To start your system with the Phoenix server running\n _build/dev/rel/my_app/bin/server\n\n # To run migrations\n _build/dev/rel/my_app/bin/migrate\n\nOnce the release is running:\n\n # To connect to it remotely\n _build/dev/rel/my_app/bin/my_app remote\n\n # To stop it gracefully (you may also send SIGINT/SIGTERM)\n _build/dev/rel/my_app/bin/my_app stop\n\nTo list all commands:\n\n _build/dev/rel/my_app/bin/my_app\n\n```\n\nThe `phx.gen.release` task generated a few files for us to assist in releases. First, it created `server` and `migrate` *overlay* scripts for conveniently running the phoenix server inside a release or invoking migrations from a release. The files in the `rel/overlays` directory are copied into every release environment. Next, it generated a `release.ex` file which is used to invoke Ecto migrations without a dependency on `mix` itself.\n\n*Note*: If you are a Docker user, you can pass the `--docker` flag to `mix phx.gen.release` to generate a Dockerfile ready for deployment.\n\nNext, we can invoke `mix release` to build the release:\n\n```console\n$ MIX_ENV=prod mix release\nGenerated my_app app\n* assembling my_app-0.1.0 on MIX_ENV=prod\n* using config/runtime.exs to configure the release at runtime\n\nRelease created at _build/prod/rel/my_app!\n\n # To start your system\n _build/prod/rel/my_app/bin/my_app start\n\n...\n```\n\nYou can start the release by calling `_build/prod/rel/my_app/bin/my_app start`, or boot your webserver by calling `_build/prod/rel/my_app/bin/server`, where you have to replace `my_app` by your current application name.\n\nNow you can get all of the files under the `_build/prod/rel/my_app` directory, package it, and run it in any production machine with the same OS and architecture as the one that assembled the release. For more details, check the [docs for `mix release`](https://hexdocs.pm/mix/Mix.Tasks.Release.html).\n\n## Ecto migrations\n\nA common need in production systems is to execute custom commands required to set up the production environment. One of such commands is precisely migrating the database. Since we don't have `Mix`, a *build* tool, inside releases, which are production artifacts, we need to bring said commands directly into the release.\n\nThe `phx.gen.release` command created the following `release.ex` file in your project `lib/my_app/release.ex`, with the following content:\n\n```elixir\ndefmodule MyApp.Release do\n @app :my_app\n\n def migrate do\n load_app()\n\n for repo <- repos() do\n {:ok, _, _} = Ecto.Migrator.with_repo(repo, &Ecto.Migrator.run(&1, :up, all: true))\n end\n end\n\n def rollback(repo, version) do\n load_app()\n {:ok, _, _} = Ecto.Migrator.with_repo(repo, &Ecto.Migrator.run(&1, :down, to: version))\n end\n\n defp repos do\n Application.fetch_env!(@app, :ecto_repos)\n end\n\n defp load_app do\n Application.ensure_all_started(:ssl)\n Application.ensure_loaded(@app)\n end\nend\n```\n\nWhere you replace the first two lines by your application names.\n\nNow you can assemble a new release with `MIX_ENV=prod mix release` and you can invoke any code, including the functions in the module above, by calling the `eval` command:\n\n```console\n$ _build/prod/rel/my_app/bin/my_app eval \"MyApp.Release.migrate\"\n```\n\nAnd that's it! If you peek inside the `migrate` script, you'll see it wraps exactly this invocation. Depending on where you are deploying your application, you can invoke the `migrate` command separately, or you may want to change the `server` script to migrate your database before starting your app.\n\n## Custom commands\n\nYou can use the same approach used for migrations to create any custom command to run in production. The idea is that each command invokes `load_app`, which calls `Application.ensure_loaded/1` to load the current application without starting it.\n\nHowever, some commands may need to start the whole application. In such cases, `Application.ensure_all_started/1` must be used instead of `Application.load/1`. Keep in mind starting the application will start all processes in its supervision tree, including the Phoenix endpoint. This can be circumvented by changing your supervision tree to not start certain children under certain conditions. For example, in the release commands file you could do:\n\n```elixir\ndefp start_app do\n load_app()\n Application.put_env(@app, :minimal, true)\n Application.ensure_all_started(@app)\nend\n```\n\nAnd then in your application you check `Application.get_env(@app, :minimal)` and start only part of the children when it is set.\n\n## Containers\n\nElixir releases work well with container technologies such as Docker. The idea is that you assemble the release inside the Docker container and then build an image based on the release artifacts.\n\nIf you call `mix phx.gen.release --docker`, you'll see a new file with content similar to:\n\n```Dockerfile\n# Find eligible builder and runner images on Docker Hub. We use Ubuntu/Debian\n# instead of Alpine to avoid DNS resolution issues in production.\n#\n# https://hub.docker.com/r/hexpm/elixir/tags?page=1&name=ubuntu\n# https://hub.docker.com/_/ubuntu?tab=tags\n#\n# This file is based on these images:\n#\n# - https://hub.docker.com/r/hexpm/elixir/tags - for the build image\n# - https://hub.docker.com/_/debian?tab=tags&page=1&name=bullseye-20230612-slim - for the release image\n# - https://pkgs.org/ - resource for finding needed packages\n# - Ex: hexpm/elixir:1.18.4-erlang-27.3.4.3-debian-trixie-20250908-slim\n#\nARG ELIXIR_VERSION=1.18.4\nARG OTP_VERSION=27.3.4.3\nARG DEBIAN_VERSION=trixie-20250908-slim\n\nARG BUILDER_IMAGE=\"hexpm/elixir:${ELIXIR_VERSION}-erlang-${OTP_VERSION}-debian-${DEBIAN_VERSION}\"\nARG RUNNER_IMAGE=\"debian:${DEBIAN_VERSION}\"\n\nFROM ${BUILDER_IMAGE} AS builder\n\n# install build dependencies\nRUN apt-get update \\\n && apt-get install -y --no-install-recommends build-essential git \\\n && rm -rf /var/lib/apt/lists/*\n\n# prepare build dir\nWORKDIR /app\n\n# install hex + rebar\nRUN mix local.hex --force \\\n && mix local.rebar --force\n\n# set build ENV\nENV MIX_ENV=\"prod\"\n\n# install mix dependencies\nCOPY mix.exs mix.lock ./\nRUN mix deps.get --only $MIX_ENV\nRUN mkdir config\n\n# copy compile-time config files before we compile dependencies\n# to ensure any relevant config change will trigger the dependencies\n# to be re-compiled.\nCOPY config/config.exs config/${MIX_ENV}.exs config/\nRUN mix deps.compile\n\nRUN mix assets.setup\n\nCOPY priv priv\n\nCOPY lib lib\n\n# Compile the release\nRUN mix compile\n\nCOPY assets assets\n\n# compile assets\nRUN mix assets.deploy\n\n# Changes to config/runtime.exs don't require recompiling the code\nCOPY config/runtime.exs config/\n\nCOPY rel rel\nRUN mix release\n\n# start a new build stage so that the final image will only contain\n# the compiled release and other runtime necessities\nFROM ${RUNNER_IMAGE} AS final\n\nRUN apt-get update \\\n && apt-get install -y --no-install-recommends libstdc++6 openssl libncurses6 locales ca-certificates \\\n && rm -rf /var/lib/apt/lists/*\n\n# Set the locale\nRUN sed -i '/en_US.UTF-8/s/^# //g' /etc/locale.gen \\\n && locale-gen\n\nENV LANG=en_US.UTF-8\nENV LANGUAGE=en_US:en\nENV LC_ALL=en_US.UTF-8\n\nWORKDIR \"/app\"\nRUN chown nobody /app\n\n# set runner ENV\nENV MIX_ENV=\"prod\"\n\n# Only copy the final release from the build stage\nCOPY --from=builder --chown=nobody:root /app/_build/${MIX_ENV}/rel/my_app ./\n\nUSER nobody\n\n# If using an environment that doesn't automatically reap zombie processes, it is\n# advised to add an init process such as tini via `apt-get install`\n# above and adding an entrypoint. See https://github.com/krallin/tini for details\n# ENTRYPOINT [\"/tini\", \"--\"]\n\nCMD [\"/app/bin/server\"]\n```\n\nWhere `my_app` is the name of your app. At the end, you will have an application in `/app` ready to run as `/app/bin/server`.\n\nA few points about configuring a containerized application:\n\n- The more configuration you can provide at runtime (using `config/runtime.exs`), the more reusable your images will be across environments. In particular, secrets like database credentials and API keys should not be compiled into the image, but rather should be provided when creating containers based on that image. This is why the `Endpoint`'s `:secret_key_base` is configured in `config/runtime.exs` by default.\n\n- If possible, any environment variables that are needed at runtime should be read in `config/runtime.exs`, not scattered throughout your code. Having them all visible in one place will make it easier to ensure the containers get what they need, especially if the person doing the infrastructure work does not work on the Elixir code. Libraries in particular should never directly read environment variables; all their configuration should be handed to them by the top-level application, preferably [without using the application environment](https://hexdocs.pm/elixir/design-anti-patterns.html#using-application-configuration-for-libraries).\n\n## Clustering\n\nElixir and the Erlang VM have the incredible ability to be clustered together and pass messages seamlessly between nodes. To enable clustering, we need two distinct features:\n\n* Node connection: different instances of the same service should communicate with each other. This is a feature of the Erlang VM.\n\n* Service discovery: for a given service, you must be able to find the IP address of all instances. Phoenix ships with `dns_cluster` to provide out-of-the-box DNS-based service discovery but alternative methods may be used.\n\n### DNS Discovery\n\nYour clustering configuration is typically added to `rel/env.sh.eex`. This is a file that is executed before you release starts, and it is a perfect place to configure your application runtime based on your deployment environment. Here is a general skeleton:\n\n```sh\n# Uncomment if IPv6 is required\n# export ECTO_IPV6=\"true\"\n# export ERL_AFLAGS=\"-proto_dist inet6_tcp\"\n\n# Erlang uses a port mapper daemon on each node,\n# it by default runs on port 4369\nexport ERL_EPMD_PORT=4369\n\n# Use the ports 4370-4372 for nodes to communicate.\nexport ERL_AFLAGS=\"-kernel inet_dist_listen_min 4370 inet_dist_listen_max 4372\"\n\nexport RELEASE_DISTRIBUTION=\"name\"\nexport RELEASE_NODE=\"app-${PLATFORM_DEPLOYMENT_SHA}@${PLATFORM_DEPLOYMENT_IP}\"\nexport DNS_CLUSTER_QUERY=\"your-app.internal\"\n```\n\nThe script above is doing a couple things:\n\n* It configures your app to use ports 4369, 4370, 4371, and 4372 for communication. You may need to explicitly expose those as internal TCP ports in your deployment platform (in addition to the HTTP port of your choice)\n\n* It then configures your app to use fully qualified names. The name of each app will include the current deployment sha as `PLATFORM_DEPLOYMENT_SHA` (the name of the exact environment variable is platform dependent), so each deployment establishes its own cluster, and the current IP as `PLATFORM_DEPLOYMENT_IP` (also platform specific). If the IP is not available, you may be able to compute it as `NODE_IP=hostname | tr -d ' '`\n\n* Then finally you define a DNS query which will be used to find the IPs of the other instances\n\nSome platforms, such as [Fly.io](https://fly.io/docs/networking/private-networking/), [Railway](https://docs.railway.com/guides/private-networking), and [Render](https://render.com/docs/private-network#direct-ip-communication-advanced), provide private networks with DNS querying out of the box. You only need to adapt the `DNS_CLUSTER_QUERY` variable accordingly.\n\nOther platforms, such as [Digital Ocean App Platform](https://www.digitalocean.com/products/app-platform) and [Northflank](https://northflank.com/features/platform), allow nodes to directly connect to each other, but they do not provide DNS service discovery. In this next section, we explore different service discovery mechanisms.\n\n### Alternative discovery mechanisms\n\nWhile not all platforms support DNS queries for service discovery, there are many alternative strategies for connecting your nodes together. Please checkout the following libraries:\n\n * [libcluster](https://github.com/bitwalker/libcluster) - provides strategies for connecting your nodes using gossip protocols, kubernetes, ec2, and others\n\n * [libcluster_postgres](https://github.com/supabase/libcluster_postgres/) - a plugin for `libcluster` which uses PostgreSQL for node discovery. Given most applications already use a database, and likely PostgreSQL, this is a suitable option which does not require additional setup\n\nWhen using the libraries above, you can likely remove `dns_query` from your application dependencies.\n\n### `epmd`-less deployment\n\nIn the snippet above, we used ports 4369, 4370, 4371, and 4372. However, the Erlang VM allows running the distribution over a fixed port, also known as `epmd`-less deployments. To enable such, do this.\n\nRemove the lines:\n\n```sh\nexport ERL_EPMD_PORT=4369\nexport ERL_AFLAGS=\"-kernel inet_dist_listen_min 4370 inet_dist_listen_max 4372\"\n```\n\nAdd a file rel/vm.args.eex with the following:\n\n```\n-start_epmd false -erl_epmd_port 6789\n```\n\nAdd a file rel/remote.vm.args.eex with the following:\n\n```\n-start_epmd false -erl_epmd_port 6789 -dist_listen false\n```\n\nAnd now only port 6789 (in addition to the HTTP one) needs to be exposed internally between instances.\n"
},
{
"path": "guides/directory_structure.md",
"content": "# Directory structure\n\n> **Requirement**: This guide expects that you have gone through the [introductory guides](installation.html) and got a Phoenix application [up and running](up_and_running.html).\n\nWhen we use `mix phx.new` to generate a new Phoenix application, it builds a top-level directory structure like this:\n\n```console\n├── _build\n├── assets\n├── config\n├── deps\n├── lib\n│  ├── hello\n│  ├── hello.ex\n│  ├── hello_web\n│  └── hello_web.ex\n├── priv\n└── test\n```\n\nWe will go over those directories one by one:\n\n * `_build` - a directory that holds all compilation artifacts, created by the `mix` command line tool (shipped as part of Elixir). As we have seen in \"[Up and Running](up_and_running.html)\", `mix` is the main interface to your application. We use Mix to compile our code, create databases, run our server, and more. This directory must not be checked into version control and it can be removed at any time. Removing it will force Mix to rebuild your application from scratch.\n\n * `assets` - a directory that keeps source code for your front-end assets, typically JavaScript and CSS. These sources are automatically bundled by the `esbuild` tool. Static files like images and fonts go in `priv/static`.\n\n * `config` - a directory that holds your project configuration. The `config/config.exs` file is the entry point for your configuration. At the end of the `config/config.exs`, it imports environment specific configuration, which can be found in `config/dev.exs`, `config/test.exs`, and `config/prod.exs`. Finally, `config/runtime.exs` is executed and it is the best place to read secrets and other dynamic configuration.\n\n * `deps` - a directory with all of our Mix dependencies. You can find all dependencies listed in the `mix.exs` file, inside the `defp deps do` function definition. This directory must not be checked into version control and it can be removed at any time. Removing it will force Mix to download all deps from scratch.\n\n * `lib` - a directory that holds your application source code. This directory is broken into two subdirectories, `lib/hello` and `lib/hello_web`. The `lib/hello` directory is responsible for hosting all of your business logic and business domain. It typically interacts directly with the database - it is the \"Model\" in Model-View-Controller (MVC) architecture. `lib/hello_web` is responsible for exposing your business domain to the world, in this case, through a web application. It holds both the View and Controller from MVC. We will discuss the contents of these directories in more detail in the next sections.\n\n * `priv` - a directory that keeps all resources that are necessary in production but are not directly part of your source code. You typically keep database scripts, translation files, images, and more in here. Generated assets, created from files in the `assets` directory, are placed in `priv/static/assets` by default.\n\n * `test` - a directory with all of our application tests. It often mirrors the same structure found in `lib`.\n\n## The lib/hello directory\n\nThe `lib/hello` directory hosts all of your business domain. Since our project does not have any business logic yet, the directory is mostly empty. You will only find three files:\n\n```console\nlib/hello\n├── application.ex\n├── mailer.ex\n└── repo.ex\n```\n\nThe `lib/hello/application.ex` file defines an Elixir application named `Hello.Application`. That's because at the end of the day Phoenix applications are simply Elixir applications. The `Hello.Application` module defines which services are part of our application:\n\n```elixir\nchildren = [\n HelloWeb.Telemetry,\n Hello.Repo,\n {Phoenix.PubSub, name: Hello.PubSub},\n HelloWeb.Endpoint\n]\n```\n\nIf it is your first time with Phoenix, you don't need to worry about the details right now. For now, suffice it to say our application starts a database repository, a PubSub system for sharing messages across processes and nodes, and the application endpoint, which effectively serves HTTP requests. These services are started in the order they are defined and, whenever shutting down your application, they are stopped in the reverse order.\n\nYou can learn more about applications in [Elixir's official docs for Application](https://hexdocs.pm/elixir/Application.html).\n\nThe `lib/hello/mailer.ex` file holds the `Hello.Mailer` module, which defines the main interface to deliver e-mails:\n\n```elixir\ndefmodule Hello.Mailer do\n use Swoosh.Mailer, otp_app: :hello\nend\n```\n\nIn the same `lib/hello` directory, we will find a `lib/hello/repo.ex`. It defines a `Hello.Repo` module which is our main interface to the database. If you are using Postgres (the default database), you will see something like this:\n\n```elixir\ndefmodule Hello.Repo do\n use Ecto.Repo,\n otp_app: :hello,\n adapter: Ecto.Adapters.Postgres\nend\n```\n\nAnd that's it for now. As you work on your project, we will add files and modules to this directory.\n\n## The lib/hello_web directory\n\nThe `lib/hello_web` directory holds the web-related parts of our application. It looks like this when expanded:\n\n```console\nlib/hello_web\n├── controllers\n│  ├── page_controller.ex\n│  ├── page_html.ex\n│  ├── error_html.ex\n│  ├── error_json.ex\n│  └── page_html\n│  └── home.html.heex\n├── components\n│  ├── core_components.ex\n│  ├── layouts.ex\n│  └── layouts\n│  └── root.html.heex\n├── endpoint.ex\n├── gettext.ex\n├── router.ex\n└── telemetry.ex\n```\n\nAll of the files which are currently in the `controllers` and `components` directories are there to create the \"Welcome to Phoenix!\" page we saw in the \"[Up and running](up_and_running.html)\" guide.\n\nBy looking at `controller` and `components` directories, we can see Phoenix provides features for handling layouts, HTML, and error pages out of the box.\n\nBesides the directories mentioned, `lib/hello_web` has four files at its root. `lib/hello_web/endpoint.ex` is the entry-point for HTTP requests. Once the browser accesses [http://localhost:4000](http://localhost:4000), the endpoint starts processing the data, eventually leading to the router, which is defined in `lib/hello_web/router.ex`. The router defines the rules to dispatch requests to \"controllers\", which calls a view module to render HTML pages back to clients. We explore these layers in length in other guides, starting with the \"[Request life-cycle](request_lifecycle.html)\" guide coming next.\n\nThrough _Telemetry_, Phoenix is able to collect metrics and send monitoring events of your application. The `lib/hello_web/telemetry.ex` file defines the supervisor responsible for managing the telemetry processes. You can find more information on this topic in the [Telemetry guide](telemetry.html).\n\nFinally, there is a `lib/hello_web/gettext.ex` file which provides internationalization through [Gettext](https://hexdocs.pm/gettext/Gettext.html). If you are not worried about internationalization, you can safely skip this file and its contents.\n\n## The assets directory\n\nThe `assets` directory contains source files related to front-end assets, such as JavaScript and CSS. Since Phoenix v1.6, we use [`esbuild`](https://github.com/evanw/esbuild/) to compile assets, which is managed by the [`esbuild`](https://github.com/phoenixframework/esbuild) Elixir package. The integration with `esbuild` is baked into your app. The relevant config can be found in your `config/config.exs` file.\n\nYour other static assets are placed in the `priv/static` folder, where `priv/static/assets` is kept for generated assets. Everything in `priv/static` is served by the `Plug.Static` plug configured in `lib/hello_web/endpoint.ex`. When running in dev mode (`MIX_ENV=dev`), Phoenix watches for any changes you make in the `assets` directory, and then takes care of updating your front end application in your browser as you work.\n\nNote that when you first create your Phoenix app using `mix phx.new` it is possible to specify options that will affect the presence and layout of the `assets` directory. In fact, Phoenix apps can bring their own front end tools or not have a front-end at all (handy if you're writing an API for example). For more information you can run `mix help phx.new`.\n\nIf the default esbuild integration does not cover your needs, for example because you want to use another build tool, you can switch to a [custom assets build](asset_management.html#custom_builds).\n\nAs for CSS, Phoenix ships with the [Tailwind CSS Framework](https://tailwindcss.com/), providing a base setup for projects. You may move to any CSS framework of your choice. Additional references can be found in the [asset management](asset_management.md#css) guide.\n"
},
{
"path": "guides/ecto.md",
"content": "# Ecto\n\n> **Requirement**: This guide expects that you have gone through the [introductory guides](installation.html) and got a Phoenix application [up and running](up_and_running.html).\n\nMost web applications today need some form of data validation and persistence. In the Elixir ecosystem, we have `Ecto` to enable this. Before we jump into building database-backed web features, we're going to focus on the finer details of Ecto to give a solid base to build our web features on top of. Let's get started!\n\nPhoenix uses Ecto to provide builtin support to the following databases:\n\n* PostgreSQL (via [`postgrex`](https://github.com/elixir-ecto/postgrex))\n* MySQL (via [`myxql`](https://github.com/elixir-ecto/myxql))\n* MSSQL (via [`tds`](https://github.com/livehelpnow/tds))\n* ETS (via [`etso`](https://github.com/evadne/etso))\n* SQLite3 (via [`ecto_sqlite3`](https://github.com/elixir-sqlite/ecto_sqlite3))\n\nNewly generated Phoenix projects include Ecto with the PostgreSQL adapter by default. You can pass the `--database` option to change or `--no-ecto` flag to exclude this.\n\nEcto also provides support for other databases and it has many learning resources available. Please check out [Ecto's README](https://github.com/elixir-ecto/ecto) for general information.\n\nThis guide assumes that we have generated our new application with Ecto integration and that we will be using PostgreSQL. The introductory guides cover how to get your first application up and running. For using other databases, see the [Swapping Databases](swapping_databases.html) how-to guide.\n\n## Using `phx.gen.schema`\n\nOnce we have Ecto and PostgreSQL installed and configured, the easiest way to use Ecto is to generate an Ecto *schema* through the `phx.gen.schema` task. Ecto schemas are a way for us to specify how Elixir data types map to and from external sources, such as database tables. Let's generate a `User` schema with `name`, `email`, `bio`, and `number_of_pets` fields.\n\n```console\n$ mix phx.gen.schema User users name:string email:string \\\nbio:string number_of_pets:integer\n\n* creating ./lib/hello/user.ex\n* creating priv/repo/migrations/20170523151118_create_users.exs\n\nRemember to update your repository by running migrations:\n\n $ mix ecto.migrate\n```\n\nA couple of files were generated with this task. First, we have a `user.ex` file, containing our Ecto schema with our schema definition of the fields we passed to the task. Next, a migration file was generated inside `priv/repo/migrations/` which will create our database table that our schema maps to.\n\nWith our files in place, let's follow the instructions and run our migration:\n\n```console\n$ mix ecto.migrate\nCompiling 1 file (.ex)\nGenerated hello app\n\n[info] == Running Hello.Repo.Migrations.CreateUsers.change/0 forward\n\n[info] create table users\n\n[info] == Migrated in 0.0s\n```\n\nMix assumes that we are in the development environment unless we tell it otherwise with `MIX_ENV=prod mix ecto.migrate`.\n\nIf we log in to our database server, and connect to our `hello_dev` database, we should see our `users` table. Ecto assumes that we want an integer column called `id` as our primary key, so we should see a sequence generated for that as well.\n\n```console\n$ psql -U postgres\n\nType \"help\" for help.\n\npostgres=# \\connect hello_dev\nYou are now connected to database \"hello_dev\" as user \"postgres\".\nhello_dev=# \\d\n List of relations\n Schema | Name | Type | Owner\n--------+-------------------+----------+----------\n public | schema_migrations | table | postgres\n public | users | table | postgres\n public | users_id_seq | sequence | postgres\n(3 rows)\nhello_dev=# \\q\n```\n\nIf we take a look at the migration generated by `phx.gen.schema` in `priv/repo/migrations/`, we'll see that it will add the columns we specified. It will also add timestamp columns for `inserted_at` and `updated_at` which come from the [`timestamps/1`] function.\n\n```elixir\ndefmodule Hello.Repo.Migrations.CreateUsers do\n use Ecto.Migration\n\n def change do\n create table(:users) do\n add :name, :string\n add :email, :string\n add :bio, :string\n add :number_of_pets, :integer\n\n timestamps(type: :utc_datetime)\n end\n end\nend\n```\n\nAnd here's what that translates to in the actual `users` table.\n\n```console\n$ psql\nhello_dev=# \\d users\nTable \"public.users\"\nColumn | Type | Modifiers\n---------------+--------------------------------+----------------------------------------------------\nid | bigint | not null default nextval('users_id_seq'::regclass)\nname | character varying(255) |\nemail | character varying(255) |\nbio | character varying(255) |\nnumber_of_pets | integer |\ninserted_at | timestamp(0) without time zone | not null\nupdated_at | timestamp(0) without time zone | not null\nIndexes:\n\"users_pkey\" PRIMARY KEY, btree (id)\n```\n\nNotice that we do get an `id` column as our primary key by default, even though it isn't listed as a field in our migration.\n\n## Repo configuration\n\nOur `Hello.Repo` module is the foundation we need to work with databases in a Phoenix application. Phoenix generated it for us in `lib/hello/repo.ex`, and this is what it looks like.\n\n```elixir\ndefmodule Hello.Repo do\n use Ecto.Repo,\n otp_app: :hello,\n adapter: Ecto.Adapters.Postgres\nend\n```\n\nIt begins by defining the repository module. Then it configures our `otp_app` name, and the `adapter` – `Postgres`, in our case.\n\nOur repo has three main tasks - to bring in all the common query functions from [`Ecto.Repo`], to set the `otp_app` name equal to our application name, and to configure our database adapter. We'll talk more about how to use `Hello.Repo` in a bit.\n\nWhen `phx.new` generated our application, it included some basic repository configuration as well. Let's look at `config/dev.exs`.\n\n```elixir\n...\n# Configure your database\nconfig :hello, Hello.Repo,\n username: \"postgres\",\n password: \"postgres\",\n hostname: \"localhost\",\n database: \"hello_dev\",\n show_sensitive_data_on_connection_error: true,\n pool_size: 10\n...\n```\n\nWe also have similar configuration in `config/test.exs` and `config/runtime.exs` which can also be changed to match your actual credentials.\n\n## The schema\n\nEcto schemas are responsible for mapping Elixir values to external data sources, as well as mapping external data back into Elixir data structures. We can also define relationships to other schemas in our applications. For example, our `User` schema might have many posts, and each post would belong to a user. Ecto also handles data validation and type casting with changesets, which we'll discuss in a moment.\n\nHere's the `User` schema that Phoenix generated for us.\n\n```elixir\ndefmodule Hello.User do\n use Ecto.Schema\n import Ecto.Changeset\n\n schema \"users\" do\n field :bio, :string\n field :email, :string\n field :name, :string\n field :number_of_pets, :integer\n\n timestamps(type: :utc_datetime)\n end\n\n @doc false\n def changeset(user, attrs) do\n user\n |> cast(attrs, [:name, :email, :bio, :number_of_pets])\n |> validate_required([:name, :email, :bio, :number_of_pets])\n end\nend\n```\n\nEcto schemas at their core are simply Elixir structs. Our `schema` block is what tells Ecto how to cast our `%User{}` struct fields to and from the external `users` table. Often, the ability to simply cast data to and from the database isn't enough and extra data validation is required. This is where Ecto changesets come in. Let's dive in!\n\n## Changesets and validations\n\nChangesets define a pipeline of transformations our data needs to undergo before it will be ready for our application to use. These transformations might include type-casting, user input validation, and filtering out any extraneous parameters. Often we'll use changesets to validate user input before writing it to the database. Ecto repositories are also changeset-aware, which allows them not only to refuse invalid data, but also perform the minimal database updates possible by inspecting the changeset to know which fields have changed.\n\nLet's take a closer look at our default changeset function.\n\n```elixir\ndef changeset(user, attrs) do\n user\n |> cast(attrs, [:name, :email, :bio, :number_of_pets])\n |> validate_required([:name, :email, :bio, :number_of_pets])\nend\n```\n\nRight now, we have two transformations in our pipeline. In the first call, we invoke `Ecto.Changeset.cast/3`, passing in our external parameters and marking which fields are required for validation.\n\n[`cast/3`] first takes a struct, then the parameters (the proposed updates), and then the final field is the list of columns to be updated. [`cast/3`] also will only take fields that exist in the schema.\n\nNext, `Ecto.Changeset.validate_required/3` checks that this list of fields is present in the changeset that [`cast/3`] returns. By default with the generator, all fields are required.\n\nWe can verify this functionality in `IEx`. Let's fire up our application inside IEx by running `iex -S mix`. In order to minimize typing and make this easier to read, let's alias our `Hello.User` struct.\n\n```console\n$ iex -S mix\n\niex> alias Hello.User\nHello.User\n```\n\nNext, let's build a changeset from our schema with an empty `User` struct, and an empty map of parameters.\n\n```elixir\niex> changeset = User.changeset(%User{}, %{})\n#Ecto.Changeset<\n action: nil,\n changes: %{},\n errors: [\n name: {\"can't be blank\", [validation: :required]},\n email: {\"can't be blank\", [validation: :required]},\n bio: {\"can't be blank\", [validation: :required]},\n number_of_pets: {\"can't be blank\", [validation: :required]}\n ],\n data: #Hello.User<>,\n valid?: false\n>\n```\n\nOnce we have a changeset, we can check if it is valid.\n\n```elixir\niex> changeset.valid?\nfalse\n```\n\nSince this one is not valid, we can ask it what the errors are.\n\n```elixir\niex> changeset.errors\n[\n name: {\"can't be blank\", [validation: :required]},\n email: {\"can't be blank\", [validation: :required]},\n bio: {\"can't be blank\", [validation: :required]},\n number_of_pets: {\"can't be blank\", [validation: :required]}\n]\n```\n\nNow, let's make `number_of_pets` optional. In order to do this, we simply remove it from the list in the `changeset/2` function, in `Hello.User`.\n\n```elixir\n|> validate_required([:name, :email, :bio])\n```\n\nNow casting the changeset should tell us that only `name`, `email`, and `bio` can't be blank. We can test that by running `recompile()` inside IEx and then rebuilding our changeset.\n\n```elixir\niex> recompile()\nCompiling 1 file (.ex)\n:ok\n\niex> changeset = User.changeset(%User{}, %{})\n#Ecto.Changeset<\n action: nil,\n changes: %{},\n errors: [\n name: {\"can't be blank\", [validation: :required]},\n email: {\"can't be blank\", [validation: :required]},\n bio: {\"can't be blank\", [validation: :required]}\n ],\n data: #Hello.User<>,\n valid?: false\n>\n\niex> changeset.errors\n[\n name: {\"can't be blank\", [validation: :required]},\n email: {\"can't be blank\", [validation: :required]},\n bio: {\"can't be blank\", [validation: :required]}\n]\n```\n\nWhat happens if we pass a key-value pair that is neither defined in the schema nor required?\n\nInside our existing IEx shell, let's create a `params` map with valid values plus an extra `random_key: \"random value\"`.\n\n```elixir\niex> params = %{name: \"Joe Example\", email: \"joe@example.com\", bio: \"An example to all\", number_of_pets: 5, random_key: \"random value\"}\n%{\n bio: \"An example to all\",\n email: \"joe@example.com\",\n name: \"Joe Example\",\n number_of_pets: 5,\n random_key: \"random value\"\n}\n```\n\nNext, let's use our new `params` map to create another changeset.\n\n```elixir\niex> changeset = User.changeset(%User{}, params)\n#Ecto.Changeset<\n action: nil,\n changes: %{\n bio: \"An example to all\",\n email: \"joe@example.com\",\n name: \"Joe Example\",\n number_of_pets: 5\n },\n errors: [],\n data: #Hello.User<>,\n valid?: true\n>\n```\n\nOur new changeset is valid.\n\n```elixir\niex> changeset.valid?\ntrue\n```\n\nWe can also check the changeset's changes - the map we get after all of the transformations are complete.\n\n```elixir\niex(9)> changeset.changes\n%{bio: \"An example to all\", email: \"joe@example.com\", name: \"Joe Example\",\n number_of_pets: 5}\n```\n\nNotice that our `random_key` key and `\"random_value\"` value have been removed from the final changeset. Changesets allow us to cast external data, such as user input on a web form or data from a CSV file into valid data into our system. Invalid parameters will be stripped and bad data that is unable to be cast according to our schema will be highlighted in the changeset errors.\n\nWe can validate more than just whether a field is required or not. Let's take a look at some finer-grained validations.\n\nWhat if we had a requirement that all biographies in our system must be at least two characters long? We can do this easily by adding another transformation to the pipeline in our changeset which validates the length of the `bio` field.\n\n```elixir\ndef changeset(user, attrs) do\n user\n |> cast(attrs, [:name, :email, :bio, :number_of_pets])\n |> validate_required([:name, :email, :bio, :number_of_pets])\n |> validate_length(:bio, min: 2)\nend\n```\n\nNow, if we try to cast data containing a value of `\"A\"` for our user's `bio`, we should see the failed validation in the changeset's errors.\n\n```elixir\niex> recompile()\n\niex> changeset = User.changeset(%User{}, %{bio: \"A\"})\n\niex> changeset.errors[:bio]\n{\"should be at least %{count} character(s)\",\n [count: 2, validation: :length, kind: :min, type: :string]}\n```\n\nIf we also have a requirement for the maximum length that a bio can have, we can simply add another validation.\n\n```elixir\ndef changeset(user, attrs) do\n user\n |> cast(attrs, [:name, :email, :bio, :number_of_pets])\n |> validate_required([:name, :email, :bio, :number_of_pets])\n |> validate_length(:bio, min: 2)\n |> validate_length(:bio, max: 140)\nend\n```\n\nLet's say we want to perform at least some rudimentary format validation on the `email` field. All we want to check for is the presence of the `@`. The `Ecto.Changeset.validate_format/3` function is just what we need.\n\n```elixir\ndef changeset(user, attrs) do\n user\n |> cast(attrs, [:name, :email, :bio, :number_of_pets])\n |> validate_required([:name, :email, :bio, :number_of_pets])\n |> validate_length(:bio, min: 2)\n |> validate_length(:bio, max: 140)\n |> validate_format(:email, ~r/@/)\nend\n```\n\nIf we try to cast a user with an email of `\"example.com\"`, we should see an error message like the following:\n\n```elixir\niex> recompile()\n\niex> changeset = User.changeset(%User{}, %{email: \"example.com\"})\n\niex> changeset.errors[:email]\n{\"has invalid format\", [validation: :format]}\n```\n\nThere are many more validations and transformations we can perform in a changeset. Please see the [Ecto Changeset documentation](https://hexdocs.pm/ecto/Ecto.Changeset.html) for more information.\n\n## Data persistence\n\nWe've explored migrations and schemas, but we haven't yet persisted any of our schemas or changesets. We briefly looked at our repository module in `lib/hello/repo.ex` earlier, and now it's time to put it to use.\n\nEcto repositories are the interface into a storage system, be it a database like PostgreSQL or an external service like a RESTful API. The `Repo` module's purpose is to take care of the finer details of persistence and data querying for us. As the caller, we only care about fetching and persisting data. The `Repo` module takes care of the underlying database adapter communication, connection pooling, and error translation for database constraint violations.\n\nLet's head back over to IEx with `iex -S mix`, and insert a couple of users into the database.\n\n```elixir\niex> alias Hello.{Repo, User}\n[Hello.Repo, Hello.User]\n\niex> Repo.insert(%User{email: \"user1@example.com\"})\n[debug] QUERY OK db=6.5ms queue=0.5ms idle=1358.3ms\nINSERT INTO \"users\" (\"email\",\"inserted_at\",\"updated_at\") VALUES ($1,$2,$3) RETURNING \"id\" [\"user1@example.com\", ~U[2021-02-25 01:58:55Z], ~U[2021-02-25 01:58:55Z]]\n{:ok,\n %Hello.User{\n __meta__: #Ecto.Schema.Metadata<:loaded, \"users\">,\n bio: nil,\n email: \"user1@example.com\",\n id: 1,\n inserted_at: ~U[2021-02-25 01:58:55Z],\n name: nil,\n number_of_pets: nil,\n updated_at: ~U[2021-02-25 01:58:55Z]\n }}\n\niex> Repo.insert(%User{email: \"user2@example.com\"})\n[debug] QUERY OK db=1.3ms idle=1402.7ms\nINSERT INTO \"users\" (\"email\",\"inserted_at\",\"updated_at\") VALUES ($1,$2,$3) RETURNING \"id\" [\"user2@example.com\", ~U[2021-02-25 02:03:28Z], ~U[2021-02-25 02:03:28Z]]\n{:ok,\n %Hello.User{\n __meta__: #Ecto.Schema.Metadata<:loaded, \"users\">,\n bio: nil,\n email: \"user2@example.com\",\n id: 2,\n inserted_at: ~U[2021-02-25 02:03:28Z],\n name: nil,\n number_of_pets: nil,\n updated_at: ~U[2021-02-25 02:03:28Z]\n }}\n```\n\nWe started by aliasing our `User` and `Repo` modules for easy access. Next, we called [`Repo.insert/2`] with a User struct. Since we are in the `dev` environment, we can see the debug logs for the query our repository performed when inserting the underlying `%User{}` data. We received a two-element tuple back with `{:ok, %User{}}`, which lets us know the insertion was successful.\n\nWe could also insert a user by passing a changeset to [`Repo.insert/2`]. If the changeset is valid, the repository will use an optimized database query to insert the record, and return a two-element tuple back, as above. If the changeset is not valid, we receive a two-element tuple consisting of `:error` plus the invalid changeset.\n\nWith a couple of users inserted, let's fetch them back out of the repo.\n\n```elixir\niex> Repo.all(User)\n[debug] QUERY OK source=\"users\" db=5.8ms queue=1.4ms idle=1672.0ms\nSELECT u0.\"id\", u0.\"bio\", u0.\"email\", u0.\"name\", u0.\"number_of_pets\", u0.\"inserted_at\", u0.\"updated_at\" FROM \"users\" AS u0 []\n[\n %Hello.User{\n __meta__: #Ecto.Schema.Metadata<:loaded, \"users\">,\n bio: nil,\n email: \"user1@example.com\",\n id: 1,\n inserted_at: ~U[2021-02-25 01:58:55Z],\n name: nil,\n number_of_pets: nil,\n updated_at: ~U[2021-02-25 01:58:55Z]\n },\n %Hello.User{\n __meta__: #Ecto.Schema.Metadata<:loaded, \"users\">,\n bio: nil,\n email: \"user2@example.com\",\n id: 2,\n inserted_at: ~U[2021-02-25 02:03:28Z],\n name: nil,\n number_of_pets: nil,\n updated_at: ~U[2021-02-25 02:03:28Z]\n }\n]\n```\n\nThat was easy! `Repo.all/1` takes a data source, our `User` schema in this case, and translates that to an underlying SQL query against our database. After it fetches the data, the Repo then uses our Ecto schema to map the database values back into Elixir data structures according to our `User` schema. We're not just limited to basic querying – Ecto includes a full-fledged query DSL for advanced SQL generation. In addition to a natural Elixir DSL, Ecto's query engine gives us multiple great features, such as SQL injection protection and compile-time optimization of queries. Let's try it out.\n\n```elixir\niex> import Ecto.Query\nEcto.Query\n\niex> Repo.all(from u in User, select: u.email)\n[debug] QUERY OK source=\"users\" db=0.8ms queue=0.9ms idle=1634.0ms\nSELECT u0.\"email\" FROM \"users\" AS u0 []\n[\"user1@example.com\", \"user2@example.com\"]\n```\n\nFirst, we imported `Ecto.Query`, which imports the [`from/2`] macro of Ecto's Query DSL. Next, we built a query which selects all the email addresses in our users table. Let's try another example.\n\n```elixir\niex> Repo.one(from u in User, where: ilike(u.email, \"%1%\"),\n select: count(u.id))\n[debug] QUERY OK source=\"users\" db=1.6ms SELECT count(u0.\"id\") FROM \"users\" AS u0 WHERE (u0.\"email\" ILIKE '%1%') []\n1\n```\n\nNow we're starting to get a taste of Ecto's rich querying capabilities. We used [`Repo.one/2`] to fetch the count of all users with an email address containing `1`, and received the expected count in return. This just scratches the surface of Ecto's query interface, and much more is supported such as sub-querying, interval queries, and advanced select statements. For example, let's build a query to fetch a map of all user id's to their email addresses.\n\n```elixir\niex> Repo.all(from u in User, select: %{u.id => u.email})\n[debug] QUERY OK source=\"users\" db=0.9ms\nSELECT u0.\"id\", u0.\"email\" FROM \"users\" AS u0 []\n[\n %{1 => \"user1@example.com\"},\n %{2 => \"user2@example.com\"}\n]\n```\n\nThat little query packed a big punch. It both fetched all user emails from the database and efficiently built a map of the results in one go. You should browse the [Ecto.Query documentation](https://hexdocs.pm/ecto/Ecto.Query.html#content) to see the breadth of supported query features.\n\nIn addition to inserts, we can also perform updates and deletes with [`Repo.update/2`] and [`Repo.delete/2`] to update or delete a single schema. Ecto also supports bulk persistence with the [`Repo.insert_all/3`], [`Repo.update_all/3`], and [`Repo.delete_all/2`] functions.\n\nThere is quite a bit more that Ecto can do and we've only barely scratched the surface. With a solid Ecto foundation in place, we're now ready to continue building our app and integrate the web-facing application with our backend persistence. Along the way, we'll expand our Ecto knowledge and learn how to properly isolate our web interface from the underlying details of our system. Please take a look at the [Ecto documentation](https://hexdocs.pm/ecto/) for the rest of the story.\n\nIn our [Data modelling guides](contexts.html), we'll find out how to wrap up our Ecto access and business logic behind modules that group related functionality. We'll see how Phoenix helps us design maintainable applications, and we'll find out about other neat Ecto features along the way.\n\n## Mix tasks\n\nEcto comes with a collection of Mix tasks to make it easier to manage your database and your application. Here is a quick look into the most important ones.\n\n### `mix ecto.create`\n\nThis task will create the database specified by our application repositories, but we can pass in another repo if we want.\n\nHere's what it looks like in action.\n\n```console\n$ mix ecto.create\nThe database for Hello.Repo has been created.\n```\n\nThere are a few things that can go wrong with `ecto.create`. If our Postgres database doesn't have a \"postgres\" role (user), we'll get an error like this one.\n\n```console\n$ mix ecto.create\n** (Mix) The database for Hello.Repo couldn't be created, reason given: psql: FATAL: role \"postgres\" does not exist\n```\n\nWe can fix this by creating the \"postgres\" role in the `psql` console with the permissions needed to log in and create a database.\n\n```console\n=# CREATE ROLE postgres LOGIN CREATEDB;\nCREATE ROLE\n```\n\nIf the \"postgres\" role does not have permission to log in to the application, we'll get this error.\n\n```console\n$ mix ecto.create\n** (Mix) The database for Hello.Repo couldn't be created, reason given: psql: FATAL: role \"postgres\" is not permitted to log in\n```\n\nTo fix this, we need to change the permissions on our \"postgres\" user to allow login.\n\n```console\n=# ALTER ROLE postgres LOGIN;\nALTER ROLE\n```\n\nIf the \"postgres\" role does not have permission to create a database, we'll get this error.\n\n```console\n$ mix ecto.create\n** (Mix) The database for Hello.Repo couldn't be created, reason given: ERROR: permission denied to create database\n```\n\nTo fix this, we need to change the permissions on our \"postgres\" user in the `psql` console to allow database creation.\n\n```console\n=# ALTER ROLE postgres CREATEDB;\nALTER ROLE\n```\n\nIf the \"postgres\" role is using a password different from the default \"postgres\", we'll get this error.\n\n```console\n$ mix ecto.create\n** (Mix) The database for Hello.Repo couldn't be created, reason given: psql: FATAL: password authentication failed for user \"postgres\"\n```\n\nTo fix this, we can change the password in the environment specific configuration file. For the development environment the password used can be found at the bottom of the `config/dev.exs` file.\n\nFinally, if we happen to have another repo called `OurCustom.Repo` that we want to create the database for, we can run this.\n\n```console\n$ mix ecto.create -r OurCustom.Repo\nThe database for OurCustom.Repo has been created.\n```\n\n### `mix ecto.drop`\n\nThis task will drop the database specified in our repo. By default it will look for the repo named after our application (the one generated with our app unless we opted out of Ecto). It will not prompt us to check if we're sure we want to drop the database, so do exercise caution.\n\n```console\n$ mix ecto.drop\nThe database for Hello.Repo has been dropped.\n```\n\n### `mix ecto.gen.migration`\n\nMigrations are a programmatic, repeatable way to affect changes to a database schema. Phoenix generators take care of generating migrations for us whenever we create a new context or schema, but if you want to generate a migration from scratch, `mix ecto.gen.migration` has our back. Let's see an example.\n\nWe simply need to invoke the task with a `snake_case` version of the module name that we want. Preferably, the name will describe what we want the migration to do.\n\n```console\n$ mix ecto.gen.migration add_comments_table\n* creating priv/repo/migrations\n* creating priv/repo/migrations/20150318001628_add_comments_table.exs\n```\n\nNotice that the migration's filename begins with a string representation of the date and time the file was created.\n\nLet's take a look at the file `ecto.gen.migration` has generated for us at `priv/repo/migrations/20150318001628_add_comments_table.exs`.\n\n```elixir\ndefmodule Hello.Repo.Migrations.AddCommentsTable do\n use Ecto.Migration\n\n def change do\n end\nend\n```\n\nNotice that there is a single function `change/0` which will handle both forward migrations and rollbacks. We'll define the schema changes that we want using Ecto's handy DSL, and Ecto will figure out what to do depending on whether we are rolling forward or rolling back. Very nice indeed.\n\nWhat we want to do is create a `comments` table with a `body` column, a `word_count` column, and timestamp columns for `inserted_at` and `updated_at`.\n\n```elixir\n...\ndef change do\n create table(:comments) do\n add :body, :string\n add :word_count, :integer\n\n timestamps(type: :utc_datetime)\n end\nend\n...\n```\n\nFor more information on how to modify your database schema please refer to the\n[Ecto's migration DSL docs](https://hexdocs.pm/ecto_sql/Ecto.Migration.html).\nFor example, to alter an existing schema see the documentation on Ecto’s\n[`alter/2`](`Ecto.Migration.alter/2`) function.\n\nThat's it! We're ready to run our migration.\n\n### `mix ecto.migrate`\n\nOnce we have our migration module ready, we can simply run `mix ecto.migrate` to have our changes applied to the database. We have already used it earlier in this chapter, but let's take it for a spin once more for our newly generated migration.\n\n```console\n$ mix ecto.migrate\n[info] == Running Hello.Repo.Migrations.AddCommentsTable.change/0 forward\n[info] create table comments\n[info] == Migrated in 0.1s\n```\n\nWhen we first run `ecto.migrate`, it will create a table for us called `schema_migrations`. This will keep track of all the migrations which we run by storing the timestamp portion of the migration's filename.\n\nHere's what the `schema_migrations` table looks like.\n\n```console\nhello_dev=# select * from schema_migrations;\nversion | inserted_at\n---------------+---------------------\n20250317170448 | 2025-03-17 21:07:26\n20250318001628 | 2025-03-18 01:45:00\n(2 rows)\n```\n\nWhen we roll back a migration, `mix ecto.rollback`, to be discussed next, we will remove the record representing this migration from `schema_migrations`.\n\nBy default, `ecto.migrate` will execute all pending migrations. We can exercise more control over which migrations we run by specifying some options when we run the task.\n\nWe can specify the number of pending migrations we would like to run with the `-n` or `--step` options.\n\n```console\n$ mix ecto.migrate -n 2\n[info] == Running Hello.Repo.Migrations.CreatePost.change/0 forward\n[info] create table posts\n[info] == Migrated in 0.0s\n[info] == Running Hello.Repo.Migrations.AddCommentsTable.change/0 forward\n[info] create table comments\n[info] == Migrated in 0.0s\n```\n\nThe `--step` option will behave the same way.\n\n```console\n$ mix ecto.migrate --step 2\n```\n\nThe `--to` option will run all migrations up to and including given version.\n\n```console\n$ mix ecto.migrate --to 20150317170448\n```\n\n### `mix ecto.rollback`\n\nThe `mix ecto.rollback` task will reverse the last migration we have run, undoing the schema changes. `ecto.migrate` and `ecto.rollback` are mirror images of each other.\n\n```console\n$ mix ecto.rollback\n[info] == Running Hello.Repo.Migrations.AddCommentsTable.change/0 backward\n[info] drop table comments\n[info] == Migrated in 0.0s\n```\n\n`ecto.rollback` will handle the same options as `ecto.migrate`, so `-n`, `--step`, `-v`, and `--to` will behave as they do for `ecto.migrate`.\n\n[`cast/3`]: `Ecto.Changeset.cast/3`\n[`from/2`]: `Ecto.Query.from/2`\n[`Repo.delete_all/2`]: `c:Ecto.Repo.delete_all/2`\n[`Repo.delete/2`]: `c:Ecto.Repo.delete/2`\n[`Repo.insert_all/3`]: `c:Ecto.Repo.insert_all/3`\n[`Repo.insert/2`]: `c:Ecto.Repo.insert/2`\n[`Repo.one/2`]: `c:Ecto.Repo.one/2`\n[`Repo.update_all/3`]: `c:Ecto.Repo.update_all/3`\n[`Repo.update/2`]: `c:Ecto.Repo.update/2`\n[`timestamps/1`]: `Ecto.Migration.timestamps/1`\n"
},
{
"path": "guides/howto/custom_error_pages.md",
"content": "# Custom Error Pages\n\nNew Phoenix projects have two error views called `ErrorHTML` and `ErrorJSON`, which live in `lib/hello_web/controllers/`. The purpose of these views is to handle errors in a general way for each format, from one centralized location.\n\n## The Error Views\n\nFor new applications, the `ErrorHTML` and `ErrorJSON` views looks like this:\n\n```elixir\ndefmodule HelloWeb.ErrorHTML do\n use HelloWeb, :html\n\n # If you want to customize your error pages,\n # uncomment the embed_templates/1 call below\n # and add pages to the error directory:\n #\n # * lib/<%= @lib_web_name %>/controllers/error_html/404.html.heex\n # * lib/<%= @lib_web_name %>/controllers/error_html/500.html.heex\n #\n # embed_templates \"error_html/*\"\n\n # The default is to render a plain text page based on\n # the template name. For example, \"404.html\" becomes\n # \"Not Found\".\n def render(template, _assigns) do\n Phoenix.Controller.status_message_from_template(template)\n end\nend\n\ndefmodule HelloWeb.ErrorJSON do\n # If you want to customize a particular status code,\n # you may add your own clauses, such as:\n #\n # def render(\"500.json\", _assigns) do\n # %{errors: %{detail: \"Internal Server Error\"}}\n # end\n\n # By default, Phoenix returns the status message from\n # the template name. For example, \"404.json\" becomes\n # \"Not Found\".\n def render(template, _assigns) do\n %{errors: %{detail: Phoenix.Controller.status_message_from_template(template)}}\n end\nend\n```\n\nBefore we dive into this, let's see what the rendered `404 Not Found` message looks like in a browser. In the development environment, Phoenix will debug errors by default, showing us a very informative debugging page. What we want here, however, is to see what page the application would serve in production. In order to do that, we need to set `debug_errors: false` in `config/dev.exs`.\n\n```elixir\nimport Config\n\nconfig :hello, HelloWeb.Endpoint,\n ...,\n debug_errors: false,\n code_reloader: true,\n ...\n```\n\nAfter modifying our config file, we need to restart our server in order for this change to take effect. After restarting the server, let's go to [http://localhost:4000/such/a/wrong/path](http://localhost:4000/such/a/wrong/path) for a running local application and see what we get.\n\nOk, that's not very exciting. We get the bare string \"Not Found\", displayed without any markup or styling.\n\nThe first question is, where does that error string come from? The answer is right in `ErrorHTML`.\n\n```elixir\ndef render(template, _assigns) do\n Phoenix.Controller.status_message_from_template(template)\nend\n```\n\nGreat, so we have this `render/2` function that takes a template and an `assigns` map, which we ignore. When you call `render(conn, :some_template)` from the controller, Phoenix first looks for a `some_template/1` function on the view module. If no function exists, it falls back to calling `render/2` with the template and format name, such as `\"some_template.html\"`.\n\nIn other words, to provide custom error pages, we could simply define a proper `render/2` function clause in `HelloWeb.ErrorHTML`.\n\n```elixir\n def render(\"404.html\", _assigns) do\n \"Page Not Found\"\n end\n```\n\nBut we can do even better.\n\nPhoenix generates an `ErrorHTML` for us, but it doesn't give us a `lib/hello_web/controllers/error_html` directory. Let's create one now. Inside our new directory, let's add a template named `404.html.heex` and give it some markup – a mixture of our application layout and a new `
` with our message to the user.\n\n```heex\n\n\n \n \n \n Welcome to Phoenix!\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
Sorry, the page you are looking for does not exist.
\n \n \n \n\n```\n\nAfter you define the template file, remember to remove the equivalent `render/2` clause for that template, as otherwise the function overrides the template. Let's do so for the 404.html clause we have previously introduced in `lib/hello_web/controllers/error_html.ex`. We also need to tell Phoenix to embed our templates into the module:\n\n```diff\n+ embed_templates \"error_html/*\"\n\n- def render(\"404.html\", _assigns) do\n- \"Page Not Found\"\n- end\n```\n\nNow, when we go back to [http://localhost:4000/such/a/wrong/path](http://localhost:4000/such/a/wrong/path), we should see a much nicer error page. It is worth noting that we did not render our `404.html.heex` template through our application layout, even though we want our error page to have the look and feel of the rest of our site. This is to avoid circular errors. For example, what happens if our application failed due to an error in the layout? Attempting to render the layout again will just trigger another error. So ideally we want to minimize the amount of dependencies and logic in our error templates, sharing only what is necessary.\n\n## Custom exceptions\n\nElixir provides a macro called `defexception/1` for defining custom exceptions. Exceptions are represented as structs, and structs need to be defined inside of modules.\n\nIn order to create a custom exception, we need to define a new module. Conventionally, this will have \"Error\" in the name. Inside that module, we need to define a new exception with `defexception/1`, the file `lib/hello_web.ex` seems like a good place for it.\n\n```elixir\ndefmodule HelloWeb.SomethingNotFoundError do\n defexception [:message]\nend\n```\n\nYou can raise your new exception like this:\n\n```elixir\nraise HelloWeb.SomethingNotFoundError, \"oops\"\n```\n\nBy default, Plug and Phoenix will treat all exceptions as 500 errors. However, Plug provides a protocol called `Plug.Exception` where we are able to customize the status and add actions that exception structs can return on the debug error page.\n\nIf we wanted to supply a status of 404 for an `HelloWeb.SomethingNotFoundError` error, we could do it by defining an implementation for the `Plug.Exception` protocol like this, in `lib/hello_web.ex`:\n\n```elixir\ndefimpl Plug.Exception, for: HelloWeb.SomethingNotFoundError do\n def status(_exception), do: 404\n def actions(_exception), do: []\nend\n```\n\nAlternatively, you could define a `plug_status` field directly in the exception struct:\n\n```elixir\ndefmodule HelloWeb.SomethingNotFoundError do\n defexception [:message, plug_status: 404]\nend\n```\n\nHowever, implementing the `Plug.Exception` protocol by hand can be convenient in certain occasions, such as when providing actionable errors.\n\n## Actionable errors\n\nException actions are functions that can be triggered from the error page, and they're basically a list of maps defining a `label` and a `handler` to be executed. As an example, Phoenix will display an error if you have pending migrations and will provide a button on the error page to perform the pending migrations.\n\nWhen `debug_errors` is `true`, they are rendered in the error page as a collection of buttons and follow the format of:\n\n```elixir\n[\n %{\n label: String.t(),\n handler: {module(), function :: atom(), args :: []}\n }\n]\n```\n\nIf we wanted to return some actions for an `HelloWeb.SomethingNotFoundError` we would implement `Plug.Exception` like this:\n\n```elixir\ndefimpl Plug.Exception, for: HelloWeb.SomethingNotFoundError do\n def status(_exception), do: 404\n\n def actions(_exception) do\n [\n %{\n label: \"Run seeds\",\n handler: {Code, :eval_file, [\"priv/repo/seeds.exs\"]}\n }\n ]\n end\nend\n```\n"
},
{
"path": "guides/howto/file_uploads.md",
"content": "# File Uploads\n\nOne common task for web applications is uploading files. These files might be images, videos, PDFs, or files of any other type. In order to upload files through an HTML interface, we need a `file` input tag in a multipart form.\n\n> #### Looking for the LiveView Uploads guide? {: .neutral}\n>\n> This guide explains multipart HTTP file uploads via `Plug.Upload`.\n> For more information about LiveView file uploads, including direct-to-cloud external uploads on\n> the client, refer to the [LiveView Uploads guide](https://hexdocs.pm/phoenix_live_view/uploads.html).\n\nPlug provides a `Plug.Upload` struct to hold the data from the `file` input. A `Plug.Upload` struct will automatically appear in your request parameters if a user has selected a file when they submit the form.\n\nIn this guide you will do the following:\n\n 1. Configure a multipart form\n\n 2. Add a file input element to the form\n\n 3. Verify your upload params\n\n 4. Manage your uploaded files\n\nIn the [`Contexts guide`](contexts.md), we generated an HTML resource for products. We can reuse the form we generated there in order to demonstrate how file uploads work in Phoenix. Please refer to that guide for instructions on generating the product resource you will be using here.\n\n### Configure a multipart form\n\nThe first thing you need to do is change your form into a multipart form. The `HelloWeb.CoreComponents` `form/1` component accepts a `multipart` attribute where you can specify this.\n\nHere is the form from `lib/hello_web/controllers/product_html/product_form.html.heex` with that change in place:\n\n```heex\n<.form :let={f} for={@changeset} action={@action} multipart>\n...\n```\n\n### Add a file input\n\nOnce you have a multipart form, you need a `file` input. Here's how you would do that, also in `product_form.html.heex`:\n\n```heex\n...\n <.input field={f[:photo]} type=\"file\" label=\"Photo\" />\n\n <.button>Save Product\n\n```\n\nWhen rendered, here is the HTML for the default `HelloWeb.CoreComponents` `input/1` component:\n\n```html\n
\n```\n\nGo to [http://localhost:4000/](http://localhost:4000/) and you should see the locale exhibited. Visit [http://localhost:4000/?locale=fr](http://localhost:4000/?locale=fr) and you should see the assign changed to `\"fr\"`. You can use this information alongside [Gettext](https://hexdocs.pm/gettext/Gettext.html) to provide a fully internationalized web application.\n\nThat's all there is to Plug. Phoenix embraces the plug design of composable transformations all the way up and down the stack. Let's see some examples!\n\n## Where to plug\n\nThe endpoint, router, and controllers in Phoenix accept plugs.\n\n### Endpoint plugs\n\nEndpoints organize all the plugs common to every request, and apply them before dispatching into the router with its custom pipelines. We added a plug to the endpoint like this:\n\n```elixir\ndefmodule HelloWeb.Endpoint do\n ...\n\n plug :introspect\n plug HelloWeb.Router\n```\n\nThe default endpoint plugs do quite a lot of work. Here they are in order:\n\n- `Plug.Static` - serves static assets. Since this plug comes before the logger, requests for static assets are not logged.\n\n- `Phoenix.LiveDashboard.RequestLogger` - sets up the *Request Logger* for Phoenix LiveDashboard, this will allow you to have the option to either pass a query parameter to stream requests logs or to enable/disable a cookie that streams requests logs from your dashboard.\n\n- `Plug.RequestId` - generates a unique request ID for each request.\n\n- `Plug.Telemetry` - adds instrumentation points so Phoenix can log the request path, status code and request time by default.\n\n- `Plug.Parsers` - parses the request body when a known parser is available. By default, this plug can handle URL-encoded, multipart and JSON content (with `Jason`). The request body is left untouched if the request content-type cannot be parsed.\n\n- `Plug.MethodOverride` - converts the request method to PUT, PATCH or DELETE for POST requests with a valid `_method` parameter.\n\n- `Plug.Head` - converts HEAD requests to GET requests.\n\n- `Plug.Session` - a plug that sets up session management. Note that `fetch_session/2` must still be explicitly called before using the session, as this plug just sets up how the session is fetched.\n\nIn the middle of the endpoint, there is also a conditional block:\n\n```elixir\n if code_reloading? do\n socket \"/phoenix/live_reload/socket\", Phoenix.LiveReloader.Socket\n plug Phoenix.LiveReloader\n plug Phoenix.CodeReloader\n plug Phoenix.Ecto.CheckRepoStatus, otp_app: :hello\n end\n```\n\nThis block is only executed in development. It enables:\n\n* live reloading - if you change a CSS file, they are updated in-browser without refreshing the page;\n* [code reloading](`Phoenix.CodeReloader`) - so we can see changes to our application without restarting the server;\n* check repo status - which makes sure our database is up to date, raising a readable and actionable error otherwise.\n\n### Router plugs\n\nIn the router, we can declare plugs inside pipelines:\n\n```elixir\ndefmodule HelloWeb.Router do\n use HelloWeb, :router\n\n pipeline :browser do\n plug :accepts, [\"html\"]\n plug :fetch_session\n plug :fetch_live_flash\n plug :put_root_layout, html: {HelloWeb.LayoutView, :root}\n plug :protect_from_forgery\n plug :put_secure_browser_headers\n plug HelloWeb.Plugs.Locale, \"en\"\n end\n\n scope \"/\", HelloWeb do\n pipe_through :browser\n\n get \"/\", PageController, :index\n end\n```\n\nRoutes are defined inside scopes and scopes may pipe through multiple pipelines. Once a route matches, Phoenix invokes all plugs defined in all pipelines associated to that route. For example, accessing \"/\" will pipe through the `:browser` pipeline, consequently invoking all of its plugs.\n\nAs we will see in the [routing guide](routing.html), the pipelines themselves are plugs. There, we will also discuss all plugs in the `:browser` pipeline.\n\n### Controller plugs\n\nFinally, controllers are plugs too, so we can do:\n\n```elixir\ndefmodule HelloWeb.PageController do\n use HelloWeb, :controller\n\n plug HelloWeb.Plugs.Locale, \"en\"\n```\n\nIn particular, controller plugs provide a feature that allows us to execute plugs only within certain actions. For example, you can do:\n\n```elixir\ndefmodule HelloWeb.PageController do\n use HelloWeb, :controller\n\n plug HelloWeb.Plugs.Locale, \"en\" when action in [:index]\n```\n\nAnd the plug will only be executed for the `index` action.\n\n## Plugs as composition\n\nBy abiding by the plug contract, we turn an application request into a series of explicit transformations. It doesn't stop there. To really see how effective Plug's design is, let's imagine a scenario where we need to check a series of conditions and then either redirect or halt if a condition fails. Without plug, we would end up with something like this:\n\n```elixir\ndefmodule HelloWeb.MessageController do\n use HelloWeb, :controller\n\n def show(conn, params) do\n case Authenticator.find_user(conn) do\n {:ok, user} ->\n case find_message(params[\"id\"]) do\n nil ->\n conn |> put_flash(:info, \"That message wasn't found\") |> redirect(to: ~p\"/\")\n message ->\n if Authorizer.can_access?(user, message) do\n render(conn, :show, page: message)\n else\n conn |> put_flash(:info, \"You can't access that page\") |> redirect(to: ~p\"/\")\n end\n end\n :error ->\n conn |> put_flash(:info, \"You must be logged in\") |> redirect(to: ~p\"/\")\n end\n end\nend\n```\n\nNotice how just a few steps of authentication and authorization require complicated nesting and duplication? Let's improve this with a couple of plugs.\n\n```elixir\ndefmodule HelloWeb.MessageController do\n use HelloWeb, :controller\n\n plug :authenticate\n plug :fetch_message\n plug :authorize_message\n\n def show(conn, params) do\n render(conn, :show, page: conn.assigns[:message])\n end\n\n defp authenticate(conn, _) do\n case Authenticator.find_user(conn) do\n {:ok, user} ->\n assign(conn, :user, user)\n :error ->\n conn |> put_flash(:info, \"You must be logged in\") |> redirect(to: ~p\"/\") |> halt()\n end\n end\n\n defp fetch_message(conn, _) do\n case find_message(conn.params[\"id\"]) do\n nil ->\n conn |> put_flash(:info, \"That message wasn't found\") |> redirect(to: ~p\"/\") |> halt()\n message ->\n assign(conn, :message, message)\n end\n end\n\n defp authorize_message(conn, _) do\n if Authorizer.can_access?(conn.assigns[:user], conn.assigns[:message]) do\n conn\n else\n conn |> put_flash(:info, \"You can't access that page\") |> redirect(to: ~p\"/\") |> halt()\n end\n end\nend\n```\n\nTo make this all work, we converted the nested blocks of code and used `halt(conn)` whenever we reached a failure path. The `halt(conn)` functionality is essential here: it tells Plug that the next plug should not be invoked.\n\nAt the end of the day, by replacing the nested blocks of code with a flattened series of plug transformations, we are able to achieve the same functionality in a much more composable, clear, and reusable way.\n\nTo learn more about plugs, see the documentation for the [Plug project](`Plug`), which provides many built-in plugs and functionalities.\n\n[`init/1`]: `c:Plug.init/1`\n[`call/2`]: `c:Plug.call/2`\n[`assign/3`]: `Plug.Conn.assign/3`\n"
},
{
"path": "guides/real_time/channels.md",
"content": "# Channels\n\n> **Requirement**: This guide expects that you have gone through the [introductory guides](installation.html) and got a Phoenix application [up and running](up_and_running.html).\n\nChannels are an exciting part of Phoenix that enable soft real-time communication with and between millions of connected clients.\n\nSome possible use cases include:\n\n- Chat rooms and APIs for messaging apps\n- Breaking news, like \"a goal was scored\" or \"an earthquake is coming\"\n- Tracking trains, trucks, or race participants on a map\n- Events in multiplayer games\n- Monitoring sensors and controlling lights\n- Notifying a browser that a page's CSS or JavaScript has changed (this is handy in development)\n\nConceptually, Channels are pretty simple.\n\nFirst, clients connect to the server using some transport, like WebSocket. Once connected, they join one or more topics. For example, to interact with a public chat room clients may join a topic called `public_chat`, and to receive updates from a product with ID 7, they may need to join a topic called `product_updates:7`.\n\nClients can push messages to the topics they've joined, and can also receive messages from them. The other way around, Channel servers receive messages from their connected clients, and can push messages to them too.\n\nServers are able to broadcast messages to all clients subscribed to a certain topic. This is illustrated in the following diagram:\n\n```plaintext\n +----------------+\n +--Topic X-->| Mobile Client |\n | +----------------+\n +-------------------+ |\n+----------------+ | | | +----------------+\n| Browser Client |--Topic X-->| Phoenix Server(s) |--+--Topic X-->| Desktop Client |\n+----------------+ | | | +----------------+\n +-------------------+ |\n | +----------------+\n +--Topic X-->| IoT Client |\n +----------------+\n```\n\nBroadcasts work even if the application runs on several nodes/computers. That is, if two clients have their socket connected to different application nodes and are subscribed to the same topic `T`, both of them will receive messages broadcasted to `T`. That is possible thanks to an internal PubSub mechanism.\n\nChannels can support any kind of client: a browser, native app, smart watch, embedded device, or anything else that can connect to a network.\nAll the client needs is a suitable library; see the [Client Libraries](#client-libraries) section below.\nEach client library communicates using one of the \"transports\" that Channels understand.\nCurrently, that's either Websockets or long polling, but other transports may be added in the future.\n\nUnlike stateless HTTP connections, Channels support long-lived connections, each backed by a lightweight Erlang VM process, working in parallel and maintaining its own state.\n\nThis architecture scales well; Phoenix Channels [can support millions of subscribers with reasonable latency on a single box](https://phoenixframework.org/blog/the-road-to-2-million-websocket-connections), passing hundreds of thousands of messages per second.\nAnd that capacity can be multiplied by adding more nodes to the cluster.\n\n## The Moving Parts\n\nAlthough Channels are simple to use from a client perspective, there are a number of components involved in routing messages to clients across a cluster of servers.\nLet's take a look at them.\n\n### Overview\n\nTo start communicating, a client connects to a node (a Phoenix server) using a transport (e.g., Websockets or long polling) and joins one or more channels using that single network connection.\nOne channel server lightweight process is created per client, per topic. Each channel holds onto the `%Phoenix.Socket{}` and can maintain any state it needs within its `socket.assigns`.\n\nOnce the connection is established, each incoming message from a client is routed, based on its topic, to the correct channel server.\nIf the channel server asks to broadcast a message, that message is sent to the local PubSub, which sends it out to any clients connected to the same server and subscribed to that topic.\n\nIf there are other nodes in the cluster, the local PubSub also forwards the message to their PubSubs, which send it out to their own subscribers.\nBecause only one message has to be sent per additional node, the performance cost of adding nodes is negligible, while each new node supports many more subscribers.\n\nThe message flow looks something like this:\n\n```plaintext\n Channel +-------------------------+ +--------+\n route | Sending Client, Topic 1 | | Local |\n +----------->| Channel.Server |----->| PubSub |--+\n+----------------+ | +-------------------------+ +--------+ |\n| Sending Client |-Transport--+ | |\n+----------------+ +-------------------------+ | |\n | Sending Client, Topic 2 | | |\n | Channel.Server | | |\n +-------------------------+ | |\n | |\n +-------------------------+ | |\n+----------------+ | Browser Client, Topic 1 | | |\n| Browser Client |<-------Transport--------| Channel.Server |<----------+ |\n+----------------+ +-------------------------+ |\n |\n |\n |\n +-------------------------+ |\n+----------------+ | Phone Client, Topic 1 | |\n| Phone Client |<-------Transport--------| Channel.Server |<-+ |\n+----------------+ +-------------------------+ | +--------+ |\n | | Remote | |\n +-------------------------+ +---| PubSub |<-+\n+----------------+ | Watch Client, Topic 1 | | +--------+ |\n| Watch Client |<-------Transport--------| Channel.Server |<-+ |\n+----------------+ +-------------------------+ |\n |\n |\n +-------------------------+ +--------+ |\n+----------------+ | IoT Client, Topic 1 | | Remote | |\n| IoT Client |<-------Transport--------| Channel.Server |<-----| PubSub |<-+\n+----------------+ +-------------------------+ +--------+\n```\n\n### Endpoint\n\nIn your Phoenix app's `Endpoint` module, a `socket` declaration specifies which socket handler will receive connections on a given URL.\n\n```elixir\nsocket \"/socket\", HelloWeb.UserSocket,\n websocket: true,\n longpoll: false,\n auth_token: true\n```\n\nPhoenix comes with two default transports: websocket and longpoll. You can configure them directly via the `socket` declaration.\n\n### Socket Handlers\n\nOn the client side, you will establish a socket connection to the route above:\n\n```javascript\nlet socket = new Socket(\"/socket\", {authToken: window.userToken})\n```\n\nOn the server, Phoenix will invoke `HelloWeb.UserSocket.connect/2`, passing your parameters and the initial socket state. Within the socket, you can authenticate and identify a socket connection and set default socket assigns. The socket is also where you define your channel routes.\n\n### Channel Routes\n\nChannel routes match on the topic string and dispatch matching requests to the given Channel module.\n\nThe star character `*` acts as a wildcard matcher, so in the following example route, requests for `room:lobby` and `room:123` would both be dispatched to the `RoomChannel`. In your `UserSocket`, you would have:\n\n```elixir\nchannel \"room:*\", HelloWeb.RoomChannel\n```\n\n### Channels\n\nChannels handle events from clients, so they are similar to Controllers, but there are two key differences. Channel events can go both directions - incoming and outgoing. Channel connections also persist beyond a single request/response cycle. Channels are the highest level abstraction for real-time communication components in Phoenix.\n\nEach Channel will implement one or more clauses of each of these four callback functions - `join/3`, `terminate/2`, `handle_in/3`, and `handle_out/3`.\n\n### Topics\n\nTopics are string identifiers - names that the various layers use in order to make sure messages end up in the right place. As we saw above, topics can use wildcards. This allows for a useful `\"topic:subtopic\"` convention. Often, you'll compose topics using record IDs from your application layer, such as `\"users:123\"`.\n\n### Messages\n\nThe `Phoenix.Socket.Message` module defines a struct with the following keys which denotes a valid message. From the [Phoenix.Socket.Message docs](https://hexdocs.pm/phoenix/Phoenix.Socket.Message.html).\n\n- `topic` - The string topic or `\"topic:subtopic\"` pair namespace, such as `\"messages\"` or `\"messages:123\"`\n- `event` - The string event name, for example `\"phx_join\"`\n- `payload` - The message payload\n- `ref` - The unique string ref\n\n### PubSub\n\nPubSub is provided by the `Phoenix.PubSub` module. Interested parties can receive events by subscribing to topics. Other processes can broadcast events to certain topics.\n\nThis is useful to broadcast messages on channel and also for application development in general. For instance, letting all connected [live views](https://github.com/phoenixframework/phoenix_live_view) to know that a new comment has been added to a post.\n\nThe PubSub system takes care of getting messages from one node to another so that they can be sent to all subscribers across the cluster.\nBy default, this is done using [Phoenix.PubSub.PG2](https://hexdocs.pm/phoenix_pubsub/Phoenix.PubSub.PG2.html), which uses native Erlang VM messaging.\n\nIf your deployment environment does not support distributed Elixir or direct communication between servers, Phoenix also ships with a [Redis Adapter](https://hexdocs.pm/phoenix_pubsub_redis/Phoenix.PubSub.Redis.html) that uses Redis to exchange PubSub data. Please see the [Phoenix.PubSub docs](https://hexdocs.pm/phoenix_pubsub/Phoenix.PubSub.html) for more information.\n\n### Client Libraries\n\nAny networked device can connect to Phoenix Channels as long as it has a client library.\nThe following libraries exist today, and new ones are always welcome; to write your own, see our how-to guide [Writing a Channels Client](writing_a_channels_client.md).\n\n#### Official\n\nPhoenix ships with a JavaScript client that is available when generating a new Phoenix project. The documentation for the JavaScript module is available at [https://hexdocs.pm/phoenix/js/](https://hexdocs.pm/phoenix/js/); the code is in [multiple js files](https://github.com/phoenixframework/phoenix/blob/main/assets/js/phoenix/).\n\n#### 3rd Party\n\n+ Swift (iOS)\n - [SwiftPhoenix](https://github.com/davidstump/SwiftPhoenixClient)\n+ Java (Android)\n - [JavaPhoenixChannels](https://github.com/eoinsha/JavaPhoenixChannels)\n+ Kotlin (Android)\n - [JavaPhoenixClient](https://github.com/dsrees/JavaPhoenixClient)\n+ C#\n - [PhoenixSharp](https://github.com/Mazyod/PhoenixSharp)\n+ Elixir\n - [phoenix_gen_socket_client](https://github.com/Aircloak/phoenix_gen_socket_client)\n - [slipstream](https://hexdocs.pm/slipstream/Slipstream.html)\n+ GDScript (Godot Game Engine)\n - [GodotPhoenixChannels](https://github.com/alfredbaudisch/GodotPhoenixChannels)\n\n## Tying it all together\n\nLet's tie all these ideas together by building a simple chat application. Make sure [you created a new Phoenix application](https://hexdocs.pm/phoenix/up_and_running.html) and now we are ready to generate the `UserSocket`.\n\n### Generating a socket\n\nLet's invoke the socket generator to get started:\n\n```console\n$ mix phx.gen.socket User\n```\n\nIt will create two files, the client code in `assets/js/user_socket.js` and the server counter-part in `lib/hello_web/channels/user_socket.ex`. After running, the generator will also ask to add the following line to `lib/hello_web/endpoint.ex`:\n\n```elixir\ndefmodule HelloWeb.Endpoint do\n use Phoenix.Endpoint, otp_app: :hello\n\n socket \"/socket\", HelloWeb.UserSocket,\n websocket: true,\n longpoll: false\n\n ...\nend\n```\n\nThe generator also asks us to import the client code, we will do that later.\n\nNext, we will configure our socket to ensure messages get routed to the correct channel. To do that, we'll uncomment the `\"room:*\"` channel definition:\n\n```elixir\ndefmodule HelloWeb.UserSocket do\n use Phoenix.Socket\n\n ## Channels\n channel \"room:*\", HelloWeb.RoomChannel\n ...\n```\n\nNow, whenever a client sends a message whose topic starts with `\"room:\"`, it will be routed to our RoomChannel. Next, we'll define a `HelloWeb.RoomChannel` module to manage our chat room messages.\n\n### Joining Channels\n\nThe first priority of your channels is to authorize clients to join a given topic. For authorization, we must implement `join/3` in `lib/hello_web/channels/room_channel.ex`.\n\n```elixir\ndefmodule HelloWeb.RoomChannel do\n use Phoenix.Channel\n\n def join(\"room:lobby\", _message, socket) do\n {:ok, socket}\n end\n\n def join(\"room:\" <> _private_room_id, _params, _socket) do\n {:error, %{reason: \"unauthorized\"}}\n end\nend\n```\n\nFor our chat app, we'll allow anyone to join the `\"room:lobby\"` topic, but any other room will be considered private and special authorization, say from a database, will be required.\n(We won't worry about private chat rooms for this exercise, but feel free to explore after we finish.)\n\nWith our channel in place, let's get the client and server talking.\n\nThe generated `assets/js/user_socket.js` defines a simple client based on the socket implementation that ships with Phoenix.\n\nWe can use that library to connect to our socket and join our channel, we just need to set our room name to `\"room:lobby\"` in that file.\n\n```javascript\n// assets/js/user_socket.js\n// ...\nsocket.connect()\n\n// Now that you are connected, you can join channels with a topic:\nlet channel = socket.channel(\"room:lobby\", {})\nchannel.join()\n .receive(\"ok\", resp => { console.log(\"Joined successfully\", resp) })\n .receive(\"error\", resp => { console.log(\"Unable to join\", resp) })\n\nexport default socket\n```\n\nAfter that, we need to make sure `assets/js/user_socket.js` gets imported into our application JavaScript file. To do that, uncomment this line in `assets/js/app.js`.\n\n```javascript\n// ...\nimport \"./user_socket.js\"\n```\n\nSave the file and your browser should auto refresh, thanks to the Phoenix live reloader. If everything worked, we should see \"Joined successfully\" in the browser's JavaScript console. Our client and server are now talking over a persistent connection. Now let's make it useful by enabling chat.\n\nIn `lib/hello_web/controllers/page_html/home.html.heex`, we'll replace the existing code with a container to hold our chat messages, and an input field to send them:\n\n```heex\n\n\n```\n\nNow let's add a couple of event listeners to `assets/js/user_socket.js`:\n\n```javascript\n// ...\nlet channel = socket.channel(\"room:lobby\", {})\nlet chatInput = document.querySelector(\"#chat-input\")\nlet messagesContainer = document.querySelector(\"#messages\")\n\nchatInput.addEventListener(\"keypress\", event => {\n if(event.key === 'Enter'){\n channel.push(\"new_msg\", {body: chatInput.value})\n chatInput.value = \"\"\n }\n})\n\nchannel.join()\n .receive(\"ok\", resp => { console.log(\"Joined successfully\", resp) })\n .receive(\"error\", resp => { console.log(\"Unable to join\", resp) })\n\nexport default socket\n```\n\nAll we had to do is detect that enter was pressed and then `push` an event over the channel with the message body. We named the event `\"new_msg\"`. With this in place, let's handle the other piece of a chat application, where we listen for new messages and append them to our messages container.\n\n```javascript\n// ...\nlet channel = socket.channel(\"room:lobby\", {})\nlet chatInput = document.querySelector(\"#chat-input\")\nlet messagesContainer = document.querySelector(\"#messages\")\n\nchatInput.addEventListener(\"keypress\", event => {\n if(event.key === 'Enter'){\n channel.push(\"new_msg\", {body: chatInput.value})\n chatInput.value = \"\"\n }\n})\n\nchannel.on(\"new_msg\", payload => {\n let messageItem = document.createElement(\"p\")\n messageItem.innerText = `[${Date()}] ${payload.body}`\n messagesContainer.appendChild(messageItem)\n})\n\nchannel.join()\n .receive(\"ok\", resp => { console.log(\"Joined successfully\", resp) })\n .receive(\"error\", resp => { console.log(\"Unable to join\", resp) })\n\nexport default socket\n```\n\nWe listen for the `\"new_msg\"` event using `channel.on`, and then append the message body to the DOM. Now let's handle the incoming and outgoing events on the server to complete the picture.\n\n### Incoming Events\n\nWe handle incoming events with `handle_in/3`. We can pattern match on the event names, like `\"new_msg\"`, and then grab the payload that the client passed over the channel. For our chat application, we simply need to notify all other `room:lobby` subscribers of the new message with `broadcast!/3`.\n\n```elixir\ndefmodule HelloWeb.RoomChannel do\n use Phoenix.Channel\n\n def join(\"room:lobby\", _message, socket) do\n {:ok, socket}\n end\n\n def join(\"room:\" <> _private_room_id, _params, _socket) do\n {:error, %{reason: \"unauthorized\"}}\n end\n\n def handle_in(\"new_msg\", %{\"body\" => body}, socket) do\n broadcast!(socket, \"new_msg\", %{body: body})\n {:noreply, socket}\n end\nend\n```\n\n`broadcast!/3` will notify all joined clients on this `socket`'s topic and invoke their `handle_out/3` callbacks. `handle_out/3` isn't a required callback, but it allows us to customize and filter broadcasts before they reach each client. By default, `handle_out/3` is implemented for us and simply pushes the message on to the client. Hooking into outgoing events allows for powerful message customization and filtering. Let's see how.\n\n### Intercepting Outgoing Events\n\nWe won't implement this for our application, but imagine our chat app allowed users to ignore messages about new users joining a room. We could implement that behavior like this, where we explicitly tell Phoenix which outgoing event we want to intercept and then define a `handle_out/3` callback for those events. (Of course, this assumes that we have an `Accounts` context with an `ignoring_user?/2` function, and that we pass a user in via the `assigns` map). It is important to note that the `handle_out/3` callback will be called for every recipient of a message, so more expensive operations like hitting the database should be considered carefully before being included in `handle_out/3`.\n\n```elixir\nintercept [\"user_joined\"]\n\ndef handle_out(\"user_joined\", msg, socket) do\n if Accounts.ignoring_user?(socket.assigns[:user], msg.user_id) do\n {:noreply, socket}\n else\n push(socket, \"user_joined\", msg)\n {:noreply, socket}\n end\nend\n```\n\nThat's all there is to our basic chat app. Fire up multiple browser tabs and you should see your messages being pushed and broadcasted to all windows!\n\n## Using Token Authentication\n\nWhen we connect, we'll often need to authenticate the client. Fortunately, this is a 5-step process with [Phoenix.Token](https://hexdocs.pm/phoenix/Phoenix.Token.html).\n\n### Step 1 - Enable the `auth_token` functionality in the socket\n\nPhoenix supports a transport agnostic way to pass an authentication token to the server. To enable this, we need to pass the `:auth_token` option to the socket declaration in our `Endpoint` module.\n\n```elixir\ndefmodule HelloWeb.Endpoint do\n use Phoenix.Endpoint, otp_app: :hello\n\n socket \"/socket\", HelloWeb.UserSocket,\n websocket: true,\n longpoll: false,\n auth_token: true\n\n ...\nend\n```\n\n### Step 2 - Assign a Token in the Connection\n\nLet's say we have an authentication plug in our app called `OurAuth`. When `OurAuth` authenticates a user, it sets a value for the `:current_user` key in `conn.assigns`. Since the `current_user` exists, we can simply assign the user's token in the connection for use in the layout. We can wrap that behavior up in a private function plug, `put_user_token/2`. This could also be put in its own module as well. To make this all work, we just add `OurAuth` and `put_user_token/2` to the browser pipeline.\n\n```elixir\npipeline :browser do\n ...\n plug OurAuth\n plug :put_user_token\nend\n\ndefp put_user_token(conn, _) do\n if current_user = conn.assigns[:current_user] do\n token = Phoenix.Token.sign(conn, \"user socket\", current_user.id)\n assign(conn, :user_token, token)\n else\n conn\n end\nend\n```\n\nNow our `conn.assigns` contains the `current_user` and `user_token`.\n\n### Step 3 - Pass the Token to the JavaScript\n\nNext, we need to pass this token to JavaScript. We can do so inside a script tag in `lib/hello_web/components/layouts/root.html.heex` right above the app.js script, as follows:\n\n```heex\n\n\n```\n\n### Step 4 - Pass the Token to the Socket Constructor and Verify\n\nWe also need to pass the `:auth_token` to the socket constructor and verify the user token in the `connect/3` function. To do so, edit `lib/hello_web/channels/user_socket.ex`, as follows:\n\n```elixir\ndef connect(_params_, socket, connect_info) do\n # max_age: 1209600 is equivalent to two weeks in seconds\n case Phoenix.Token.verify(socket, \"user socket\", connect_info[:auth_token], max_age: 1209600) do\n {:ok, user_id} ->\n {:ok, assign(socket, :current_user, user_id)}\n {:error, reason} ->\n :error\n end\nend\n```\n\nIn our JavaScript, we can use the token set previously when constructing the Socket:\n\n```javascript\nlet socket = new Socket(\"/socket\", {authToken: window.userToken})\n```\n\nWe used `Phoenix.Token.verify/4` to verify the user token provided by the client. `Phoenix.Token.verify/4` returns either `{:ok, user_id}` or `{:error, reason}`. We can pattern match on that return in a `case` statement. With a verified token, we set the user's id as the value to `:current_user` in the socket. Otherwise, we return `:error`.\n\n### Step 5 - Connect to the socket in JavaScript\n\nWith authentication set up, we can connect to sockets and channels from JavaScript.\n\n```javascript\nlet socket = new Socket(\"/socket\", {authToken: window.userToken})\nsocket.connect()\n```\n\nNow that we are connected, we can join channels with a topic:\n\n```javascript\nlet channel = socket.channel(\"topic:subtopic\", {})\nchannel.join()\n .receive(\"ok\", resp => { console.log(\"Joined successfully\", resp) })\n .receive(\"error\", resp => { console.log(\"Unable to join\", resp) })\n\nexport default socket\n```\n\nNote that token authentication is preferable since it's transport agnostic and well-suited for long running-connections like channels, as opposed to using sessions or other authentication approaches.\n\n## Fault Tolerance and Reliability Guarantees\n\nServers restart, networks split, and clients lose connectivity. In order to design robust systems, we need to understand how Phoenix responds to these events and what guarantees it offers.\n\n### Handling Reconnection\n\nClients subscribe to topics, and Phoenix stores those subscriptions in an in-memory ETS table. If a channel crashes, the clients will need to reconnect to the topics they had previously subscribed to. Fortunately, the Phoenix JavaScript client knows how to do this. The server will notify all the clients of the crash. This will trigger each client's `Channel.onError` callback. The clients will attempt to reconnect to the server using an exponential backoff strategy. Once they reconnect, they'll attempt to rejoin the topics they had previously subscribed to. If they are successful, they'll start receiving messages from those topics as before.\n\n### Resending Client Messages\n\nChannel clients queue outgoing messages into a `PushBuffer`, and send them to the server when there is a connection. If no connection is available, the client holds on to the messages until it can establish a new connection. With no connection, the client will hold the messages in memory until it establishes a connection, or until it receives a `timeout` event. The default timeout is set to 5000 milliseconds. The client won't persist the messages in the browser's local storage, so if the browser tab closes, the messages will be gone.\n\n### Resending Server Messages\n\nPhoenix uses an at-most-once strategy when sending messages to clients. If the client is offline and misses the message, Phoenix won't resend it. Phoenix doesn't persist messages on the server. If the server restarts, unsent messages will be gone. If our application needs stronger guarantees around message delivery, we'll need to write that code ourselves. Common approaches involve persisting messages on the server and having clients request missing messages. \n\nFor example, you can track a `last_seen_id` (or `last_updated_at`) on the client. On join, the client will pass the `last_seen_id` via the channel params for the last thing it saw, which lets the server know how to catch the client up with side effects that have happened since that id. On the client, anytime an event is received for a \"new_message\", the client bumps its `last_seen_id` so that it can recover gracefully across disconnect/reconnect. The code might look something like this:\n\n```javascript\n// on the client\nlet socket = new Socket(...)\n\nlet lastSeenMsg = {}\nlet roomParams = () => lastSeenMsg.id ? {last_seen_id: lastSeenMsg.id} : {}\nlet roomChannel = socket.channel(\"rooms:123\", roomParams)\n\nroomChannel.on(\"new_message\", msg => {\n lastSeenMsg = msg\n renderNewMessage(msg)\n})\n\nroomChannel.join().receive(\"ok\", ({messages}) => {\n lastSeenMsg = messages[messages.length - 1]\n renderMessages(messages)\n})\n```\n\n```elixir\n# room_channel.ex on the server\ndef join(\"rooms:\" <> id, params, socket) do\n ...\n messages = fetch_messages_since(params[\"last_seen_id\"])\n {:ok, %{messages: messages}, socket}\nend\n```\n\n## Example Application\n\nTo see an example of the application we just built, checkout the project [phoenix_chat_example](https://github.com/chrismccord/phoenix_chat_example).\n"
},
{
"path": "guides/real_time/presence.md",
"content": "# Presence\n\n> **Requirement**: This guide expects that you have gone through the [introductory guides](installation.html) and got a Phoenix application [up and running](up_and_running.html).\n\n> **Requirement**: This guide expects that you have gone through the [Channels guide](channels.html).\n\nPhoenix Presence is a feature which allows you to register process information on a topic and replicate it transparently across a cluster. It's a combination of both a server-side and client-side library, which makes it simple to implement. A simple use-case would be showing which users are currently online in an application.\n\nPhoenix Presence is special for a number of reasons. It has no single point of failure, no single source of truth, relies entirely on the standard library with no operational dependencies and self-heals.\n\n## Setting up\n\nWe are going to use Presence to track which users are connected on the server and send updates to the client as users join and leave. We will deliver those updates via Phoenix Channels. Therefore, let's create a `RoomChannel`, as we did in the channels guides:\n\n```console\n$ mix phx.gen.channel Room\n```\n\nFollow the steps after the generator and you are ready to start tracking presence.\n\n## The Presence generator\n\nTo get started with Presence, we'll first need to generate a presence module. We can do this with the `mix phx.gen.presence` task:\n\n```console\n$ mix phx.gen.presence\n* creating lib/hello_web/channels/presence.ex\n\nAdd your new module to your supervision tree,\nin lib/hello/application.ex:\n\n children = [\n ...\n HelloWeb.Presence,\n ]\n\nYou're all set! See the Phoenix.Presence docs for more details:\nhttps://hexdocs.pm/phoenix/Phoenix.Presence.html\n```\n\nIf we open up the `lib/hello_web/channels/presence.ex` file, we will see the following line:\n\n```elixir\nuse Phoenix.Presence,\n otp_app: :hello,\n pubsub_server: Hello.PubSub\n```\n\nThis sets up the module for presence, defining the functions we require for tracking presences. As mentioned in the generator task, we should add this module to our supervision tree in\n`application.ex`:\n\n```elixir\nchildren = [\n ...\n HelloWeb.Presence,\n]\n```\n\n## Usage With Channels and JavaScript\n\nNext, we will create the channel that we'll communicate presence over. After a user joins, we can push the list of presences down the channel and then track the connection. We can also provide a map of additional information to track.\n\n```elixir\ndefmodule HelloWeb.RoomChannel do\n use Phoenix.Channel\n alias HelloWeb.Presence\n\n def join(\"room:lobby\", %{\"name\" => name}, socket) do\n send(self(), :after_join)\n {:ok, assign(socket, :name, name)}\n end\n\n def handle_info(:after_join, socket) do\n {:ok, _} =\n Presence.track(socket, socket.assigns.name, %{\n online_at: inspect(System.system_time(:second))\n })\n\n push(socket, \"presence_state\", Presence.list(socket))\n {:noreply, socket}\n end\nend\n```\n\nFinally, we can use the client-side Presence library included in `phoenix.js` to manage the state and presence diffs that come down the socket. It listens for the `\"presence_state\"` and `\"presence_diff\"` events and provides a simple callback for you to handle the events as they happen, with the `onSync` callback.\n\nThe `onSync` callback allows you to easily react to presence state changes, which most often results in re-rendering an updated list of active users. You can use the `list` method to format and return each individual presence based on the needs of your application.\n\nTo iterate users, we use the `presences.list()` function which accepts a callback. The callback will be called for each presence item with 2 arguments, the presence id and a list of metas (one for each presence for that presence id). We use this to display the users and the number of devices they are online with.\n\nWe can see presence working by adding the following to `assets/js/app.js`:\n\n```javascript\nimport {Socket, Presence} from \"phoenix\"\n\nlet socket = new Socket(\"/socket\", {authToken: window.userToken})\nlet channel = socket.channel(\"room:lobby\", {name: window.location.search.split(\"=\")[1]})\nlet presence = new Presence(channel)\n\nfunction renderOnlineUsers(presence) {\n let response = \"\"\n\n presence.list((id, {metas: [first, ...rest]}) => {\n let count = rest.length + 1\n response += ` ${id} (count: ${count})`\n })\n\n document.querySelector(\"main\").innerHTML = response\n}\n\nsocket.connect()\n\npresence.onSync(() => renderOnlineUsers(presence))\n\nchannel.join()\n```\n\nWe can ensure this is working by opening 3 browser tabs. If we navigate to on two browser tabs and then we should see:\n\n```plaintext\nAlice (count: 2)\nBob (count: 1)\n```\n\nIf we close one of the Alice tabs, then the count should decrease to 1. If we close another tab, the user should disappear from the list entirely.\n\n### Making it safe\n\nIn our initial implementation, we are passing the name of the user as part of the URL. However, in many systems, you want to allow only logged in users to access the presence functionality. To do so, you should set up token authentication, [as detailed in the token authentication section of the channels guide](channels.html#using-token-authentication).\n\nWith token authentication, you should access `socket.assigns.user_id`, set in `UserSocket`, instead of `socket.assigns.name` set from parameters.\n\n## Usage With LiveView\n\nWhilst Phoenix does ship with a JavaScript API for dealing with presence, it is also possible to extend the `HelloWeb.Presence` module to support [LiveView](https://hexdocs.pm/phoenix_live_view).\n\nOne thing to keep in mind when dealing with LiveView, is that each LiveView is a stateful process, so if we keep the presence state in the LiveView, each LiveView process will contain the full list of online users in memory. Instead, we can keep track of the online users within the `Presence` process, and pass separate events to the LiveView, which can use a stream to update the online list.\n\nTo start with, we need to update the `lib/hello_web/channels/presence.ex` file to add some optional callbacks to the `HelloWeb.Presence` module.\n\nFirstly, we add the `init/1` callback. This allows us to keep track of the presence state within the process.\n\n```elixir\n def init(_opts) do\n {:ok, %{}}\n end\n```\n\nThe presence module also allows a `fetch/2` callback, this allows the data fetched from the presence to be modified, allowing us to define the shape of the response. In this case we are adding an `id` and a `user` map.\n\n```elixir\n def fetch(_topic, presences) do\n for {key, %{metas: [meta | metas]}} <- presences, into: %{} do\n # user can be populated here from the database here we populate\n # the name for demonstration purposes\n {key, %{metas: [meta | metas], id: meta.id, user: %{name: meta.id}}}\n end\n end\n```\n\nThe final thing to add is the `handle_metas/4` callback. This callback updates the state that we keep track of in `HelloWeb.Presence` based on the user leaves and joins.\n\n```elixir\n def handle_metas(topic, %{joins: joins, leaves: leaves}, presences, state) do\n for {user_id, presence} <- joins do\n user_data = %{id: user_id, user: presence.user, metas: Map.fetch!(presences, user_id)}\n msg = {__MODULE__, {:join, user_data}}\n Phoenix.PubSub.local_broadcast(Hello.PubSub, \"proxy:#{topic}\", msg)\n end\n\n for {user_id, presence} <- leaves do\n metas =\n case Map.fetch(presences, user_id) do\n {:ok, presence_metas} -> presence_metas\n :error -> []\n end\n\n user_data = %{id: user_id, user: presence.user, metas: metas}\n msg = {__MODULE__, {:leave, user_data}}\n Phoenix.PubSub.local_broadcast(Hello.PubSub, \"proxy:#{topic}\", msg)\n end\n\n {:ok, state}\n end\n```\n\nYou can see that we are broadcasting events for the joins and leaves. These will be listened to by the LiveView process. You'll also see that we use \"proxy\" channel when broadcasting the joins and leaves. This is because we don't want our LiveView process to receive the presence events directly. We can add a few helper functions so that this particular implementation detail is abstracted from the LiveView module.\n\n```elixir\n def list_online_users(), do: list(\"online_users\") |> Enum.map(fn {_id, presence} -> presence end)\n\n def track_user(name, params), do: track(self(), \"online_users\", name, params)\n\n def subscribe(), do: Phoenix.PubSub.subscribe(Hello.PubSub, \"proxy:online_users\")\n```\n\nNow that we have our presence module set up and broadcasting events, we can create a LiveView. Create a new file `lib/hello_web/live/online/index.ex` with the following contents:\n\n```elixir\ndefmodule HelloWeb.OnlineLive do\n use HelloWeb, :live_view\n\n def mount(params, _session, socket) do\n socket = stream(socket, :presences, [])\n socket =\n if connected?(socket) do\n HelloWeb.Presence.track_user(params[\"name\"], %{id: params[\"name\"]})\n HelloWeb.Presence.subscribe()\n stream(socket, :presences, HelloWeb.Presence.list_online_users())\n else\n socket\n end\n\n {:ok, socket}\n end\n\n def render(assigns) do\n ~H\"\"\"\n
\n
{id} ({length(metas)})
\n
\n \"\"\"\n end\n\n def handle_info({HelloWeb.Presence, {:join, presence}}, socket) do\n {:noreply, stream_insert(socket, :presences, presence)}\n end\n\n def handle_info({HelloWeb.Presence, {:leave, presence}}, socket) do\n if presence.metas == [] do\n {:noreply, stream_delete(socket, :presences, presence)}\n else\n {:noreply, stream_insert(socket, :presences, presence)}\n end\n end\nend\n```\n\nIf we add this route to the `lib/hello_web/router.ex`:\n\n```elixir\n live \"/online/:name\", OnlineLive, :index\n```\n\nThen we can navigate to http://localhost:4000/online/Alice in one tab, and http://localhost:4000/online/Bob in another, you'll see that the presences are tracked, along with the number of presences per user. Opening and closing tabs with various users will update the presence list in real-time.\n"
},
{
"path": "guides/request_lifecycle.md",
"content": "# Request life-cycle\n\n> **Requirement**: This guide expects that you have gone through the [introductory guides](installation.html) and got a Phoenix application [up and running](up_and_running.html).\n\nThe goal of this guide is to talk about Phoenix's request life-cycle. This guide will take a practical approach where we will learn by doing: we will add two new pages to our Phoenix project and comment on how the pieces fit together along the way.\n\nLet's get on with our first new Phoenix page!\n\n## Adding a new page\n\nWhen your browser accesses [http://localhost:4000/](http://localhost:4000/), it sends an HTTP request to whatever service is running on that address, in this case our Phoenix application. The HTTP request is made of a verb and a path. For example, the following browser requests translate into:\n\n| Browser address bar | Verb | Path |\n|:------------------------------------|:-----|:--------------|\n| | GET | / |\n| | GET | /hello |\n| | GET | /hello/world |\n\nThere are other HTTP verbs. For example, submitting a form typically uses the POST verb.\n\nWeb applications typically handle requests by mapping each verb/path pair onto a specific part of your application. In Phoenix, this mapping is done by the router. For example, we may map \"/articles\" to a portion of our application that shows all articles. Therefore, to add a new page, our first task is to add a new route.\n\n### A new route\n\nThe router maps unique HTTP verb/path pairs to controller/action pairs which will handle them. Controllers in Phoenix are simply Elixir modules. Actions are functions that are defined within these controllers.\n\nPhoenix generates a router file for us in new applications at `lib/hello_web/router.ex`. This is where we will be working for this section.\n\nThe route for our \"Welcome to Phoenix!\" page from the previous [Up And Running Guide](up_and_running.html) looks like this:\n\n```elixir\nget \"/\", PageController, :home\n```\n\nLet's digest what this route is telling us. Visiting [http://localhost:4000/](http://localhost:4000/) issues an HTTP `GET` request to the root path. All requests like this will be handled by the `home/2` function in the `HelloWeb.PageController` module defined in `lib/hello_web/controllers/page_controller.ex`.\n\nThe page we are going to build will say \"Hello World, from Phoenix!\" when we point our browser to [http://localhost:4000/hello](http://localhost:4000/hello).\n\nThe first thing we need to do is to create the page route for a new page. Let's open up `lib/hello_web/router.ex` in a text editor. For a brand new application, it looks like this:\n\n```elixir\ndefmodule HelloWeb.Router do\n use HelloWeb, :router\n\n pipeline :browser do\n plug :accepts, [\"html\"]\n plug :fetch_session\n plug :fetch_live_flash\n plug :put_root_layout, html: {HelloWeb.Layouts, :root}\n plug :protect_from_forgery\n plug :put_secure_browser_headers\n end\n\n pipeline :api do\n plug :accepts, [\"json\"]\n end\n\n scope \"/\", HelloWeb do\n pipe_through :browser\n\n get \"/\", PageController, :home\n end\n\n # Other scopes may use custom stacks.\n # scope \"/api\", HelloWeb do\n # pipe_through :api\n # end\n\n # ...\nend\n```\n\nFor now, we'll ignore the pipelines and the use of `scope` here and just focus on adding a route. We will discuss those in the [Routing guide](routing.html).\n\nLet's add a new route to the router that maps a `GET` request for `/hello` to the `index` action of a soon-to-be-created `HelloWeb.HelloController` inside the `scope \"/\" do` block of the router:\n\n```elixir\nscope \"/\", HelloWeb do\n pipe_through :browser\n\n get \"/\", PageController, :home\n get \"/hello\", HelloController, :index\nend\n```\n\n### A new controller\n\nControllers are Elixir modules, and actions are Elixir functions defined in them. The purpose of actions is to gather the data and perform the tasks needed for rendering. Our route specifies that we need a `HelloWeb.HelloController` module with an `index/2` function.\n\nTo make the `index` action happen, let's create a new `lib/hello_web/controllers/hello_controller.ex` file, and make it look like the following:\n\n```elixir\ndefmodule HelloWeb.HelloController do\n use HelloWeb, :controller\n\n def index(conn, _params) do\n render(conn, :index)\n end\nend\n```\n\nWe'll save a discussion of `use HelloWeb, :controller` for the [Controllers guide](controllers.html). For now, let's focus on the `index` action.\n\nAll controller actions take two arguments. The first is `conn`, a struct which holds a ton of data about the request. The second is `params`, which are the request parameters. Here, we are not using `params`, and we avoid compiler warnings by prefixing it with `_`.\n\nThe core of this action is `render(conn, :index)`. It tells Phoenix to render the `index` template. The modules responsible for rendering are called views. By default, Phoenix views are named after the controller (`HelloController`) and format (`HTML` in this case), so Phoenix is expecting a `HelloWeb.HelloHTML` module to exist and define an `index/1` function.\n\n### A new view\n\nPhoenix views act as the presentation layer. For example, we expect the output of rendering `index` to be a complete HTML page. To make our lives easier, we often use templates for creating those HTML pages.\n\nLet's create a new view. Create `lib/hello_web/controllers/hello_html.ex` and make it look like this:\n\n```elixir\ndefmodule HelloWeb.HelloHTML do\n use HelloWeb, :html\nend\n```\n\nTo add templates to this view, we can define them as functions in the module or in separate files.\n\nLet's start by defining a function:\n\n```elixir\ndefmodule HelloWeb.HelloHTML do\n use HelloWeb, :html\n\n def index(assigns) do\n ~H\"\"\"\n Hello!\n \"\"\"\n end\nend\n```\n\nWe defined a function that receives `assigns` as arguments and used [the `~H` sigil](https://hexdocs.pm/phoenix_live_view/Phoenix.Component.html#sigil_H/2) to specify the content we want to render. Inside the `~H` sigil, we used a templating language called HEEx, which stands for \"HTML+EEx\". `EEx` is a library for embedding Elixir that ships as part of Elixir itself. \"HTML+EEx\" is a Phoenix extension of EEx that is HTML aware, with support for HTML validation, components, and automatic escaping of values. The latter protects you from security vulnerabilities like Cross-Site Scripting with no extra work on your part. We say that any function that receives `assigns` and returns templates to be a **function component**.\n\nA template file works in the same way. Let's give it a try by defining a template in its own file. First, delete our `def index(assigns)` function from above and replace it with an `embed_templates` declaration:\n\n```elixir\ndefmodule HelloWeb.HelloHTML do\n use HelloWeb, :html\n\n embed_templates \"hello_html/*\"\nend\n```\n\nHere we are saying we want to embed all `.heex` templates found in the sibling `hello_html` directory into our module as function components.\n\nNext, we need to add files to the `lib/hello_web/controllers/hello_html` directory. A template file has the following structure: `NAME.FORMAT.TEMPLATING_LANGUAGE`. In our case, let's create an `index.html.heex` file at `lib/hello_web/controllers/hello_html/index.html.heex`:\n\n```heex\n\n
Hello World, from Phoenix!
\n\n```\n\nPhoenix will see the template file and compile it into an `index(assigns)` function, similar as before. There is no runtime or performance difference between the two styles.\n\nAlso note the controller name (`HelloController`) and the view name (`HelloHTML`) and their respective files, `hello_controller.ex` and `hello_html.ex` all follow the same naming convention, and are named after each other. You could name the directory anything you want, as long as you update the `embed_templates` setting accordingly, but it's best to follow conventions.\n\n```console\nlib/hello_web\n├── controllers\n│ ├── hello_controller.ex\n│ ├── hello_html.ex\n│ ├── hello_html\n| ├── index.html.heex (NEW FILE!)\n```\n\nNow that we've got the route, controller, view, and template, we should be able to point our browser at [http://localhost:4000/hello](http://localhost:4000/hello) and see our greeting from Phoenix!\n\n\n \n \n \n\n\nIn case you stopped the server along the way, the task to restart it is `mix phx.server`. If you didn't stop it, everything should update on the fly: Phoenix has hot code reloading!\n\n## Layouts\n\nEven though our `index.html.heex` file consists of only a single `section` tag, the page we get is a full HTML document. Our index template is actually rendered into a separate layout: `lib/hello_web/components/layouts/root.html.heex`, which contains the basic HTML skeleton of the page. If you open this file, you'll see a line that looks like this at the bottom:\n\n```heex\n{@inner_content}\n```\n\nThis line injects our template into the layout before the HTML is sent off to the browser. The root layout, as the name implies, is a barebone layout with mostly the `` tag and a structure that is shared across **all of your pages**. Richer features, such as sidebar, menus, etc. are part of your application layout, which we will explore in a couple sections below.\n\n## From endpoint to views\n\nHaving built our first page, we're beginning to understand how the request life-cycle is put together. Now let's take a more holistic look at it.\n\nAll HTTP requests start in our application endpoint. You can find it as a module named `HelloWeb.Endpoint` in `lib/hello_web/endpoint.ex`. Once you open up the endpoint file, you will see that, similar to the router, the endpoint has many calls to `plug`. `Plug` is a library and a specification for stitching web applications together. It is an essential part of how Phoenix handles requests and we will discuss it in detail in the [Plug guide](plug.html) coming next.\n\nFor now, it suffices to say that each plug defines a slice of request processing. In the endpoint you will find a skeleton roughly like this:\n\n```elixir\ndefmodule HelloWeb.Endpoint do\n use Phoenix.Endpoint, otp_app: :hello\n\n plug Plug.Static, ...\n plug Plug.RequestId\n plug Plug.Telemetry, ...\n plug Plug.Parsers, ...\n plug Plug.MethodOverride\n plug Plug.Head\n plug Plug.Session, ...\n plug HelloWeb.Router\nend\n```\n\nEach of these plugs have a specific responsibility that we will learn later. The last plug is precisely the `HelloWeb.Router` module. This allows the endpoint to delegate all further request processing to the router. As we now know, its main responsibility is to map verb/path pairs to controllers. The controller then tells a view to render a template.\n\nAt this moment, you may be thinking this can be a lot of steps to simply render a page. However, as our application grows in complexity, we will see that each layer serves a distinct purpose:\n\n * endpoint (`Phoenix.Endpoint`) - the endpoint contains the common and initial path that all requests go through. If you want something to happen on all requests, it goes in the endpoint.\n\n * router (`Phoenix.Router`) - the router is responsible for dispatching verb/path pairs to controllers. The router also allows us to scope functionality. For example, some pages in your application may require user authentication, others may not.\n\n * controller (`Phoenix.Controller`) - the job of the controller is to retrieve request information, talk to your business domain, and prepare data for the presentation layer.\n\n * view - the view handles the structured data from the controller and converts it to a presentation to be shown to users. Views are often named after the content format they are rendering.\n\nLet's do a quick recap on how the last three components work together by adding another page. This time, we will use some additional features, such as layout components and content interpolation.\n\n## Another new page\n\nLet's add just a little complexity to our application. We're going to add a new page that will recognize a piece of the URL, label it as a \"messenger\" and pass it through the controller into the template so our messenger can say hello.\n\nAs we did last time, the first thing we'll do is create a new route.\n\n### Another new route\n\nFor this exercise, we're going to reuse `HelloController` created at the [previous step](request_lifecycle.html#a-new-controller) and add a new `show` action. We'll add a line just below our last route, like this:\n\n```elixir\nscope \"/\", HelloWeb do\n pipe_through :browser\n\n get \"/\", PageController, :home\n get \"/hello\", HelloController, :index\n get \"/hello/:messenger\", HelloController, :show\nend\n```\n\nNotice that we use the `:messenger` syntax in the path. Phoenix will take whatever value that appears in that position in the URL and convert it into a parameter. For example, if we point the browser at: `http://localhost:4000/hello/Frank`, the value of `\"messenger\"` will be `\"Frank\"`.\n\n### Another new action\n\nRequests to our new route will be handled by the `HelloWeb.HelloController` `show` action. We already have the controller at `lib/hello_web/controllers/hello_controller.ex`, so all we need to do is edit that controller and add a `show` action to it. This time, we'll need to extract the messenger from the parameters so that we can pass it (the messenger) to the template. To do that, we add this show function to the controller:\n\n```elixir\ndef show(conn, %{\"messenger\" => messenger}) do\n render(conn, :show, messenger: messenger)\nend\n```\n\nWithin the body of the `show` action, we also pass a third argument to the render function, a key-value pair where `:messenger` is the key, and the `messenger` variable is passed as the value.\n\nIf the body of the action needs access to the full map of parameters bound to the `params` variable, in addition to the bound messenger variable, we could define `show/2` like this:\n\n```elixir\ndef show(conn, %{\"messenger\" => messenger} = params) do\n ...\nend\n```\n\nIt's good to remember that the keys of the `params` map will always be strings, and that the equals sign does not represent assignment, but is instead a [pattern match](https://hexdocs.pm/elixir/pattern-matching.html) assertion.\n\n### Another new template\n\nFor the last piece of this puzzle, we'll need a new template. Since it is for the `show` action of `HelloController`, it will go into the `lib/hello_web/controllers/hello_html` directory and be called `show.html.heex`. It will look surprisingly like our `index.html.heex` template, except that we will need to display the name of our messenger. Let's write the new template down and then explain what it does:\n\n```heex\n\n \n
Hello World, from {@messenger}!
\n \n\n```\n\nIf you point your browser to [http://localhost:4000/hello/Frank](http://localhost:4000/hello/Frank), you should see a page that looks like this:\n\n\n \n \n \n\n\nLet's break what the template does into parts. This template has the `.heex` extension which stands for HTML + Embedded Elixir. There are three features from HEEx we are using in the template above:\n\n * Assigns, such as `@messenger` and `@flash` - values we pass to the view from the controller are collectively called our \"assigns\". We could access our messenger value via `assigns.messenger` and `assigns.flash`, but Phoenix gives us the much cleaner `@` syntax for use in templates.\n\n * Content interpolation, such as `{@messenger}` - any Elixir code that goes between `{...}` will be executed, and the resulting value will replace the tag in the HTML output\n\n * Function component tags, as in `` - the reason templates are called function components is because we can compose them! In this case, there is an `HelloWeb.Layouts.app` function, that defines our application layout, which we invoke with our custom content\n\nAlso note how these three features compose: we are passing the `@flash` assign as an Elixir value to the `` component. As we will learn later, flash messages are used to display temporary messages to the user, such as success or error messages. We will learn more about them in the [Components and HEEx templates](components.html) guide.\n\nWe are done! Feel free to play around a bit. Whatever you put after `/hello/` will appear on the page as your messenger.\n"
},
{
"path": "guides/routing.md",
"content": "# Routing\n\n> **Requirement**: This guide expects that you have gone through the [introductory guides](installation.html) and got a Phoenix application [up and running](up_and_running.html).\n\n> **Requirement**: This guide expects that you have gone through the [Request life-cycle guide](request_lifecycle.html).\n\nRouters are the main hubs of Phoenix applications. They match HTTP requests to controller actions, wire up real-time channel handlers, and define a series of pipeline transformations scoped to a set of routes.\n\nThe router file that Phoenix generates, `lib/hello_web/router.ex`, will look something like this one:\n\n```elixir\ndefmodule HelloWeb.Router do\n use HelloWeb, :router\n\n pipeline :browser do\n plug :accepts, [\"html\"]\n plug :fetch_session\n plug :fetch_live_flash\n plug :put_root_layout, html: {HelloWeb.Layouts, :root}\n plug :protect_from_forgery\n plug :put_secure_browser_headers\n end\n\n pipeline :api do\n plug :accepts, [\"json\"]\n end\n\n scope \"/\", HelloWeb do\n pipe_through :browser\n\n get \"/\", PageController, :home\n end\n\n # Other scopes may use custom stacks.\n # scope \"/api\", HelloWeb do\n # pipe_through :api\n # end\n\n # ...\nend\n```\n\nBoth the router and controller module names will be prefixed with the name you gave your application suffixed with `Web`.\n\nThe first line of this module, `use HelloWeb, :router`, simply makes Phoenix router functions available in our particular router.\n\nScopes have their own section in this guide, so we won't spend time on the `scope \"/\", HelloWeb do` block here. The `pipe_through :browser` line will get a full treatment in the \"Pipelines\" section of this guide. For now, you only need to know that pipelines allow a set of plugs to be applied to different sets of routes.\n\nInside the scope block, however, we have our first actual route:\n\n```elixir\nget \"/\", PageController, :home\n```\n\n`get` is a Phoenix macro that corresponds to the HTTP verb GET. Similar macros exist for other HTTP verbs, including POST, PUT, PATCH, DELETE, OPTIONS, CONNECT, TRACE, and HEAD.\n\n> #### Why the macros? {: .info}\n>\n> Phoenix does its best to keep the usage of macros low. You may have noticed, however, that the `Phoenix.Router` relies heavily on macros. Why is that?\n>\n> We use `get`, `post`, `put`, and `delete` to define your routes. We use macros for two purposes:\n>\n> * They define the routing engine, used on every request, to choose which controller to dispatch the request to. Thanks to macros, Phoenix compiles all of your routes to a huge case-statement with pattern matching rules, which is heavily optimized by the Erlang VM\n>\n> * For each route you define, we also define metadata to implement `Phoenix.VerifiedRoutes`. As we will soon learn, verified routes allow us to reference any route as if it were a plain looking string, except that it is verified by the compiler to be valid (making it much harder to ship broken links, forms, mails, etc to production)\n>\n> In other words, the router relies on macros to build applications that are faster and safer. Also remember that macros in Elixir are compile-time only, which gives plenty of stability after the code is compiled. As we will learn next, Phoenix also provides introspection for all defined routes via `mix phx.routes`.\n\n## Examining routes\n\nPhoenix provides an excellent tool for investigating routes in an application: `mix phx.routes`.\n\nLet's see how this works. Go to the root of a newly-generated Phoenix application and run `mix phx.routes`. You should see something like the following, generated with all routes you currently have:\n\n```console\n$ mix phx.routes\nGET / HelloWeb.PageController :home\n...\n```\n\nThe route above tells us that any HTTP GET request for the root of the application will be handled by the `home` action of the `HelloWeb.PageController`.\n\n## Resources\n\nThe router supports other macros besides those for HTTP verbs like [`get`](`Phoenix.Router.get/3`), [`post`](`Phoenix.Router.post/3`), and [`put`](`Phoenix.Router.put/3`). The most important among them is [`resources`](`Phoenix.Router.resources/4`). Let's add a resource to our `lib/hello_web/router.ex` file like this:\n\n```elixir\nscope \"/\", HelloWeb do\n pipe_through :browser\n\n get \"/\", PageController, :home\n resources \"/users\", UserController\n ...\nend\n```\n\nFor now it doesn't matter that we don't actually have a `HelloWeb.UserController`.\n\nRun `mix phx.routes` once again at the root of your project. You should see something like the following:\n\n```console\n...\nGET /users HelloWeb.UserController :index\nGET /users/:id/edit HelloWeb.UserController :edit\nGET /users/new HelloWeb.UserController :new\nGET /users/:id HelloWeb.UserController :show\nPOST /users HelloWeb.UserController :create\nPATCH /users/:id HelloWeb.UserController :update\nPUT /users/:id HelloWeb.UserController :update\nDELETE /users/:id HelloWeb.UserController :delete\n...\n```\n\nThis is the standard matrix of HTTP verbs, paths, and controller actions. For a while, this was known as RESTful routes, but most consider this a misnomer nowadays. Let's look at them individually.\n\n- A GET request to `/users` will invoke the `index` action to show all the users.\n- A GET request to `/users/:id/edit` will invoke the `edit` action with an ID to retrieve an individual user from the data store and present the information in a form for editing.\n- A GET request to `/users/new` will invoke the `new` action to present a form for creating a new user.\n- A GET request to `/users/:id` will invoke the `show` action with an id to show an individual user identified by that ID.\n- A POST request to `/users` will invoke the `create` action to save a new user to the data store.\n- A PATCH request to `/users/:id` will invoke the `update` action with an ID to save the updated user to the data store.\n- A PUT request to `/users/:id` will also invoke the `update` action with an ID to save the updated user to the data store.\n- A DELETE request to `/users/:id` will invoke the `delete` action with an ID to remove the individual user from the data store.\n\nIf we don't need all these routes, we can be selective using the `:only` and `:except` options to filter specific actions.\n\nLet's say we have a read-only posts resource. We could define it like this:\n\n```elixir\nresources \"/posts\", PostController, only: [:index, :show]\n```\n\nRunning `mix phx.routes` shows that we now only have the routes to the index and show actions defined.\n\n```console\nGET /posts HelloWeb.PostController :index\nGET /posts/:id HelloWeb.PostController :show\n```\n\nSimilarly, if we have a comments resource, and we don't want to provide a route to delete one, we could define a route like this.\n\n```elixir\nresources \"/comments\", CommentController, except: [:delete]\n```\n\nRunning `mix phx.routes` now shows that we have all the routes except the DELETE request to the delete action.\n\n```console\nGET /comments HelloWeb.CommentController :index\nGET /comments/:id/edit HelloWeb.CommentController :edit\nGET /comments/new HelloWeb.CommentController :new\nGET /comments/:id HelloWeb.CommentController :show\nPOST /comments HelloWeb.CommentController :create\nPATCH /comments/:id HelloWeb.CommentController :update\nPUT /comments/:id HelloWeb.CommentController :update\n```\n\nThe `Phoenix.Router.resources/4` macro describes additional options for customizing resource routes.\n\n## Verified Routes\n\nPhoenix includes `Phoenix.VerifiedRoutes` module which provides compile-time checks of router paths against your router by using the `~p` sigil. For example, you can write paths in controllers, tests, and templates and the compiler will make sure those actually match routes defined in your router.\n\nLet's see it in action. Run `iex -S mix` at the root of the project. We'll define a throwaway example module that builds a couple `~p` route paths.\n\n```elixir\niex> defmodule RouteExample do\n...> use HelloWeb, :verified_routes\n...>\n...> def example do\n...> ~p\"/comments\"\n...> ~p\"/unknown/123\"\n...> end\n...> end\nwarning: no route path for HelloWeb.Router matches \"/unknown/123\"\n iex:5: RouteExample.example/0\n\n{:module, RouteExample, ...}\niex>\n```\n\nNotice how the first call to an existing route, `~p\"/comments\"` gave no warning, but a bad route path `~p\"/unknown/123\"` produced a compiler warning, just as it should. This is significant because it allows us to write otherwise hard-coded paths in our application and the compiler will let us know whenever we write a bad route or change our routing structure.\n\nPhoenix projects are set up out of the box to allow use of verified routes throughout your web layer, including tests. For example in your templates you can render `~p` links:\n\n```heex\nWelcome Page!\nView Comments\n```\n\nOr in a controller, issue a redirect:\n\n```elixir\nredirect(conn, to: ~p\"/comments/#{comment}\")\n```\n\nUsing `~p` for route paths ensures our application paths and URLs stay up to date with the router definitions. The compiler will catch bugs for us, and let us know when we change routes that are referenced elsewhere in our application.\n\n### More on verified routes\n\nWhat about paths with query strings? You can add query string key values directly, as a keyword list or map of values, for example:\n\n```elixir\n~p\"/users/17?admin=true&active=false\"\n\"/users/17?admin=true&active=false\"\n\n~p\"/users/17?#{[admin: true]}\"\n\"/users/17?admin=true\"\n\n~p\"/users/17?#{%{admin: true}}\"\n\"/users/17?admin=true\"\n```\n\nWhat if we need a full URL instead of a path? Just wrap your path with a call to `Phoenix.VerifiedRoutes.url/1`, which is imported everywhere that `~p` is available:\n\n```elixir\nurl(~p\"/users\")\n\"http://localhost:4000/users\"\n```\n\nThe `url` calls will get the host, port, proxy port, and SSL information needed to construct the full URL from the configuration parameters set for each environment. We'll talk about configuration in more detail in its own guide. For now, you can take a look at `config/dev.exs` file in your own project to see those values.\n\n## Nested resources\n\nIt is also possible to nest resources in a Phoenix router. Let's say we also have a `posts` resource that has a many-to-one relationship with `users`. That is to say, a user can create many posts, and an individual post belongs to only one user. We can represent that by adding a nested route in `lib/hello_web/router.ex` like this:\n\n```elixir\nresources \"/users\", UserController do\n resources \"/posts\", PostController\nend\n```\n\nWhen we run `mix phx.routes` now, in addition to the routes we saw for `users` above, we get the following set of routes:\n\n```console\n...\nGET /users/:user_id/posts HelloWeb.PostController :index\nGET /users/:user_id/posts/:id/edit HelloWeb.PostController :edit\nGET /users/:user_id/posts/new HelloWeb.PostController :new\nGET /users/:user_id/posts/:id HelloWeb.PostController :show\nPOST /users/:user_id/posts HelloWeb.PostController :create\nPATCH /users/:user_id/posts/:id HelloWeb.PostController :update\nPUT /users/:user_id/posts/:id HelloWeb.PostController :update\nDELETE /users/:user_id/posts/:id HelloWeb.PostController :delete\n...\n```\n\nWe see that each of these routes scopes the posts to a user ID. For the first one, we will invoke `PostController`'s `index` action, but we will pass in a `user_id`. This implies that we would display all the posts for that individual user only. The same scoping applies for all these routes.\n\nWhen building paths for nested routes, we will need to interpolate the IDs where they belong in route definition. For the following `show` route, `42` is the `user_id`, and `17` is the `post_id`.\n\n```elixir\nuser_id = 42\npost_id = 17\n~p\"/users/#{user_id}/posts/#{post_id}\"\n\"/users/42/posts/17\"\n```\n\nVerified routes also support the `Phoenix.Param` protocol, but we don't need to concern ourselves with Elixir protocols just yet. Just know that once we start building our application with structs like `%User{}` and `%Post{}`, we'll be able to interpolate those data structures directly into our `~p` paths and Phoenix will pluck out the correct fields to use in the route.\n\n```elixir\n~p\"/users/#{user}/posts/#{post}\"\n\"/users/42/posts/17\"\n```\n\nNotice how we didn't need to interpolate `user.id` or `post.id`? This is particularly nice if we decide later we want to make our URLs a little nicer and start using slugs instead. We don't need to change any of our `~p`'s!\n\n## Scoped routes\n\nScopes are a way to group routes under a common path prefix and scoped set of plugs. We might want to do this for admin functionality, APIs, and especially for versioned APIs. Let's say we have user-generated reviews on a site, and that those reviews first need to be approved by an administrator. The semantics of these resources are quite different, and they might not share the same controller. Scopes enable us to segregate these routes.\n\nThe paths to the user-facing reviews would look like a standard resource.\n\n```console\n/reviews\n/reviews/1234\n/reviews/1234/edit\n...\n```\n\nThe administration review paths can be prefixed with `/admin`.\n\n```console\n/admin/reviews\n/admin/reviews/1234\n/admin/reviews/1234/edit\n...\n```\n\nWe accomplish this with a scoped route that sets a path option to `/admin` like this one. We can nest this scope inside another scope, but instead, let's set it by itself at the root, by adding to `lib/hello_web/router.ex` the following:\n\n```elixir\nscope \"/admin\", HelloWeb.Admin do\n pipe_through :browser\n\n resources \"/reviews\", ReviewController\nend\n```\n\nWe define a new scope where all routes are prefixed with `/admin` and all controllers are under the `HelloWeb.Admin` namespace.\n\nRunning `mix phx.routes` again, in addition to the previous set of routes we get the following:\n\n```console\n...\nGET /admin/reviews HelloWeb.Admin.ReviewController :index\nGET /admin/reviews/:id/edit HelloWeb.Admin.ReviewController :edit\nGET /admin/reviews/new HelloWeb.Admin.ReviewController :new\nGET /admin/reviews/:id HelloWeb.Admin.ReviewController :show\nPOST /admin/reviews HelloWeb.Admin.ReviewController :create\nPATCH /admin/reviews/:id HelloWeb.Admin.ReviewController :update\nPUT /admin/reviews/:id HelloWeb.Admin.ReviewController :update\nDELETE /admin/reviews/:id HelloWeb.Admin.ReviewController :delete\n...\n```\n\nThis looks good, but there is a problem here. Remember that we wanted both user-facing review routes `/reviews` and the admin ones `/admin/reviews`. If we now include the user-facing reviews in our router under the root scope like this:\n\n```elixir\nscope \"/\", HelloWeb do\n pipe_through :browser\n\n ...\n resources \"/reviews\", ReviewController\nend\n\nscope \"/admin\", HelloWeb.Admin do\n pipe_through :browser\n\n resources \"/reviews\", ReviewController\nend\n```\n\nand we run `mix phx.routes`, we get output for each scoped route:\n\n```console\n...\nGET /reviews HelloWeb.ReviewController :index\nGET /reviews/:id/edit HelloWeb.ReviewController :edit\nGET /reviews/new HelloWeb.ReviewController :new\nGET /reviews/:id HelloWeb.ReviewController :show\nPOST /reviews HelloWeb.ReviewController :create\nPATCH /reviews/:id HelloWeb.ReviewController :update\nPUT /reviews/:id HelloWeb.ReviewController :update\nDELETE /reviews/:id HelloWeb.ReviewController :delete\n...\nGET /admin/reviews HelloWeb.Admin.ReviewController :index\nGET /admin/reviews/:id/edit HelloWeb.Admin.ReviewController :edit\nGET /admin/reviews/new HelloWeb.Admin.ReviewController :new\nGET /admin/reviews/:id HelloWeb.Admin.ReviewController :show\nPOST /admin/reviews HelloWeb.Admin.ReviewController :create\nPATCH /admin/reviews/:id HelloWeb.Admin.ReviewController :update\nPUT /admin/reviews/:id HelloWeb.Admin.ReviewController :update\nDELETE /admin/reviews/:id HelloWeb.Admin.ReviewController :delete\n```\n\nWhat if we had a number of resources that were all handled by admins? We could put all of them inside the same scope like this:\n\n```elixir\nscope \"/admin\", HelloWeb.Admin do\n pipe_through :browser\n\n resources \"/images\", ImageController\n resources \"/reviews\", ReviewController\n resources \"/users\", UserController\nend\n```\n\nHere's what `mix phx.routes` tells us:\n\n```console\n...\nGET /admin/images HelloWeb.Admin.ImageController :index\nGET /admin/images/:id/edit HelloWeb.Admin.ImageController :edit\nGET /admin/images/new HelloWeb.Admin.ImageController :new\nGET /admin/images/:id HelloWeb.Admin.ImageController :show\nPOST /admin/images HelloWeb.Admin.ImageController :create\nPATCH /admin/images/:id HelloWeb.Admin.ImageController :update\nPUT /admin/images/:id HelloWeb.Admin.ImageController :update\nDELETE /admin/images/:id HelloWeb.Admin.ImageController :delete\nGET /admin/reviews HelloWeb.Admin.ReviewController :index\nGET /admin/reviews/:id/edit HelloWeb.Admin.ReviewController :edit\nGET /admin/reviews/new HelloWeb.Admin.ReviewController :new\nGET /admin/reviews/:id HelloWeb.Admin.ReviewController :show\nPOST /admin/reviews HelloWeb.Admin.ReviewController :create\nPATCH /admin/reviews/:id HelloWeb.Admin.ReviewController :update\nPUT /admin/reviews/:id HelloWeb.Admin.ReviewController :update\nDELETE /admin/reviews/:id HelloWeb.Admin.ReviewController :delete\nGET /admin/users HelloWeb.Admin.UserController :index\nGET /admin/users/:id/edit HelloWeb.Admin.UserController :edit\nGET /admin/users/new HelloWeb.Admin.UserController :new\nGET /admin/users/:id HelloWeb.Admin.UserController :show\nPOST /admin/users HelloWeb.Admin.UserController :create\nPATCH /admin/users/:id HelloWeb.Admin.UserController :update\nPUT /admin/users/:id HelloWeb.Admin.UserController :update\nDELETE /admin/users/:id HelloWeb.Admin.UserController :delete\n```\n\nThis is great, exactly what we want. Note how every route and controller is properly namespaced.\n\nScopes can also be arbitrarily nested, but you should do it carefully as nesting can sometimes make our code confusing and less clear. With that said, suppose that we had a versioned API with resources defined for images, reviews, and users. Then technically, we could set up routes for the versioned API like this:\n\n```elixir\nscope \"/api\", HelloWeb.Api do\n pipe_through :api\n\n scope \"/v1\", V1 do\n resources \"/images\", ImageController\n resources \"/reviews\", ReviewController\n resources \"/users\", UserController\n end\nend\n```\n\nYou can run `mix phx.routes` to see how these definitions will look like.\n\nInterestingly, we can use multiple scopes with the same path as long as we are careful not to duplicate routes. The following router is perfectly fine with two scopes defined for the same path:\n\n```elixir\ndefmodule HelloWeb.Router do\n use Phoenix.Router\n ...\n scope \"/\", HelloWeb do\n pipe_through :browser\n\n resources \"/users\", UserController\n end\n\n scope \"/\", AnotherAppWeb do\n pipe_through :browser\n\n resources \"/posts\", PostController\n end\n ...\nend\n```\n\nIf we do duplicate a route — which means two routes having the same path — we'll get this familiar warning:\n\n```console\nwarning: this clause cannot match because a previous clause at line 16 always matches\n```\n\n## Pipelines\n\nWe have come quite a long way in this guide without talking about one of the first lines we saw in the router: `pipe_through :browser`. It's time to fix that.\n\nPipelines are a series of plugs that can be attached to specific scopes. If you are not familiar with plugs, we have an [in-depth guide about them](plug.html).\n\nRoutes are defined inside scopes and scopes may pipe through multiple pipelines. Once a route matches, Phoenix invokes all plugs defined in all pipelines associated to that route. For example, accessing `/` will pipe through the `:browser` pipeline, consequently invoking all of its plugs.\n\nPhoenix defines two pipelines by default, `:browser` and `:api`, which can be used for a number of common tasks. In turn we can customize them as well as create new pipelines to meet our needs.\n\n### The `:browser` and `:api` pipelines\n\nAs their names suggest, the `:browser` pipeline prepares for routes which render requests for a browser, and the `:api` pipeline prepares for routes which produce data for an API.\n\nThe `:browser` pipeline has six plugs: The `plug :accepts, [\"html\"]` defines the accepted request format or formats. `:fetch_session`, which, naturally, fetches the session data and makes it available in the connection. `:fetch_live_flash`, which fetches any flash messages from LiveView and merges them with the controller flash messages. Then, the plug `:put_root_layout` will store the root layout for rendering purposes. Later `:protect_from_forgery` and `:put_secure_browser_headers`, protects form posts from cross-site forgery.\n\nCurrently, the `:api` pipeline only defines `plug :accepts, [\"json\"]`.\n\nThe router invokes a pipeline on a route defined within a scope. Routes outside of a scope have no pipelines. Although the use of nested scopes is discouraged (see above the versioned API example), if we call `pipe_through` within a nested scope, the router will invoke all `pipe_through`'s from parent scopes, followed by the nested one.\n\nThose are a lot of words bunched up together. Let's take a look at some examples to untangle their meaning.\n\nHere's another look at the router from a newly generated Phoenix application, this time with the `/api` scope uncommented back in and a route added.\n\n```elixir\ndefmodule HelloWeb.Router do\n use HelloWeb, :router\n\n pipeline :browser do\n plug :accepts, [\"html\"]\n plug :fetch_session\n plug :fetch_live_flash\n plug :put_root_layout, html: {HelloWeb.Layouts, :root}\n plug :protect_from_forgery\n plug :put_secure_browser_headers\n end\n\n pipeline :api do\n plug :accepts, [\"json\"]\n end\n\n scope \"/\", HelloWeb do\n pipe_through :browser\n\n get \"/\", PageController, :home\n end\n\n # Other scopes may use custom stacks.\n scope \"/api\", HelloWeb do\n pipe_through :api\n\n resources \"/reviews\", ReviewController\n end\n # ...\nend\n```\n\nWhen the server accepts a request, the request will always first pass through the plugs in our endpoint, after which it will attempt to match on the path and HTTP verb.\n\nLet's say that the request matches our first route: a GET to `/`. The router will first pipe that request through the `:browser` pipeline - which will fetch the session data, fetch the flash, and execute forgery protection - before it dispatches the request to `PageController`'s `home` action.\n\nConversely, suppose the request matches any of the routes defined by the [`resources/2`](`Phoenix.Router.resources/2`) macro. In that case, the router will pipe it through the `:api` pipeline — which currently only performs content negotiation — before it dispatches further to the correct action of the `HelloWeb.ReviewController`.\n\nIf no route matches, no pipeline is invoked and a 404 error is raised.\n\n### Creating new pipelines\n\nPhoenix allows us to create our own custom pipelines anywhere in the router. To do so, we call the [`pipeline/2`](`Phoenix.Router.pipeline/2`) macro with these arguments: an atom for the name of our new pipeline and a block with all the plugs we want in it.\n\n```elixir\ndefmodule HelloWeb.Router do\n use HelloWeb, :router\n\n pipeline :browser do\n plug :accepts, [\"html\"]\n plug :fetch_session\n plug :fetch_live_flash\n plug :put_root_layout, html: {HelloWeb.Layouts, :root}\n plug :protect_from_forgery\n plug :put_secure_browser_headers\n end\n\n pipeline :auth do\n plug HelloWeb.Authentication\n end\n\n scope \"/reviews\", HelloWeb do\n pipe_through [:browser, :auth]\n\n resources \"/\", ReviewController\n end\nend\n```\n\nThe above assumes there is a plug called `HelloWeb.Authentication` that performs authentication and is now part of the `:auth` pipeline.\n\nNote that pipelines themselves are plugs, so we can plug a pipeline inside another pipeline. For example, we could rewrite the `auth` pipeline above to automatically invoke `browser`, simplifying the downstream pipeline call:\n\n```elixir\n pipeline :auth do\n plug :browser\n plug :ensure_authenticated_user\n plug :ensure_user_owns_review\n end\n\n scope \"/reviews\", HelloWeb do\n pipe_through :auth\n\n resources \"/\", ReviewController\n end\n```\n\n## How to organize my routes?\n\nIn Phoenix, we tend to define several pipelines, that provide specific functionality. For example, the `:browser` and `:api` pipelines are meant to be accessed by specific clients, browsers and http clients respectively.\n\nPerhaps more importantly, it is also very common to define pipelines specific to authentication and authorization. For example, you might have a pipeline that requires all users are authenticated. Another pipeline may enforce only admin users can access certain routes.\n\nOnce your pipelines are defined, you reuse the pipelines in the desired scopes, grouping your routes around their pipelines. For example, going back to our reviews example. Let's say anyone can read a review, but only authenticated users can create them. Your routes could look like this:\n\n```elixir\npipeline :browser do\n ...\nend\n\npipeline :auth do\n plug HelloWeb.Authentication\nend\n\nscope \"/\" do\n pipe_through [:browser]\n\n get \"/reviews\", PostController, :index\n get \"/reviews/:id\", PostController, :show\nend\n\nscope \"/\" do\n pipe_through [:browser, :auth]\n\n get \"/reviews/new\", PostController, :new\n post \"/reviews\", PostController, :create\nend\n```\n\nNote in the above how the routes are split across different scopes. While the separation can be confusing at first, it has one big upside: it is very easy to inspect your routes and see all routes that, for example, require authentication and which ones do not. This helps with auditing and making sure your routes have the proper scope.\n\nYou can create as few or as many scopes as you want. Because pipelines are reusable across scopes, they help encapsulate common functionality and you can compose them as necessary on each scope you define.\n\n## Forward\n\nThe `Phoenix.Router.forward/4` macro can be used to send all requests that start with a particular path to a particular plug. Let's say we have a part of our system that is responsible (it could even be a separate application or library) for running jobs in the background, it could have its own web interface for checking the status of the jobs. We can forward to this admin interface using:\n\n```elixir\ndefmodule HelloWeb.Router do\n use HelloWeb, :router\n\n ...\n\n scope \"/\", HelloWeb do\n ...\n end\n\n forward \"/jobs\", BackgroundJob.Plug\nend\n```\n\nThis means that all routes starting with `/jobs` will be sent to the `BackgroundJob.Plug` module. Inside the plug, you can match on subroutes, such as `/pending` and `/active` that shows the status of certain jobs.\n\nWe can even mix the [`forward/4`](`Phoenix.Router.forward/4`) macro with pipelines. If we wanted to ensure that the user was authenticated and was an administrator in order to see the jobs page, we could use the following in our router.\n\n```elixir\ndefmodule HelloWeb.Router do\n use HelloWeb, :router\n\n ...\n\n scope \"/\" do\n pipe_through [:authenticate_user, :ensure_admin]\n forward \"/jobs\", BackgroundJob.Plug\n end\nend\n```\n\nThis means the plugs in the `authenticate_user` and `ensure_admin` pipelines will be called before the `BackgroundJob.Plug` allowing them to send an appropriate response and halt the request accordingly.\n\n`BackgroundJob.Plug` can be implemented as any \"Module Plug\" discussed in the [Plug guide](plug.html). Note though it is not advised to forward to another Phoenix endpoint. This is because plugs defined by your app and the forwarded endpoint would be invoked twice, which may lead to errors.\n\n## Summary\n\nRouting is a big topic, and we have covered a lot of ground here. The important points to take away from this guide are:\n\n- Routes which begin with an HTTP verb name expand to a single clause of the match function.\n- Routes declared with `resources` expand to 8 clauses of the match function.\n- Resources may restrict the number of match function clauses by using the `only:` or `except:` options.\n- Any of these routes may be nested.\n- Any of these routes may be scoped to a given path.\n- Using verified routes with `~p` for compile-time route checks\n"
},
{
"path": "guides/security.md",
"content": "# Security \n\nAll software exposed to the public internet will be attacked. Most Phoenix applications fall into this category, so it is useful to understand common types of web application security vulnerabilities, the impact of each, and how to avoid them. Consider the following scenario:\n\nYou are responsible for a banking application which handles transactions via a Phoenix backend. A new code change introduces a remote code execution (RCE) vulnerability, granting an attacker production SSH access to the server. This results in the database being exfiltrated, user accounts being compromised, and customer funds being stolen. \n\nWith the rise of generative AI coding tools, proper judgement on the security of code has become more important than ever. This document will detail how severe vulnerabilities can occur in a Phoenix project and secure coding best practices to help avoid an incident. \n\n## Remote Code Execution (RCE)\n\nA remote code execution (RCE) vulnerability grants an attacker the equivalent of production SSH access to your web server. This type of vulnerability is often considered the worst possible case, because it does not require user interaction and allows an attacker to bypass all security controls in your application.\n\nYou should never pass untrusted user input to the following functions:\n\n```\n# Code functions\nCode.eval_string/3\nCode.eval_file/2\nCode.eval_quoted/3\n\n# EEX functions\neval_string/3\neval_file/3\n\n# Command injection functions\n:os.cmd/2\nSystem.cmd/3\nSystem.shell/2\n```\n\nAll of these functions execute arbitrary code on your server if passed external input. The risk here is obvious to most programmers, so it is rare to find a Phoenix application vulnerable in this way. \n\nThe more common and often unexpected way a Phoenix application is vulnerable to RCE is via the Erlang function `binary_to_term`. From [the Erlang docs:](https://www.erlang.org/doc/apps/erts/erlang.html#binary_to_term/2)\n\n> When decoding binaries from untrusted sources, the untrusted source may submit data in a way to create resources, such as atoms and remote references, that cannot be garbage collected and lead to a Denial of Service (DoS) attack. In such cases, use `binary_to_term/2` with the `safe` option.\n\nThis warning is confusing, because the `safe` option mentioned above only prevents the creation of new atoms at runtime. It does not prevent the creation of executable terms via malicious user input, which is a much greater risk. \n\n```\n# Not safe\n:erlang.binary_to_term(user_input, [:safe])\n\n# Safe\nPlug.Crypto.non_executable_binary_to_term(user_input, [:safe])\n```\n\nThe function `Plug.Crypto.non_executable_binary_to_term` prevents the creation of executable terms at runtime. If you are curious how this vulnerability can occur in the real world, see the writeup on [CVE-2020-15150 in the library Paginator.](https://www.alphabot.com/security/blog/2020/elixir/Remote-code-execution-vulnerability-in-Elixir-based-Paginator-project.html)\n\n\n## SQL Injection \n\nSQL injection is on par with RCE as a highly severe vulnerability that leads to your entire database being leaked, and can even be leveraged to achieve code execution in some contexts. The good news for Phoenix developers is the majority of applications use Ecto, which is the interface to a dedicated database, typically PostgreSQL or MySQL. The Ecto query syntax protects against SQL injection by default:\n\n```\n# Safe, using query syntax \ndef a_get_fruit(min_q) do\n from(\n f in Fruit,\n where:\n f.quantity >= ^min_q and\n f.secret == false\n )\n |> Repo.all()\nend\n```\n\nThe `fragment` function seems to be a vector for SQL injection:\n\n```\n# Fails to compile \ndef b_get_fruit(min_q) do\n from(\n f in Fruit,\n where: fragment(\"f0.quantity >= #{min_q} AND f0.secret = FALSE\")\n )\n |> Repo.all()\nend\n```\n\nYet if you try to compile the above code it fails:\n\n```text\nCompiling 1 file (.ex)\n\n== Compilation error in file lib/basket/goods.ex ==\n** (Ecto.Query.CompileError) to prevent SQL injection attacks, fragment(...) \ndoes not allow strings to be interpolated as the first argument via the `^` \noperator, got: `\"f0.quantity >= #{min_q} AND f0.secret = FALSE\"`\n```\n\nWhat about passing arguments via fragment?\n\n```\n# Safe\ndef c_get_fruit(min_q) do\n min_q = String.to_integer(min_q)\n from(\n f in Fruit,\n where: fragment(\"f0.quantity >= ? AND f0.secret = FALSE\", ^min_q)\n )\n |> Repo.all()\nend\n```\n\nThe above code is safe because the external user input is safely parameterized into the query. What if you decide to pass arguments directly into raw SQL?\n\n```\n# Safe\ndef d_get_fruit(min_q) do\n q = \"\"\"\n SELECT f.id, f.name, f.quantity, f.secret\n FROM fruits AS f\n WHERE f.quantity > $1 AND f.secret = FALSE\n \"\"\"\n {:ok, %{rows: rows}} =\n Ecto.Adapters.SQL.query(Repo, q, [String.to_integer(min_q)])\nend\n```\n\nThe above code is safe, similar to the fragment example, because the user input is being safely parameterized. \n\nConstructing a SQL query string via user input, then passing it directly to the query function does lead to SQL injection: \n\n```\n# Vulnerable to SQL injection\ndef e_get_fruit(min_q) do\n q = \"\"\"\n SELECT f.id, f.name, f.quantity, f.secret\n FROM fruits AS f\n WHERE f.quantity > #{min_q} AND f.secret = FALSE\n \"\"\"\n {:ok, %{rows: rows}} =\n Ecto.Adapters.SQL.query(Repo, q)\nend\n```\n\nIf you find yourself writing raw SQL, take care not to interpolate directly into the string, but rather use parameters for external input into the query.\n\n## Server Side Request Forgery (SSRF)\n\nServer Side Request Forgery (SSRF) is a critical vulnerability that has been the root cause of major data breaches. The problem is untrusted user input being used to make outbound HTTP requests, which leads to the exploitation of services reachable from your Phoenix application. \n\nWhen you create a server in most cloud providers today, for example AWS EC2, there will be a [metadata service](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-retrieval.html) exposed on a private IP address. In the case of AWS it's on `169.254.169.254`. If you send an HTTP request to:\n\n`http://169.254.169.254/iam/security-credentials`\n\nFrom the server, it will return credentials for the AWS account. If you write a web application (for example in Phoenix) where a user can enter a URL, and then view the response of an HTTP request sent to that URL, that functionality is potentially vulnerable to SSRF. For a real world incident see [the Capital One breach.](https://dl.acm.org/doi/pdf/10.1145/3546068)\n\nYour reaction to this may be \"This seems like an unsafe feature, considering they named an entire vulnerability class after it.\" You are not alone in this opinion, AWS introduced some SSRF specific mitigations in [2019 via IMDSv2](https://aws.amazon.com/blogs/security/defense-in-depth-open-firewalls-reverse-proxies-ssrf-vulnerabilities-ec2-instance-metadata-service/), requiring HTTP requests to the metadata endpoint to have session authentication. \n\nThe instance metadata service of cloud servers is not the only target for SSRF: services such as PostgreSQL, MySQL, Redis, Elasticsearch, even custom micro-services that you believe are not exposed to the public internet may be vulnerable to SSRF. Consider an internal server with vulnerabilities that can be exploited via HTTP requests, not directly exposed to the public internet. Yet if that network also has a Phoenix application vulnerable to SSRF, an attacker can go through the Phoenix server to attack the private server. \n\nTo summarize, using an HTTP client does not necessarily mean your application is vulnerable to SSRF. Rather the following conditions must be met:\n\n1. You are using external user input to construct URLs\n2. An attacker is able to send HTTP requests to some vulnerable server on your network \n\nFor an Elixir specific example consider the Req library:\n\n```\nreq = Req.new(base_url: \"https://api.github.com\")\n\nReq.get!(req, url: \"/repos/sneako/finch\").body[\"description\"]\n#=> \"Elixir HTTP client, focused on performance\"\n```\n\nIt is possible to override the `base_url` value:\n\n```\nreq = Req.new(base_url: \"https://elixir-lang.org/\")\nuser_input = \"https://dashbit.co/blog\"\nReq.get!(req, url: user_input) \n```\n\nThe above code sends a request to `https://dashbit.co/blog`, NOT `https://elixir-lang.org/`. \n\nConsider a similar example in Tesla:\n\n```\nplug Tesla.Middleware.BaseUrl, \"https://example.com/foo\"\n\nMyClient.get(\"http://example.com/bar\") # equals to GET http://example.com/bar\n```\n\nEven if you are setting a base URL in your application, don't treat it as a security barrier, because as these examples show it can be overwritten. Take care to avoid sending HTTP requests based on user input if you can avoid it, and be mindful of services on the same network as your Phoenix application that could be exploited via SSRF.\n\n## Cross Origin Resource Sharing (CORS) Misconfiguration \n\nCross Origin Resource Sharing (CORS) is a feature in modern web browsers which can be used to bypass the same origin policy, which is useful because your application can now load resources from a different site in the user's web browser. This is normally restricted by default. \n\nConsider a Phoenix API with a single page application (SPA) on a different domain:\n\n`app.example.com` - React frontend \n\n`api.example.com` - Backend in Elixir/Phoenix \n\nThe frontend `(app.example.com)` needs to fetch information about the current user, however the origins of these projects are different. The user's web browser will block the request unless CORS is enabled between the sites.\n\nSetting the following in the Phoenix application:\n\n```\nplug CORSPlug, origin: [\"https://app.example.com\"]\n```\n\nIs the correct way to do this. However it is also possible to set a policy that is far too broad, for example:\n\n```\nplug CORSPlug, origin: ~r/^http.*/\n```\n\nThis is a major security risk, because now a malicious site loaded by a user who is logged into the application can read sensitive data, for example API keys. Take care to ensure only trusted sites are allowed here. \n\n## Broken Access Control\n\nIn Phoenix controllers the standard way to handle authorization is putting the current user in the assigns, and then doing:\n\n```\nuser = conn.assigns.current_user\n```\n\nMany projects add this as a third argument in the controller actions:\n\n```\ndef action(conn, _) do\n args = [conn, conn.params, conn.assigns.current_user]\n apply(__MODULE__, action_name(conn), args)\nend\n```\n\nThis is the correct approach. The wrong approach is to accept arbitrary user input when making authorization decisions, for example:\n\n```\n# Not safe\ndef index(conn, %{\"user\" => user_email})\n user = Accounts.get_user_by_email(user_email)\n```\n\nIn the above example an attacker can simply change the submitted `user_email` string to an arbitrary value to perform an action as a different user. Using `conn.assigns.current_user` avoids this problem. \n\nRelated to the above concept, the design of Ecto in Phoenix takes the risk of mass assignment into consideration, because you have to explicitly define what parameters are allowed to be set from user supplied data. Consider a simple users schema:\n\n```\n schema \"users\" do\n field :email, :string\n field :password, :string, virtual: true, redact: true\n field :hashed_password, :string, redact: true\n field :confirmed_at, :naive_datetime\n field :is_admin, :boolean \n\n timestamps(type: :utc_datetime)\n end\n\n\n def registration_changeset(user, attrs, opts \\\\ []) do\n user\n |> cast(attrs, [:email, :password, :is_admin])\n |> validate_email()\n |> validate_password(opts)\n end\n```\n\nAssume that the corresponding signup form is exposed to the public internet. Can you spot the vulnerability? The problem is that `:is_admin` should never be set via external user input. Anyone on the public internet can now create a user where `:is_admin` is set to true in the database, which is likely not the intent of the developer.\n\n## Cross Site Scripting (XSS) \n\nBy default, user input in Phoenix is escaped so that:\n\n```\n<%= \"\" %>\n```\n\nis shown in your browser as:\n\n```text\n<hello>\n```\n\nNote that this looks like a normal string of `` from an end user perspective, the `<` and `>` are only visible if you inspect the page with your browser tools. \n\nIt is possible to bypass this protection via the `raw/1` function. For example, consider the string `hello`. \n\n```\n# This will render the literal string hello\n<%= \"hello\" %>\n\n# This will render a bold hello \n<%= raw \"hello\" %>\n```\n\nWith the ability to inject script tags, an attacker now has the ability to execute JavaScript in a victim's browser, for example by submitting a string such as: \n\n```html\n\n```\n\nIf someone submits the above input to your application, and it is displayed to logged in users, you have a serious problem. See the [2005 MySpace worm](https://en.wikipedia.org/wiki/Samy_(computer_worm)) for a real world example of this. \n\nUser input should never be passed into the `raw/1` function. There are some additional vectors for XSS in Phoenix applications, for example consider the following controller functions: \n\n\n```\ndef html_resp(conn, %{\"i\" => i}) do\n html(conn, \"#{i}\")\nend\n```\n\nBecause the HTML is being generated from user input, the function is vulnerable to XSS. This can also happen with `put_resp_content_type`:\n\n```\ndef send_resp_html(conn, %{\"i\" => i}) do\n conn\n |> put_resp_content_type(\"text/html\")\n |> send_resp(200, \"#{i}\")\nend\n```\n\nFile uploads can also lead to XSS.\n\n```\ndef new_upload(conn, _params) do\n render(conn, \"new_upload.html\")\nend\n\ndef upload(conn, %{\"upload\" => upload}) do\n %Plug.Upload{content_type: content_type, filename: filename, path: path} = upload\n ImgServer.put(filename, %{content_type: content_type, bin: File.read!(path)})\n redirect(conn, to: Routes.page_path(conn, :view_photo, filename))\nend\n\ndef view_photo(conn, %{\"filename\" => filename}) do\n case ImgServer.get(filename) do\n %{content_type: content_type, bin: bin} ->\n conn\n |> put_resp_content_type(content_type)\n |> send_resp(200, bin)\n _ ->\n conn\n |> put_resp_content_type(\"text/html\")\n |> send_resp(404, \"Not Found\")\n end\nend\n```\n\nUser input determines the `content-type` of the file. There is no validation on the type of file being uploaded, meaning `content-type` can be set so an HTML page is rendered. This is the source of the vulnerability. Consider the file `xss.html`, with the contents:\n\n```html\n\n```\n\nThis will result in JavaScript being executed in the browser of the victim who views the image. Restricting the `put_resp_content_type` argument to only image files would fix this vulnerability. \n\n\n## Cross Site Request Forgery (CSRF)\n\n### Standard CSRF in HTML forms\n\nCross site request forgery (CSRF) is a vulnerability that exists due to a quirk in how web browsers work. Consider a social media website that is vulnerable to CSRF. An attacker creates a malicious website aimed at legitimate users. When a victim visits the malicious site, it triggers a POST request in the victim’s browser, sending a message that was written by the attacker. This results in the victim’s account making a post written by the attacker.\n\nBut why is this possible? Shouldn't the web browser block POST requests initiated by a different website? There is a cookie feature called SameSite that addresses this problem, however it's good to understand what CSRF is and why Phoenix has built in protections. \n\nConsider the following form:\n\n```html\n\n\n```\n\nThis maps to the following HTTP request:\n\n```http_request_and_response\nPOST /posts HTTP/1.1\nHost: example.com\nContent-Type: application/x-www-form-urlencoded\nContent-Length: 53\n\npost[title]=My+Title&post[body]=This+is+the+body\n```\n\nAn attacker can embed the following form on `attacker.com`:\n\n```html\n\n```\n\nNote that this form does not even have to be visible to the victim user. When the user visits `attacker.com` the form will automatically submit a POST request on behalf of the victim, with the victim's current session cookie, to the vulnerable site. \n\nThe way most web frameworks, including Phoenix, mitigate this vulnerability is by requiring a CSRF token when submitting a form.\n\n```html\n\n\n```\n\nThis changes the previous HTTP request to:\n\n```http_request_and_response\nPOST /posts HTTP/1.1\nHost: example.com\nContent-Type: application/x-www-form-urlencoded\nContent-Length: 53\n\npost[title]=My+Title&post[body]=This+is+the+body&post[_csrf_token]=WUZXJh07BhAIJ24jP1d-KQEpLwYmMDwQ0-2eYNLH_x8oHoO_qv_HJDqZ\n```\n\nBecause the token is randomly generated, an attacker cannot predict what the value will be. The application is safe against CSRF attacks because Phoenix checks the value of this token by default via the `:protect_from_forgery` plug, which is included in the default `:browser` pipeline of a new Phoenix project:\n\n```\n# router.ex\n\n pipeline :browser do\n plug :accepts, [\"html\"]\n plug :fetch_session\n plug :fetch_live_flash\n plug :put_root_layout, {CarafeWeb.LayoutView, :root}\n plug :protect_from_forgery # <-- Checks the CSRF token value\n plug :put_secure_browser_headers\n plug :fetch_current_user\n end\n```\n\nCSRF protections are included in Phoenix by default, so your application is most likely not vulnerable if you are using the default settings. \n\n### Action Re-Use CSRF \n\nMost descriptions of CSRF focus on state changing POST requests and the need for random tokens, as was just covered. Is CSRF possible with a GET request? Yes, GET requests should never be used to perform state changing actions in a web application (place an order, transfer money, etc) because they cannot be protected against CSRF in the same way POST requests can. \n\nConsider the following form:\n\n```heex\n<.form :let={f} for={@bio_changeset} action={~p\"/users/settings/edit_bio\"} method=\"post\" id=\"edit_bio\">\n
\n \"\"\"\n end\n\n @doc \"\"\"\n Renders a button with navigation support.\n\n ## Examples\n\n <.button>Send!\n <.button phx-click=\"go\" variant=\"primary\">Send!\n <.button navigate={~p\"/\"}>Home\n \"\"\"\n attr :rest, :global, include: ~w(href navigate patch method download name value disabled)\n attr :class, :any\n attr :variant, :string, values: ~w(primary)\n slot :inner_block, required: true\n\n def button(%{rest: rest} = assigns) do\n variants = %{\"primary\" => \"btn-primary\", nil => \"btn-primary btn-soft\"}\n\n assigns =\n assign_new(assigns, :class, fn ->\n [\"btn\", Map.fetch!(variants, assigns[:variant])]\n end)\n\n if rest[:href] || rest[:navigate] || rest[:patch] do\n ~H\"\"\"\n <.link class={@class} {@rest}>\n {render_slot(@inner_block)}\n \n \"\"\"\n else\n ~H\"\"\"\n \n \"\"\"\n end\n end\n\n @doc \"\"\"\n Renders an input with label and error messages.\n\n A `Phoenix.HTML.FormField` may be passed as argument,\n which is used to retrieve the input name, id, and values.\n Otherwise all attributes may be passed explicitly.\n\n ## Types\n\n This function accepts all HTML input types, considering that:\n\n * You may also set `type=\"select\"` to render a `
![\"Phoenix](\"./priv/static/phoenix-orange.png\")
\n![\"Phoenix](\"/images/logo.svg\")
\n \n ![\"Phoenix](\"assets/images/welcome-to-phoenix.png\")
\n![\"Phoenix](\"assets/images/hello-from-phoenix.png\")
\n![\"Frank](\"assets/images/hello-world-from-frank.png\")
\n![\"Phoenix](\"assets/images/welcome-to-phoenix-dark.png\")
\n![\"Phoenix](\"assets/images/hello-from-phoenix-dark.png\")
\n![\"Frank](\"assets/images/hello-world-from-frank-dark.png\")
\n