Mojo::UserAgent::Transactor(3pm)

1Mojo::UserAgent::TransaUcsteorr(C3o)ntributed Perl DocumMeonjtoa:t:iUosnerAgent::Transactor(3)
2
3
4

NAME

6       Mojo::UserAgent::Transactor - User agent transactor
7

SYNOPSIS

9         use Mojo::UserAgent::Transactor;
10
11         # GET request with Accept header
12         my $t = Mojo::UserAgent::Transactor->new;
13         say $t->tx(GET => 'http://example.com' => {Accept => '*/*'})->req->to_string;
14
15         # POST request with form-data
16         say $t->tx(POST => 'example.com' => form => {a => 'b'})->req->to_string;
17
18         # PUT request with JSON data
19         say $t->tx(PUT => 'example.com' => json => {a => 'b'})->req->to_string;
20

DESCRIPTION

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

GENERATORS

26       These content generators are available by default.
27
28   form
29         $t->tx(POST => 'http://example.com' => form => {a => 'b'});
30
31       Generate query string, "application/x-www-form-urlencoded" or
32       "multipart/form-data" content. See "tx" for more.
33
34   json
35         $t->tx(PATCH => 'http://example.com' => json => {a => 'b'});
36
37       Generate JSON content with Mojo::JSON. See "tx" for more.
38
39   multipart
40         $t->tx(PUT => 'http://example.com' => multipart => ['Hello', 'World!']);
41
42       Generate multipart content. See "tx" for more.
43

ATTRIBUTES

45       Mojo::UserAgent::Transactor implements the following attributes.
46
47   compressed
48         my $bool = $t->compressed;
49         $t       = $t->compressed($bool);
50
51       Try to negotiate compression for the response content and decompress it
52       automatically, defaults to the value of the "MOJO_GZIP" environment
53       variable or true.
54
55   generators
56         my $generators = $t->generators;
57         $t             = $t->generators({foo => sub {...}});
58
59       Registered content generators, by default only "form", "json" and
60       "multipart" are already defined.
61
62   name
63         my $name = $t->name;
64         $t       = $t->name('Mojolicious');
65
66       Value for "User-Agent" request header of generated transactions,
67       defaults to "Mojolicious (Perl)".
68

METHODS

70       Mojo::UserAgent::Transactor inherits all methods from Mojo::Base and
71       implements the following new ones.
72
73   add_generator
74         $t = $t->add_generator(foo => sub {...});
75
76       Register a content generator.
77
78         $t->add_generator(foo => sub {
79           my ($t, $tx, @args) = @_;
80           ...
81         });
82
83   endpoint
84         my ($proto, $host, $port) = $t->endpoint(Mojo::Transaction::HTTP->new);
85
86       Actual endpoint for transaction.
87
88   peer
89         my ($proto, $host, $port) = $t->peer(Mojo::Transaction::HTTP->new);
90
91       Actual peer for transaction.
92
93   promisify
94         $t->promisify(Mojo::Promise->new, Mojo::Transaction::HTTP->new);
95
96       Resolve or reject Mojo::Promise object with Mojo::Transaction::HTTP
97       object.
98
99   proxy_connect
100         my $tx = $t->proxy_connect(Mojo::Transaction::HTTP->new);
101
102       Build Mojo::Transaction::HTTP proxy "CONNECT" request for transaction
103       if possible.
104
105   redirect
106         my $tx = $t->redirect(Mojo::Transaction::HTTP->new);
107
108       Build Mojo::Transaction::HTTP follow-up request for 301, 302, 303, 307
109       or 308 redirect response if possible.
110
111   tx
112         my $tx = $t->tx(GET  => 'example.com');
113         my $tx = $t->tx(POST => 'http://example.com');
114         my $tx = $t->tx(GET  => 'http://example.com' => {Accept => '*/*'});
115         my $tx = $t->tx(PUT  => 'http://example.com' => 'Content!');
116         my $tx = $t->tx(PUT  => 'http://example.com' => form => {a => 'b'});
117         my $tx = $t->tx(PUT  => 'http://example.com' => json => {a => 'b'});
118         my $tx = $t->tx(PUT  => 'https://example.com' => multipart => ['a', 'b']);
119         my $tx = $t->tx(POST => 'example.com' => {Accept => '*/*'} => 'Content!');
120         my $tx = $t->tx(
121           PUT => 'example.com' => {Accept => '*/*'} => form => {a => 'b'});
122         my $tx = $t->tx(
123           PUT => 'example.com' => {Accept => '*/*'} => json => {a => 'b'});
124         my $tx = $t->tx(
125           PUT => 'example.com' => {Accept => '*/*'} => multipart => ['a', 'b']);
126
127       Versatile general purpose Mojo::Transaction::HTTP transaction builder
128       for requests, with support for "GENERATORS".
129
130         # Generate and inspect custom GET request with DNT header and content
131         say $t->tx(GET => 'example.com' => {DNT => 1} => 'Bye!')->req->to_string;
132
133         # Stream response content to STDOUT
134         my $tx = $t->tx(GET => 'http://example.com');
135         $tx->res->content->unsubscribe('read')->on(read => sub { say $_[1] });
136
137         # PUT request with content streamed from file
138         my $tx = $t->tx(PUT => 'http://example.com');
139         $tx->req->content->asset(Mojo::Asset::File->new(path => '/foo.txt'));
140
141       The "json" content generator uses Mojo::JSON for encoding and sets the
142       content type to "application/json".
143
144         # POST request with "application/json" content
145         my $tx = $t->tx(
146           POST => 'http://example.com' => json => {a => 'b', c => [1, 2, 3]});
147
148       The "form" content generator will automatically use query parameters
149       for "GET" and "HEAD" requests.
150
151         # GET request with query parameters
152         my $tx = $t->tx(GET => 'http://example.com' => form => {a => 'b'});
153
154       For all other request methods the "application/x-www-form-urlencoded"
155       content type is used.
156
157         # POST request with "application/x-www-form-urlencoded" content
158         my $tx = $t->tx(
159           POST => 'http://example.com' => form => {a => 'b', c => 'd'});
160
161       Parameters may be encoded with the "charset" option.
162
163         # PUT request with Shift_JIS encoded form values
164         my $tx = $t->tx(
165           PUT => 'example.com' => form => {a => 'b'} => charset => 'Shift_JIS');
166
167       An array reference can be used for multiple form values sharing the
168       same name.
169
170         # POST request with form values sharing the same name
171         my $tx = $t->tx(
172           POST => 'http://example.com' => form => {a => ['b', 'c', 'd']});
173
174       A hash reference with a "content" or "file" value can be used to switch
175       to the "multipart/form-data" content type for file uploads.
176
177         # POST request with "multipart/form-data" content
178         my $tx = $t->tx(
179           POST => 'http://example.com' => form => {mytext => {content => 'lala'}});
180
181         # POST request with multiple files sharing the same name
182         my $tx = $t->tx(POST => 'http://example.com' =>
183           form => {mytext => [{content => 'first'}, {content => 'second'}]});
184
185       The "file" value should contain the path to the file you want to upload
186       or an asset object, like Mojo::Asset::File or Mojo::Asset::Memory.
187
188         # POST request with upload streamed from file
189         my $tx = $t->tx(
190           POST => 'http://example.com' => form => {mytext => {file => '/foo.txt'}});
191
192         # POST request with upload streamed from asset
193         my $asset = Mojo::Asset::Memory->new->add_chunk('lalala');
194         my $tx    = $t->tx(
195           POST => 'http://example.com' => form => {mytext => {file => $asset}});
196
197       A "filename" value will be generated automatically, but can also be set
198       manually if necessary. All remaining values in the hash reference get
199       merged into the "multipart/form-data" content as headers.
200
201         # POST request with form values and customized upload (filename and header)
202         my $tx = $t->tx(POST => 'http://example.com' => form => {
203           a      => 'b',
204           c      => 'd',
205           mytext => {
206             content        => 'lalala',
207             filename       => 'foo.txt',
208             'Content-Type' => 'text/plain'
209           }
210         });
211
212       The "multipart/form-data" content type can also be enforced by setting
213       the "Content-Type" header manually.
214
215         # Force "multipart/form-data"
216         my $headers = {'Content-Type' => 'multipart/form-data'};
217         my $tx = $t->tx(POST => 'example.com' => $headers => form => {a => 'b'});
218
219       The "multipart" content generator can be used to build custom multipart
220       requests and does not set a content type.
221
222         # POST request with multipart content ("foo" and "bar")
223         my $tx = $t->tx(POST => 'http://example.com' => multipart => ['foo', 'bar']);
224
225       Similar to the "form" content generator you can also pass hash
226       references with "content" or "file" values, as well as headers.
227
228         # POST request with multipart content streamed from file
229         my $tx = $t->tx(
230           POST => 'http://example.com' => multipart => [{file => '/foo.txt'}]);
231
232         # PUT request with multipart content streamed from asset
233         my $headers = {'Content-Type' => 'multipart/custom'};
234         my $asset   = Mojo::Asset::Memory->new->add_chunk('lalala');
235         my $tx      = $t->tx(
236           PUT => 'http://example.com' => $headers => multipart => [{file => $asset}]);
237
238         # POST request with multipart content and custom headers
239         my $tx = $t->tx(POST => 'http://example.com' => multipart => [
240           {
241             content            => 'Hello',
242             'Content-Type'     => 'text/plain',
243             'Content-Language' => 'en-US'
244           },
245           {
246             content            => 'World!',
247             'Content-Type'     => 'text/plain',
248             'Content-Language' => 'en-US'
249           }
250         ]);
251
252   upgrade
253         my $tx = $t->upgrade(Mojo::Transaction::HTTP->new);
254
255       Build Mojo::Transaction::WebSocket follow-up transaction for WebSocket
256       handshake if possible.
257
258   websocket
259         my $tx = $t->websocket('ws://example.com');
260         my $tx = $t->websocket('ws://example.com' => {DNT => 1} => ['v1.proto']);
261
262       Versatile Mojo::Transaction::HTTP transaction builder for WebSocket
263       handshake requests.
264

NAME

SYNOPSIS

DESCRIPTION

GENERATORS

ATTRIBUTES

METHODS

SEE ALSO