phoenix-conn.md

   1 ---
   2 title: "Phoenix: Plug.Conn"
   3 category: Elixir
   4 layout: 2017/sheet
   5 updated: 2018-01-19
   6 weight: -5
   7 ---
   8
   9 Request
  10 -------
  11
  12 ### Request
  13 {: .-prime}
  14
  15 ```elixir
  16 conn.host          # → "example.com"
  17 conn.method        # → "GET"
  18 conn.path_info     # → ["posts", "1"]
  19 conn.request_path  # → "/posts/1"
  20 conn.query_string  # → "utm_source=twitter"
  21 conn.port          # → 80
  22 conn.scheme        # → :http
  23 conn.peer          # → { {127, 0, 0, 1}, 12345 }
  24 conn.remote_ip     # → { 151, 236, 219, 228 }
  25 conn.req_headers   # → [{"content-type", "text/plain"}]
  26 ```
  27
  28 ```elixir
  29 conn |> get_req_header("content-type")
  30 # → ["text/plain"]
  31 ```
  32
  33 ### Updating conn
  34
  35 ```elixir
  36 conn
  37 |> put_req_header("accept", "application/json")
  38 ```
  39
  40 Usually only useful for tests.
  41
  42 Response
  43 --------
  44
  45 ### Response
  46 {: .-prime}
  47
  48 ```elixir
  49 conn.resp_body     # → "..."
  50 conn.resp_charset  # → "utf-8"
  51 conn.resp_cookies  # → ...
  52 conn.resp_headers  # → ...
  53 conn.status        # → ...
  54 ```
  55
  56 ### Sending responses
  57
  58 ```elixir
  59 # Plug.Conn
  60 conn
  61 |> html("<html><head>...")
  62 |> json(%{ message: "Hello" })
  63 |> text("Hello")
  64 ```
  65
  66 ```elixir
  67 |> redirect(to: "/foo")
  68 |> redirect(external: "http://www.google.com/")
  69 |> halt()
  70 ```
  71
  72 ```elixir
  73 |> put_resp_content_type("text/plain")
  74 |> put_resp_cookie("abc", "def")
  75 |> put_resp_header("X-Delivered-By", "myapp")
  76 |> put_status(202)
  77 |> put_status(:not_found)
  78 ```
  79
  80 ```elixir
  81 |> put_private(:plug_foo, "...")  # reserved for libraries
  82 ```
  83
  84 ```elixir
  85 |> send_resp(201, "")
  86 ```
  87
  88 ### Phoenix views
  89
  90 ```elixir
  91 # Phoenix.Controller
  92 conn
  93 |> render("index.html")
  94 |> render("index.html", hello: "world")
  95 |> render(MyApp.ErrorView, "404.html")
  96 ```
  97
  98 ```elixir
  99 |> put_layout(:foo)
 100 |> put_layout(false)
 101 |> put_view(ErrorView)
 102 ```
 103
 104 ```elixir
 105 |> put_secure_browser_headers()
 106 # prevent clickjacking, nosniff, and xss protection
 107 # x-frame-options, x-content-type-options, x-xss-protection
 108 ```
 109
 110 ```elixir
 111 |> put_new_view(ErrorView)  # if not set yet
 112 |> put_new_layout(:foo)
 113 ```
 114
 115 ```elixir
 116 layout(conn)
 117 ```
 118
 119 Other features
 120 --------------
 121
 122 ### Other fields
 123 {: .-prime}
 124
 125 ```elixir
 126 conn.assigns          # storage of crap
 127 conn.owner            # process
 128 conn.halted           # if pipeline was halted
 129 conn.secret_key_base  # ...
 130 conn.state            # :unset, :set, :file, :sent, :chunked
 131 ```
 132
 133 ### Accepts
 134
 135 ```js
 136 plug :accepts, ["html", "json"]
 137 conn |> accepts(["html", "json"])
 138 get_format(conn)  # → "html"
 139 conn.accepts
 140 ```
 141
 142 ### Assigns
 143
 144 ```elixir
 145 conn.assigns[:hello]
 146 conn |> assign(:user_id, 100)
 147 ```
 148
 149 ```elixir
 150 conn = async_assign(conn, :location, fn -> geoip_lookup() end)
 151 await_assign(conn, :location)
 152 ```
 153
 154 ### Session
 155
 156 ```elixir
 157 conn = fetch_session(conn)   # or plug :fetch_session
 158
 159 conn = put_session(conn, :message, "new stuff we just set in the session")
 160 get_session(conn, :message)
 161 conn = clear_session(conn)
 162 ```
 163
 164 ```elixir
 165 conn
 166 |> put_flash(:info, "Success")
 167 |> put_flash(:error, "Oh no")
 168 ```
 169
 170 Also available: `flash` `cookie` `params`
 171