Mojo::U...ansactor(3)

💅 Mojo::UserAgent::Transactor — the user agent transactor, bestie ✨

okay so this is a page from the User Contributed Perl Documentation set, and it's literally the whole transaction-building situation for Mojo::UserAgent. stay with me, it's gonna slay 🫶

---

🌸 NAME 🌸

Mojo::UserAgent::Transactor — user agent transactor. that's it, that's the name, no cap 💖

---

✨ SYNOPSIS ✨

like, here's the vibe in code form:

use Mojo::UserAgent::Transactor;

# GET request with Accept header
my $t = Mojo::UserAgent::Transactor->new;
say $t->tx(GET => 'http://example.com' => {Accept => '*/*'})->req->to_string;

# POST request with form-data
say $t->tx(POST => 'example.com' => form => {a => 'b'})->req->to_string;

# PUT request with JSON data
say $t->tx(PUT => 'example.com' => json => {a => 'b'})->req->to_string;

three examples, three baddies, all iconic 👑

---

🦋 DESCRIPTION 🦋

Mojo::UserAgent::Transactor is the transaction building and manipulation framework used by Mojo::UserAgent. so it's basically the backstage crew making Mojo::UserAgent look flawless on stage. main character energy fr fr 💅

---

🎀 GENERATORS 🎀

these content generators are available by default, bestie. no setup, they just come with the gig ✨

🍓 form

$t->tx(POST => 'http://example.com' => form => {a => 'b'});

generates query string, application/x-www-form-urlencoded or multipart/form-data content. see "tx" for more. she picks her outfit based on the situation 💁‍♀️

🍓 json

$t->tx(PATCH => 'http://example.com' => json => {a => 'b'});

generates JSON content with Mojo::JSON. see "tx" for more. yes queen, structured data 🌈

🍓 multipart

$t->tx(PUT => 'http://example.com' => multipart => ['Hello', 'World!']);

generates multipart content. see "tx" for more. very "I contain multitudes" of it 💀

---

👑 ATTRIBUTES 👑

Mojo::UserAgent::Transactor implements the following attributes. yes, implements. she's capable 🫶

💜 compressed

my $bool = $t->compressed;
$t       = $t->compressed($bool);

try to negotiate compression for the response content and decompress it automatically. defaults to the value of the MOJO_GZIP environment variable or true. so like, compression is on by default unless MOJO_GZIP says otherwise 💖

💜 generators

my $generators = $t->generators;
$t             = $t->generators({foo => sub {...}});

registered content generators — by default only "form", "json" and "multipart" are already defined. the holy trinity, honestly ⭐

💜 name

my $name = $t->name;
$t       = $t->name('Mojolicious');

value for the "User-Agent" request header of generated transactions, defaults to "Mojolicious (Perl)". it's giving branding, it's giving identity 🎀

---

🔥 METHODS 🔥

Mojo::UserAgent::Transactor inherits all methods from Mojo::Base and implements the following new ones. so everything from Mojo::Base is included, plus these 💅

🌟 add_generator

$t = $t->add_generator(foo => sub {...});

register a content generator. super straightforward. then the signature looks like:

$t->add_generator(foo => sub ($t, $tx, @args) {...});

look at those arguments living their best life ✨

🌟 download

my $tx = $t->download(Mojo::Transaction::HTTP->new, '/home/sri/test.tar.gz');

build Mojo::Transaction::HTTP resumable file download request as follow-up to a "HEAD" request.

😭 heads up bestie: this method is EXPERIMENTAL and might change without warning! don't get too attached, she's still figuring herself out 💀

🌟 endpoint

my ($proto, $host, $port) = $t->endpoint(Mojo::Transaction::HTTP->new);

actual endpoint for transaction. where she really at 🌸

🌟 peer

my ($proto, $host, $port) = $t->peer(Mojo::Transaction::HTTP->new);

actual peer for transaction. her plus-one, her connection 🫶

🌟 promisify

$t->promisify(Mojo::Promise->new, Mojo::Transaction::HTTP->new);

resolve or reject Mojo::Promise object with Mojo::Transaction::HTTP object. promises!! keeping them, apparently 👑

🌟 proxy_connect

my $tx = $t->proxy_connect(Mojo::Transaction::HTTP->new);

build Mojo::Transaction::HTTP proxy "CONNECT" request for transaction if possible. if possible, key phrase, no overpromising 🧚

🌟 redirect

my $tx = $t->redirect(Mojo::Transaction::HTTP->new);

build Mojo::Transaction::HTTP follow-up request for 301, 302, 303, 307 or 308 redirect response if possible.

and here's the specific tea ☕: since "QUERY" requests are safe and idempotent, they are never redirected as "GET" requests and keep their content — except for 303 responses. periodt. 💅

🌟 tx

okay queen, this is the big one — the versatile general purpose builder. look at all these forms, every single one is valid:

my $tx = $t->tx(GET  => 'example.com');
my $tx = $t->tx(POST => 'http://example.com');
my $tx = $t->tx(GET  => 'http://example.com' => {Accept => '*/*'});
my $tx = $t->tx(PUT  => 'http://example.com' => 'Content!');
my $tx = $t->tx(PUT  => 'http://example.com' => form => {a => 'b'});
my $tx = $t->tx(PUT  => 'http://example.com' => json => {a => 'b'});
my $tx = $t->tx(PUT  => 'https://example.com' => multipart => ['a', 'b']);
my $tx = $t->tx(POST => 'example.com' => {Accept => '*/*'} => 'Content!');
my $tx = $t->tx(PUT => 'example.com' => {Accept => '*/*'} => form => {a => 'b'});
my $tx = $t->tx(PUT => 'example.com' => {Accept => '*/*'} => json => {a => 'b'});
my $tx = $t->tx(PUT => 'example.com' => {Accept => '*/*'} => multipart => ['a', 'b']);

versatile general purpose Mojo::Transaction::HTTP transaction builder for requests, with support for "GENERATORS". she does it all 💖

and some extra inspo:

# Generate and inspect custom GET request with DNT header and content
say $t->tx(GET => 'example.com' => {DNT => 1} => 'Bye!')->req->to_string;

# Stream response content to STDOUT
my $tx = $t->tx(GET => 'http://example.com');
$tx->res->content->unsubscribe('read')->on(read => sub { say $_[1] });

# PUT request with content streamed from file
my $tx = $t->tx(PUT => 'http://example.com');
$tx->req->content->asset(Mojo::Asset::File->new(path => '/foo.txt'));

k so now the content generators, one by one, because details matter:

the "json" content generator uses Mojo::JSON for encoding and sets the content type to application/json.

# POST request with "application/json" content
my $tx = $t->tx(POST => 'http://example.com' => json => {a => 'b', c => [1, 2, 3]});

the "form" content generator will automatically use query parameters for "GET" and "HEAD" requests.

# GET request with query parameters
my $tx = $t->tx(GET => 'http://example.com' => form => {a => 'b'});

for all other request methods the application/x-www-form-urlencoded content type is used.

# POST request with "application/x-www-form-urlencoded" content
my $tx = $t->tx(POST => 'http://example.com' => form => {a => 'b', c => 'd'});

parameters may be encoded with the "charset" option. cute, multilingual, global 🌍

# PUT request with Shift_JIS encoded form values
my $tx = $t->tx(PUT => 'example.com' => form => {a => 'b'} => charset => 'Shift_JIS');

an array reference can be used for multiple form values sharing the same name. sharing = caring 🫶

# POST request with form values sharing the same name
my $tx = $t->tx(POST => 'http://example.com' => form => {a => ['b', 'c', 'd']});

a hash reference with a "content" or "file" value can be used to switch to the multipart/form-data content type for file uploads. glow up moment ✨

# POST request with "multipart/form-data" content
my $tx = $t->tx(POST => 'http://example.com' => form => {mytext => {content => 'lala'}});

# POST request with multiple files sharing the same name
my $tx = $t->tx(POST => 'http://example.com' => form => {mytext => [{content => 'first'}, {content => 'second'}]});

the "file" value should contain the path to the file you want to upload, or an asset object, like Mojo::Asset::File or Mojo::Asset::Memory.

# POST request with upload streamed from file
my $tx = $t->tx(POST => 'http://example.com' => form => {mytext => {file => '/foo.txt'}});

# POST request with upload streamed from asset
my $asset = Mojo::Asset::Memory->new->add_chunk('lalala');
my $tx    = $t->tx(POST => 'http://example.com' => form => {mytext => {file => $asset}});

a "filename" value will be generated automatically, but can also be set manually if necessary. and — plot twist — all remaining values in the hash reference get merged into the multipart/form-data content as headers. multi-tasking icon 💅

# POST request with form values and customized upload (filename and header)
my $tx = $t->tx(POST => 'http://example.com' => form => {
  a      => 'b',
  c      => 'd',
  mytext => {
    content        => 'lalala',
    filename       => 'foo.txt',
    'Content-Type' => 'text/plain'
  }
});

the multipart/form-data content type can also be enforced by setting the "Content-Type" header manually. you can just decide, and honestly? love that for you 👑

# Force "multipart/form-data"
my $headers = {'Content-Type' => 'multipart/form-data'};
my $tx = $t->tx(POST => 'example.com' => $headers => form => {a => 'b'});

the "multipart" content generator can be used to build custom multipart requests and does not set a content type. she's lowkey hands-off about it 💀

# POST request with multipart content ("foo" and "bar")
my $tx = $t->tx(POST => 'http://example.com' => multipart => ['foo', 'bar']);

similar to the "form" content generator, you can also pass hash references with "content" or "file" values, as well as headers.

# POST request with multipart content streamed from file
my $tx = $t->tx(POST => 'http://example.com' => multipart => [{file => '/foo.txt'}]);

# PUT request with multipart content streamed from asset
my $headers = {'Content-Type' => 'multipart/custom'};
my $asset   = Mojo::Asset::Memory->new->add_chunk('lalala');
my $tx      = $t->tx(PUT => 'http://example.com' => $headers => multipart => [{file => $asset}]);

# POST request with multipart content and custom headers
my $tx = $t->tx(POST => 'http://example.com' => multipart => [
  {
    content            => 'Hello',
    'Content-Type'     => 'text/plain',
    'Content-Language' => 'en-US'
  },
  {
    content            => 'World!',
    'Content-Type'     => 'text/plain',
    'Content-Language' => 'en-US'
  }
]);

ok that was a lot but you ate that, bestie 🍓

🌟 upgrade

my $tx = $t->upgrade(Mojo::Transaction::HTTP->new);

build Mojo::Transaction::WebSocket follow-up transaction for WebSocket handshake if possible. level up, literally 🔥

🌟 websocket

my $tx = $t->websocket('ws://example.com');
my $tx = $t->websocket('ws://example.com' => {DNT => 1} => ['v1.proto']);

versatile Mojo::Transaction::HTTP transaction builder for WebSocket handshake requests. two-way communication queen 🌈

---

💀 SEE ALSO 💀

Mojolicious, Mojolicious::Guides, <https://mojolicious.org>. go read those too, iykyk ✨

---

and that's the whole page, bestie! 💖 this one shipped as perl v5.42.0, dated 2026-07-15, from the User Contributed Perl Documentation collection — drop a 🎀 for the transactor, she's been working overtime 🫶