Furl
view release on metacpan or search on metacpan
lib/Furl.pm view on Meta::CPAN
=back
If the number of arguments is an odd number, this method assumes that the
first argument is an instance of C<HTTP::Request>. Remaining arguments
can be any of the previously describe values (but currently there's no
way to really utilize them, so don't use it)
my $req = HTTP::Request->new(...);
my $res = $furl->request($req);
You can also specify an object other than HTTP::Request (e.g. Furl::Request),
but the object must implement the following methods:
=over 4
=item uri
=item method
=item content
=item headers
=back
These must return the same type of values as their counterparts in
C<HTTP::Request>.
You must encode all the queries or this method will die, saying
C<Wide character in ...>.
=head3 C<< $furl->get($url :Str, $headers :ArrayRef[Str] ) >>
This is an easy-to-use alias to C<request()>, sending the C<GET> method.
=head3 C<< $furl->head($url :Str, $headers :ArrayRef[Str] ) >>
This is an easy-to-use alias to C<request()>, sending the C<HEAD> method.
=head3 C<< $furl->post($url :Str, $headers :ArrayRef[Str], $content :Any) >>
This is an easy-to-use alias to C<request()>, sending the C<POST> method.
=head3 C<< $furl->put($url :Str, $headers :ArrayRef[Str], $content :Any) >>
This is an easy-to-use alias to C<request()>, sending the C<PUT> method.
=head3 C<< $furl->delete($url :Str, $headers :ArrayRef[Str] ) >>
This is an easy-to-use alias to C<request()>, sending the C<DELETE> method.
=head3 C<< $furl->env_proxy() >>
Loads proxy settings from C<< $ENV{HTTP_PROXY} >> and C<< $ENV{NO_PROXY} >>.
=head1 TIPS
=over 4
=item L<IO::Socket::SSL> preloading
Furl interprets the C<timeout> argument as the maximum time the module is permitted to spend before returning an error.
The module also lazy-loads L<IO::Socket::SSL> when an HTTPS request is being issued for the first time. Loading the module usually takes ~0.1 seconds.
The time spent for loading the SSL module may become an issue in case you want to impose a very small timeout value for connection establishment. In such case, users are advised to preload the SSL module explicitly.
=back
=head1 FAQ
=over 4
=item Does Furl depends on XS modules?
No. Although some optional features require XS modules, basic features are
available without XS modules.
Note that Furl requires HTTP::Parser::XS, which seems an XS module
but includes a pure Perl backend, HTTP::Parser::XS::PP.
=item I need more speed.
See L<Furl::HTTP>, which provides the low level interface of L<Furl>.
It is faster than C<Furl.pm> since L<Furl::HTTP> does not create response objects.
=item How do you use cookie_jar?
Furl does not directly support the cookie_jar option available in LWP. You can use L<HTTP::Cookies>, L<HTTP::Request>, L<HTTP::Response> like following.
my $f = Furl->new();
my $cookies = HTTP::Cookies->new();
my $req = HTTP::Request->new(...);
$cookies->add_cookie_header($req);
my $res = $f->request($req)->as_http_response;
$res->request($req);
$cookies->extract_cookies($res);
# and use $res.
=item How do you limit the response content length?
You can limit the content length by callback function.
my $f = Furl->new();
my $content = '';
my $limit = 1_000_000;
my %special_headers = ('content-length' => undef);
my $res = $f->request(
method => 'GET',
url => $url,
special_headers => \%special_headers,
write_code => sub {
my ( $status, $msg, $headers, $buf ) = @_;
if (($special_headers{'content-length'}||0) > $limit || length($content) > $limit) {
die "over limit: $limit";
}
$content .= $buf;
}
);
=item How do you display the progress bar?
my $bar = Term::ProgressBar->new({count => 1024, ETA => 'linear'});
$bar->minor(0);
$bar->max_update_rate(1);
my $f = Furl->new();
my $content = '';
my %special_headers = ('content-length' => undef);;
my $did_set_target = 0;
my $received_size = 0;
my $next_update = 0;
$f->request(
method => 'GET',
url => $url,
special_headers => \%special_headers,
write_code => sub {
my ( $status, $msg, $headers, $buf ) = @_;
unless ($did_set_target) {
if ( my $cl = $special_headers{'content-length'} ) {
$bar->target($cl);
$did_set_target++;
}
else {
$bar->target( $received_size + 2 * length($buf) );
}
}
$received_size += length($buf);
$content .= $buf;
$next_update = $bar->update($received_size)
if $received_size >= $next_update;
}
);
=item HTTPS requests claims warnings!
When you make https requests, IO::Socket::SSL may complain about it like:
*******************************************************************
Using the default of SSL_verify_mode of SSL_VERIFY_NONE for client
is depreciated! Please set SSL_verify_mode to SSL_VERIFY_PEER
together with SSL_ca_file|SSL_ca_path for verification.
If you really don't want to verify the certificate and keep the
connection open to Man-In-The-Middle attacks please set
SSL_verify_mode explicitly to SSL_VERIFY_NONE in your application.
*******************************************************************
You should set C<SSL_verify_mode> explicitly with Furl's C<ssl_opts>.
use IO::Socket::SSL;
my $ua = Furl->new(
ssl_opts => {
SSL_verify_mode => SSL_VERIFY_PEER(),
},
);
See L<IO::Socket::SSL> for details.
=back
=head1 AUTHOR
Tokuhiro Matsuno E<lt>tokuhirom@gmail.comE<gt>
Fuji, Goro (gfx)
=head1 THANKS TO
Kazuho Oku
mala
mattn
lestrrat
walf443
lestrrat
audreyt
=head1 SEE ALSO
L<LWP>
L<IO::Socket::SSL>
L<Furl::HTTP>
L<Furl::Response>
=head1 LICENSE
Copyright (C) Tokuhiro Matsuno.
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
=cut
( run in 1.794 second using v1.01-cache-2.11-cpan-39bf76dae61 )