Mojo::UserAgent(3) User Contributed Perl Documentation Mojo::UserAgent(3)NAMEMojo::UserAgent - Non-Blocking I/O HTTP 1.1 And WebSocket User Agent
SYNOPSIS
use Mojo::UserAgent;
my $ua = Mojo::UserAgent->new;
# Say hello to the unicode snowman
print $ua->get('www.X.net?hello=there')->res->body;
# Quick JSON API request with Basic authentication
print $ua->get('https://sri:s3cret@api.twitter.com/1/trends.json')
->res->json->{trends}->[0]->{name};
# Extract data from HTML and XML resources
print $ua->get('mojolicio.us')->res->dom->html->head->title->text;
# Scrape the latest headlines from a news site
$ua->max_redirects(5)->get('www.reddit.com/r/perl/')
->res->dom('p.title > a.title')->each(sub { print $_->text, "\n" });
# Form post with exception handling
my $tx = $ua->post_form('search.cpan.org/search' => {q => 'mojo'});
if (my $res = $tx->success) { print $res->body }
else {
my ($message, $code) = $tx->error;
print "Error: $message";
}
# Grab the latest Mojolicious release :)
$ua->max_redirects(5)->get('latest.mojolicio.us')
->res->content->asset->move_to('/Users/sri/mojo.tar.gz');
# Parallel requests
my $t = Mojo::IOLoop->trigger;
for my $url ('mojolicio.us', 'cpan.org') {
$t->begin;
$ua->get($url => sub {
my ($self, $tx) = @_;
$t->end($tx->res->dom->at('title')->text);
});
}
my @titles = $t->start;
# TLS certificate authentication
my $tx = $ua->cert('tls.crt')->key('tls.key')->get('https://mojolicio.us');
# WebSocket request
$ua->websocket('ws://websockets.org:8787' => sub {
my ($self, $tx) = @_;
$tx->on_finish(sub { Mojo::IOLoop->stop });
$tx->on_message(sub {
my ($tx, $message) = @_;
print "$message\n";
$tx->finish;
});
$tx->send_message('hi there!');
});
Mojo::IOLoop->start;
DESCRIPTIONMojo::UserAgent is a full featured non-blocking I/O HTTP 1.1 and
WebSocket user agent with "IPv6", "TLS" and "libev" support.
Optional modules EV, IO::Socket::IP and IO::Socket::SSL are supported
transparently and used if installed.
ATTRIBUTESMojo::UserAgent implements the following attributes.
"cert"
my $cert = $ua->cert;
$ua = $ua->cert('tls.crt');
Path to TLS certificate file, defaults to the value of the
"MOJO_CERT_FILE" environment variable.
"cookie_jar"
my $cookie_jar = $ua->cookie_jar;
$ua = $ua->cookie_jar(Mojo::CookieJar->new);
Cookie jar to use for this user agents requests, defaults to a
Mojo::CookieJar object.
"http_proxy"
my $proxy = $ua->http_proxy;
$ua = $ua->http_proxy('http://sri:secret@127.0.0.1:8080');
Proxy server to use for HTTP and WebSocket requests.
"https_proxy"
my $proxy = $ua->https_proxy;
$ua = $ua->https_proxy('http://sri:secret@127.0.0.1:8080');
Proxy server to use for HTTPS and WebSocket requests.
"ioloop"
my $loop = $ua->ioloop;
$ua = $ua->ioloop(Mojo::IOLoop->new);
Loop object to use for blocking I/O operations, defaults to a
Mojo::IOLoop object.
"keep_alive_timeout"
my $keep_alive_timeout = $ua->keep_alive_timeout;
$ua = $ua->keep_alive_timeout(15);
Maximum amount of time in seconds a connection can be inactive before
being dropped, defaults to 15.
"key"
my $key = $ua->key;
$ua = $ua->key('tls.crt');
Path to TLS key file, defaults to the value of the "MOJO_KEY_FILE"
environment variable.
"log"
my $log = $ua->log;
$ua = $ua->log(Mojo::Log->new);
A Mojo::Log object used for logging, defaults to the application log or
a Mojo::Log object.
"max_connections"
my $max_connections = $ua->max_connections;
$ua = $ua->max_connections(5);
Maximum number of keep alive connections that the user agent will
retain before it starts closing the oldest cached ones, defaults to 5.
"max_redirects"
my $max_redirects = $ua->max_redirects;
$ua = $ua->max_redirects(3);
Maximum number of redirects the user agent will follow before it fails,
defaults to the value of the "MOJO_MAX_REDIRECTS" environment variable
or 0.
"name"
my $name = $ua->name;
$ua = $ua->name('Mojolicious');
Value for "User-Agent" request header, defaults to "Mojolicious
(Perl)".
"no_proxy"
my $no_proxy = $ua->no_proxy;
$ua = $ua->no_proxy(['localhost', 'intranet.mojolicio.us']);
Domains that don't require a proxy server to be used. Note that this
attribute is EXPERIMENTAL and might change without warning!
"on_start"
my $cb = $ua->on_start;
$ua = $ua->on_start(sub {...});
Callback to be invoked whenever a new transaction is about to start,
this includes automatically prepared proxy "CONNECT" requests and
followed redirects.
$ua->on_start(sub {
my ($ua, $tx) = @_;
$tx->req->headers->header('X-Bender', 'Bite my shiny metal ass!');
});
"transactor"
my $t = $ua->transactor;
$ua = $ua->transactor(Mojo::UserAgent::Transactor->new);
Transaction builder, defaults to a Mojo::UserAgent::Transactor object.
Note that this attribute is EXPERIMENTAL and might change without
warning!
"websocket_timeout"
my $websocket_timeout = $ua->websocket_timeout;
$ua = $ua->websocket_timeout(300);
Maximum amount of time in seconds a WebSocket connection can be
inactive before being dropped, defaults to 300.
METHODSMojo::UserAgent inherits all methods from Mojo::Base and implements the
following new ones.
"app"
my $app = $ua->app;
$ua = $ua->app('MyApp');
$ua = $ua->app(MyApp->new);
Application relative URLs will be processed with, defaults to the value
of the "MOJO_APP" environment variable.
print $ua->app->secret;
$ua->app->log->level('fatal');
$ua->app->defaults(testing => 'oh yea!');
"build_form_tx"
my $tx = $ua->build_form_tx('http://kraih.com/foo' => {test => 123});
Alias for "form" in Mojo::UserAgent::Transactor.
"build_tx"
my $tx = $ua->build_tx(GET => 'mojolicio.us');
Alias for "tx" in Mojo::UserAgent::Transactor.
"build_websocket_tx"
my $tx = $ua->build_websocket_tx('ws://localhost:3000');
Alias for "websocket" in Mojo::UserAgent::Transactor.
"delete"
my $tx = $ua->delete('http://kraih.com');
Perform blocking HTTP "DELETE" request and return resulting
Mojo::Transaction::HTTP object, takes the exact same arguments as "tx"
in Mojo::UserAgent::Transactor (except for the method). You can also
append a callback to perform requests non-blocking.
$ua->delete('http://kraih.com' => sub {
my ($self, $tx) = @_;
print $tx->res->body;
Mojo::IOLoop->stop;
});
Mojo::IOLoop->start;
"detect_proxy"
$ua = $ua->detect_proxy;
Check environment variables "HTTP_PROXY", "http_proxy", "HTTPS_PROXY",
"https_proxy", "NO_PROXY" and "no_proxy" for proxy information.
"get"
my $tx = $ua->get('http://kraih.com');
Perform blocking HTTP "GET" request and return resulting
Mojo::Transaction::HTTP object, takes the exact same arguments as "tx"
in Mojo::UserAgent::Transactor (except for the method). You can also
append a callback to perform requests non-blocking.
$ua->get('http://kraih.com' => sub {
my ($self, $tx) = @_;
print $tx->res->body;
Mojo::IOLoop->stop;
});
Mojo::IOLoop->start;
"head"
my $tx = $ua->head('http://kraih.com');
Perform blocking HTTP "HEAD" request and return resulting
Mojo::Transaction::HTTP object, takes the exact same arguments as "tx"
in Mojo::UserAgent::Transactor (except for the method). You can also
append a callback to perform requests non-blocking.
$ua->head('http://kraih.com' => sub {
my ($self, $tx) = @_;
print $tx->res->body;
Mojo::IOLoop->stop;
});
Mojo::IOLoop->start;
"need_proxy"
my $need_proxy = $ua->need_proxy('intranet.mojolicio.us');
Check if request for domain would use a proxy server. Note that this
method is EXPERIMENTAL and might change without warning!
"post"
my $tx = $ua->post('http://kraih.com');
Perform blocking HTTP "POST" request and return resulting
Mojo::Transaction::HTTP object, takes the exact same arguments as "tx"
in Mojo::UserAgent::Transactor (except for the method). You can also
append a callback to perform requests non-blocking.
$ua->post('http://kraih.com' => sub {
my ($self, $tx) = @_;
print $tx->res->body;
Mojo::IOLoop->stop;
});
Mojo::IOLoop->start;
"post_form"
my $tx = $ua->post_form('http://kraih.com/foo' => {test => 123});
Perform blocking HTTP "POST" request with form data and return
resulting Mojo::Transaction::HTTP object, takes the exact same
arguments as "form" in Mojo::UserAgent::Transactor. You can also
append a callback to perform requests non-blocking.
$ua->post_form('http://kraih.com' => {q => 'test'} => sub {
my ($self, $tx) = @_;
print $tx->res->body;
Mojo::IOLoop->stop;
});
Mojo::IOLoop->start;
"put"
my $tx = $ua->put('http://kraih.com');
Perform blocking HTTP "PUT" request and return resulting
Mojo::Transaction::HTTP object, takes the exact same arguments as "tx"
in Mojo::UserAgent::Transactor (except for the method). You can also
append a callback to perform requests non-blocking.
$ua->put('http://kraih.com' => sub {
my ($self, $tx) = @_;
print $tx->res->body;
Mojo::IOLoop->stop;
});
Mojo::IOLoop->start;
"start"
$ua = $ua->start($tx);
Process blocking transaction. You can also append a callback to
perform transactions non-blocking.
$ua->start($tx => sub {
my ($self, $tx) = @_;
print $tx->res->body;
Mojo::IOLoop->stop;
});
Mojo::IOLoop->start;
"test_server"
my $url = $ua->test_server;
my $url = $ua->test_server('http');
my $url = $ua->test_server('https');
Starts a test server for "app" if necessary and returns absolute
Mojo::URL object for it. Note that this method is EXPERIMENTAL and
might change without warning!
"websocket"
$ua->websocket('ws://localhost:3000' => sub {...});
Open a non-blocking WebSocket connection with transparent handshake,
takes the exact same arguments as "websocket" in
Mojo::UserAgent::Transactor.
$ua->websocket('ws://localhost:3000/echo' => sub {
my ($self, $tx) = @_;
$tx->on_finish(sub { Mojo::IOLoop->stop });
$tx->on_message(sub {
my ($tx, $message) = @_;
print "$message\n";
});
$tx->send_message('Hi!');
});
Mojo::IOLoop->start;
DEBUGGING
You can set the "MOJO_USERAGENT_DEBUG" environment variable to get some
advanced diagnostics information printed to "STDERR".
MOJO_USERAGENT_DEBUG=1
SEE ALSO
Mojolicious, Mojolicious::Guides, <http://mojolicio.us>.
perl v5.14.1 2011-09-13 Mojo::UserAgent(3)
