---
name: "Mojo::UserAgent::Transactor"
section: "3pm"
platform: "linux"
package: "libmojolicious-perl"
version: "9.39+dfsg-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Mojo::UserAgent::Transactor"
---

# Mojo::UserAgent::Transactor(3pm)

User agent transactor

## NAME

Mojo::UserAgent::Transactor - User agent transactor

## SYNOPSIS

```
  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;
```

## DESCRIPTION

Mojo::UserAgent::Transactor is the transaction building and manipulation framework used by Mojo::UserAgent.

## GENERATORS

These content generators are available by default.

### form

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

Generate query string, `"application/x-www-form-urlencoded"` or `"multipart/form-data"` content. See "tx" for more.

### json

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

Generate JSON content with Mojo::JSON. See "tx" for more.

### multipart

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

Generate multipart content. See "tx" for more.

## ATTRIBUTES

Mojo::UserAgent::Transactor implements the following attributes.

### 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.

### generators

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

Registered content generators, by default only `"form"`, `"json"` and `"multipart"` are already defined.

### name

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

Value for `"User-Agent"` request header of generated transactions, defaults to `"Mojolicious (Perl)"`.

## METHODS

Mojo::UserAgent::Transactor inherits all methods from Mojo::Base and implements the following new ones.

### add\_generator

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

Register a content generator.

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

### endpoint

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

Actual endpoint for transaction.

### peer

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

Actual peer for transaction.

### promisify

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

Resolve or reject Mojo::Promise object with Mojo::Transaction::HTTP object.

### proxy\_connect

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

Build Mojo::Transaction::HTTP proxy `"CONNECT"` request for transaction if possible.

### 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.

### tx

```
  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".

```
  # 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'));
```

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.

```
  # 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.

```
  # 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.

```
  # 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. All remaining values in the hash reference get merged into the `"multipart/form-data"` content as headers.

```
  # 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.

```
  # 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.

```
  # 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'
    }
  ]);
```

### upgrade

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

Build Mojo::Transaction::WebSocket follow-up transaction for WebSocket handshake if possible.

### 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.

## SEE ALSO

Mojolicious, Mojolicious::Guides, \<https://mojolicious.org\>.