.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Mojo::UserAgent::Transactor 3pm"
.TH Mojo::UserAgent::Transactor 3pm 2024-03-24 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Mojo::UserAgent::Transactor \- User agent transactor
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Mojo::UserAgent::Transactor;
\&
\&  # GET request with Accept header
\&  my $t = Mojo::UserAgent::Transactor\->new;
\&  say $t\->tx(GET => \*(Aqhttp://example.com\*(Aq => {Accept => \*(Aq*/*\*(Aq})\->req\->to_string;
\&
\&  # POST request with form\-data
\&  say $t\->tx(POST => \*(Aqexample.com\*(Aq => form => {a => \*(Aqb\*(Aq})\->req\->to_string;
\&
\&  # PUT request with JSON data
\&  say $t\->tx(PUT => \*(Aqexample.com\*(Aq => json => {a => \*(Aqb\*(Aq})\->req\->to_string;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Mojo::UserAgent::Transactor is the transaction building and manipulation framework used by Mojo::UserAgent.
.SH GENERATORS
.IX Header "GENERATORS"
These content generators are available by default.
.SS form
.IX Subsection "form"
.Vb 1
\&  $t\->tx(POST => \*(Aqhttp://example.com\*(Aq => form => {a => \*(Aqb\*(Aq});
.Ve
.PP
Generate query string, \f(CW\*(C`application/x\-www\-form\-urlencoded\*(C'\fR or \f(CW\*(C`multipart/form\-data\*(C'\fR content. See "tx" for more.
.SS json
.IX Subsection "json"
.Vb 1
\&  $t\->tx(PATCH => \*(Aqhttp://example.com\*(Aq => json => {a => \*(Aqb\*(Aq});
.Ve
.PP
Generate JSON content with Mojo::JSON. See "tx" for more.
.SS multipart
.IX Subsection "multipart"
.Vb 1
\&  $t\->tx(PUT => \*(Aqhttp://example.com\*(Aq => multipart => [\*(AqHello\*(Aq, \*(AqWorld!\*(Aq]);
.Ve
.PP
Generate multipart content. See "tx" for more.
.SH ATTRIBUTES
.IX Header "ATTRIBUTES"
Mojo::UserAgent::Transactor implements the following attributes.
.SS compressed
.IX Subsection "compressed"
.Vb 2
\&  my $bool = $t\->compressed;
\&  $t       = $t\->compressed($bool);
.Ve
.PP
Try to negotiate compression for the response content and decompress it automatically, defaults to the value of the
\&\f(CW\*(C`MOJO_GZIP\*(C'\fR environment variable or true.
.SS generators
.IX Subsection "generators"
.Vb 2
\&  my $generators = $t\->generators;
\&  $t             = $t\->generators({foo => sub {...}});
.Ve
.PP
Registered content generators, by default only \f(CW\*(C`form\*(C'\fR, \f(CW\*(C`json\*(C'\fR and \f(CW\*(C`multipart\*(C'\fR are already defined.
.SS name
.IX Subsection "name"
.Vb 2
\&  my $name = $t\->name;
\&  $t       = $t\->name(\*(AqMojolicious\*(Aq);
.Ve
.PP
Value for \f(CW\*(C`User\-Agent\*(C'\fR request header of generated transactions, defaults to \f(CW\*(C`Mojolicious (Perl)\*(C'\fR.
.SH METHODS
.IX Header "METHODS"
Mojo::UserAgent::Transactor inherits all methods from Mojo::Base and implements the following new ones.
.SS add_generator
.IX Subsection "add_generator"
.Vb 1
\&  $t = $t\->add_generator(foo => sub {...});
.Ve
.PP
Register a content generator.
.PP
.Vb 1
\&  $t\->add_generator(foo => sub ($t, $tx, @args) {...});
.Ve
.SS endpoint
.IX Subsection "endpoint"
.Vb 1
\&  my ($proto, $host, $port) = $t\->endpoint(Mojo::Transaction::HTTP\->new);
.Ve
.PP
Actual endpoint for transaction.
.SS peer
.IX Subsection "peer"
.Vb 1
\&  my ($proto, $host, $port) = $t\->peer(Mojo::Transaction::HTTP\->new);
.Ve
.PP
Actual peer for transaction.
.SS promisify
.IX Subsection "promisify"
.Vb 1
\&  $t\->promisify(Mojo::Promise\->new, Mojo::Transaction::HTTP\->new);
.Ve
.PP
Resolve or reject Mojo::Promise object with Mojo::Transaction::HTTP object.
.SS proxy_connect
.IX Subsection "proxy_connect"
.Vb 1
\&  my $tx = $t\->proxy_connect(Mojo::Transaction::HTTP\->new);
.Ve
.PP
Build Mojo::Transaction::HTTP proxy \f(CW\*(C`CONNECT\*(C'\fR request for transaction if possible.
.SS redirect
.IX Subsection "redirect"
.Vb 1
\&  my $tx = $t\->redirect(Mojo::Transaction::HTTP\->new);
.Ve
.PP
Build Mojo::Transaction::HTTP follow-up request for \f(CW301\fR, \f(CW302\fR, \f(CW303\fR, \f(CW307\fR or \f(CW308\fR redirect response if
possible.
.SS tx
.IX Subsection "tx"
.Vb 11
\&  my $tx = $t\->tx(GET  => \*(Aqexample.com\*(Aq);
\&  my $tx = $t\->tx(POST => \*(Aqhttp://example.com\*(Aq);
\&  my $tx = $t\->tx(GET  => \*(Aqhttp://example.com\*(Aq => {Accept => \*(Aq*/*\*(Aq});
\&  my $tx = $t\->tx(PUT  => \*(Aqhttp://example.com\*(Aq => \*(AqContent!\*(Aq);
\&  my $tx = $t\->tx(PUT  => \*(Aqhttp://example.com\*(Aq => form => {a => \*(Aqb\*(Aq});
\&  my $tx = $t\->tx(PUT  => \*(Aqhttp://example.com\*(Aq => json => {a => \*(Aqb\*(Aq});
\&  my $tx = $t\->tx(PUT  => \*(Aqhttps://example.com\*(Aq => multipart => [\*(Aqa\*(Aq, \*(Aqb\*(Aq]);
\&  my $tx = $t\->tx(POST => \*(Aqexample.com\*(Aq => {Accept => \*(Aq*/*\*(Aq} => \*(AqContent!\*(Aq);
\&  my $tx = $t\->tx(PUT => \*(Aqexample.com\*(Aq => {Accept => \*(Aq*/*\*(Aq} => form => {a => \*(Aqb\*(Aq});
\&  my $tx = $t\->tx(PUT => \*(Aqexample.com\*(Aq => {Accept => \*(Aq*/*\*(Aq} => json => {a => \*(Aqb\*(Aq});
\&  my $tx = $t\->tx(PUT => \*(Aqexample.com\*(Aq => {Accept => \*(Aq*/*\*(Aq} => multipart => [\*(Aqa\*(Aq, \*(Aqb\*(Aq]);
.Ve
.PP
Versatile general purpose Mojo::Transaction::HTTP transaction builder for requests, with support for
"GENERATORS".
.PP
.Vb 2
\&  # Generate and inspect custom GET request with DNT header and content
\&  say $t\->tx(GET => \*(Aqexample.com\*(Aq => {DNT => 1} => \*(AqBye!\*(Aq)\->req\->to_string;
\&
\&  # Stream response content to STDOUT
\&  my $tx = $t\->tx(GET => \*(Aqhttp://example.com\*(Aq);
\&  $tx\->res\->content\->unsubscribe(\*(Aqread\*(Aq)\->on(read => sub { say $_[1] });
\&
\&  # PUT request with content streamed from file
\&  my $tx = $t\->tx(PUT => \*(Aqhttp://example.com\*(Aq);
\&  $tx\->req\->content\->asset(Mojo::Asset::File\->new(path => \*(Aq/foo.txt\*(Aq));
.Ve
.PP
The \f(CW\*(C`json\*(C'\fR content generator uses Mojo::JSON for encoding and sets the content type to \f(CW\*(C`application/json\*(C'\fR.
.PP
.Vb 2
\&  # POST request with "application/json" content
\&  my $tx = $t\->tx(POST => \*(Aqhttp://example.com\*(Aq => json => {a => \*(Aqb\*(Aq, c => [1, 2, 3]});
.Ve
.PP
The \f(CW\*(C`form\*(C'\fR content generator will automatically use query parameters for \f(CW\*(C`GET\*(C'\fR and \f(CW\*(C`HEAD\*(C'\fR requests.
.PP
.Vb 2
\&  # GET request with query parameters
\&  my $tx = $t\->tx(GET => \*(Aqhttp://example.com\*(Aq => form => {a => \*(Aqb\*(Aq});
.Ve
.PP
For all other request methods the \f(CW\*(C`application/x\-www\-form\-urlencoded\*(C'\fR content type is used.
.PP
.Vb 2
\&  # POST request with "application/x\-www\-form\-urlencoded" content
\&  my $tx = $t\->tx(POST => \*(Aqhttp://example.com\*(Aq => form => {a => \*(Aqb\*(Aq, c => \*(Aqd\*(Aq});
.Ve
.PP
Parameters may be encoded with the \f(CW\*(C`charset\*(C'\fR option.
.PP
.Vb 2
\&  # PUT request with Shift_JIS encoded form values
\&  my $tx = $t\->tx(PUT => \*(Aqexample.com\*(Aq => form => {a => \*(Aqb\*(Aq} => charset => \*(AqShift_JIS\*(Aq);
.Ve
.PP
An array reference can be used for multiple form values sharing the same name.
.PP
.Vb 2
\&  # POST request with form values sharing the same name
\&  my $tx = $t\->tx(POST => \*(Aqhttp://example.com\*(Aq => form => {a => [\*(Aqb\*(Aq, \*(Aqc\*(Aq, \*(Aqd\*(Aq]});
.Ve
.PP
A hash reference with a \f(CW\*(C`content\*(C'\fR or \f(CW\*(C`file\*(C'\fR value can be used to switch to the \f(CW\*(C`multipart/form\-data\*(C'\fR content type
for file uploads.
.PP
.Vb 2
\&  # POST request with "multipart/form\-data" content
\&  my $tx = $t\->tx(POST => \*(Aqhttp://example.com\*(Aq => form => {mytext => {content => \*(Aqlala\*(Aq}});
\&
\&  # POST request with multiple files sharing the same name
\&  my $tx = $t\->tx(POST => \*(Aqhttp://example.com\*(Aq => form => {mytext => [{content => \*(Aqfirst\*(Aq}, {content => \*(Aqsecond\*(Aq}]});
.Ve
.PP
The \f(CW\*(C`file\*(C'\fR value should contain the path to the file you want to upload or an asset object, like Mojo::Asset::File
or Mojo::Asset::Memory.
.PP
.Vb 2
\&  # POST request with upload streamed from file
\&  my $tx = $t\->tx(POST => \*(Aqhttp://example.com\*(Aq => form => {mytext => {file => \*(Aq/foo.txt\*(Aq}});
\&
\&  # POST request with upload streamed from asset
\&  my $asset = Mojo::Asset::Memory\->new\->add_chunk(\*(Aqlalala\*(Aq);
\&  my $tx    = $t\->tx(POST => \*(Aqhttp://example.com\*(Aq => form => {mytext => {file => $asset}});
.Ve
.PP
A \f(CW\*(C`filename\*(C'\fR value will be generated automatically, but can also be set manually if necessary. All remaining values in
the hash reference get merged into the \f(CW\*(C`multipart/form\-data\*(C'\fR content as headers.
.PP
.Vb 10
\&  # POST request with form values and customized upload (filename and header)
\&  my $tx = $t\->tx(POST => \*(Aqhttp://example.com\*(Aq => form => {
\&    a      => \*(Aqb\*(Aq,
\&    c      => \*(Aqd\*(Aq,
\&    mytext => {
\&      content        => \*(Aqlalala\*(Aq,
\&      filename       => \*(Aqfoo.txt\*(Aq,
\&      \*(AqContent\-Type\*(Aq => \*(Aqtext/plain\*(Aq
\&    }
\&  });
.Ve
.PP
The \f(CW\*(C`multipart/form\-data\*(C'\fR content type can also be enforced by setting the \f(CW\*(C`Content\-Type\*(C'\fR header manually.
.PP
.Vb 3
\&  # Force "multipart/form\-data"
\&  my $headers = {\*(AqContent\-Type\*(Aq => \*(Aqmultipart/form\-data\*(Aq};
\&  my $tx = $t\->tx(POST => \*(Aqexample.com\*(Aq => $headers => form => {a => \*(Aqb\*(Aq});
.Ve
.PP
The \f(CW\*(C`multipart\*(C'\fR content generator can be used to build custom multipart requests and does not set a content type.
.PP
.Vb 2
\&  # POST request with multipart content ("foo" and "bar")
\&  my $tx = $t\->tx(POST => \*(Aqhttp://example.com\*(Aq => multipart => [\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq]);
.Ve
.PP
Similar to the \f(CW\*(C`form\*(C'\fR content generator you can also pass hash references with \f(CW\*(C`content\*(C'\fR or \f(CW\*(C`file\*(C'\fR values, as well
as headers.
.PP
.Vb 2
\&  # POST request with multipart content streamed from file
\&  my $tx = $t\->tx(POST => \*(Aqhttp://example.com\*(Aq => multipart => [{file => \*(Aq/foo.txt\*(Aq}]);
\&
\&  # PUT request with multipart content streamed from asset
\&  my $headers = {\*(AqContent\-Type\*(Aq => \*(Aqmultipart/custom\*(Aq};
\&  my $asset   = Mojo::Asset::Memory\->new\->add_chunk(\*(Aqlalala\*(Aq);
\&  my $tx      = $t\->tx(PUT => \*(Aqhttp://example.com\*(Aq => $headers => multipart => [{file => $asset}]);
\&
\&  # POST request with multipart content and custom headers
\&  my $tx = $t\->tx(POST => \*(Aqhttp://example.com\*(Aq => multipart => [
\&    {
\&      content            => \*(AqHello\*(Aq,
\&      \*(AqContent\-Type\*(Aq     => \*(Aqtext/plain\*(Aq,
\&      \*(AqContent\-Language\*(Aq => \*(Aqen\-US\*(Aq
\&    },
\&    {
\&      content            => \*(AqWorld!\*(Aq,
\&      \*(AqContent\-Type\*(Aq     => \*(Aqtext/plain\*(Aq,
\&      \*(AqContent\-Language\*(Aq => \*(Aqen\-US\*(Aq
\&    }
\&  ]);
.Ve
.SS upgrade
.IX Subsection "upgrade"
.Vb 1
\&  my $tx = $t\->upgrade(Mojo::Transaction::HTTP\->new);
.Ve
.PP
Build Mojo::Transaction::WebSocket follow-up transaction for WebSocket handshake if possible.
.SS websocket
.IX Subsection "websocket"
.Vb 2
\&  my $tx = $t\->websocket(\*(Aqws://example.com\*(Aq);
\&  my $tx = $t\->websocket(\*(Aqws://example.com\*(Aq => {DNT => 1} => [\*(Aqv1.proto\*(Aq]);
.Ve
.PP
Versatile Mojo::Transaction::HTTP transaction builder for WebSocket handshake requests.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mojolicious, Mojolicious::Guides, <https://mojolicious.org>.