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.

   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 {
           my ($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.

   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, <http://mojolicious.org>.