cowboy/doc/src/manual/cowboy_req.read_urlencoded_body.asciidoc

= cowboy_req:read_urlencoded_body(3)

== Name

cowboy_req:read_urlencoded_body - Read and parse a urlencoded request body

== Description

[source,erlang]
----
read_urlencoded_body(Req :: cowboy_req:req())
    -> read_urlencoded_body(Req, #{})

read_urlencoded_body(Req :: cowboy_req:req(), Opts)
    -> {ok, Body, Req}

Opts :: cowboy_req:read_body_opts()
Body :: [{Key :: binary(), Value :: binary() | true}]
----

Read and parse a urlencoded request body.

This function reads the request body and parses it as
`application/x-www-form-urlencoded`. It returns a list
of key/values.

The urlencoded media type is used by Web browsers when
submitting HTML forms using the POST method.

Cowboy needs to read the full body before parsing. By default
it will read bodies of size up to 64KB. It is possible to
provide options to read larger bodies if required.

Cowboy will automatically handle protocol details including
the expect header, chunked transfer-encoding and others.

Once the body has been read, Cowboy sets the content-length
header if it was not previously provided.

This function can only be called once. Calling it again will
result in undefined behavior.

== Arguments

Req::

The Req object.

Opts::

A map of body reading options. Please refer to
link:man:cowboy_req:read_body(3)[cowboy_req:read_body(3)]
for details about each option.
+
This function defaults the `length` to 64KB and the `period`
to 5 seconds.

== Return value

An `ok` tuple is returned containing a list of key/values found
in the body.

The Req object returned in the tuple must be used for that point
onward. It contains a more up to date representation of the request.
For example it may have an added content-length header once the
body has been read.

== Changelog

* *2.0*: Function introduced. Replaces `body_qs/1,2`.

== Examples

.Read a urlencoded body
[source,erlang]
----
{ok, Body, Req} = cowboy_req:read_urlencoded_body(Req0),
{_, Lang} = lists:keyfind(<<"lang">>, 1, Body).
----

.Allow large urlencoded bodies
[source,erlang]
----
{ok, Body, Req} = cowboy_req:read_urlencoded_body(Req0, #{length => 1000000}).
----

== See also

link:man:cowboy_req(3)[cowboy_req(3)],
link:man:cowboy_req:has_body(3)[cowboy_req:has_body(3)],
link:man:cowboy_req:body_length(3)[cowboy_req:body_length(3)],
link:man:cowboy_req:read_body(3)[cowboy_req:read_body(3)],
link:man:cowboy_req:read_part(3)[cowboy_req:read_part(3)],
link:man:cowboy_req:read_part_body(3)[cowboy_req:read_part_body(3)]