view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

    Path and query to request.

- url :Str

    URL to request.

    You can use `url` instead of `scheme`, `host`, `port` and `path_query`.

- headers :ArrayRef

    HTTP request headers. e.g. `headers => [ 'Accept-Encoding' => 'gzip' ]`.

- content : Str | ArrayRef\[Str\] | HashRef\[Str\] | FileHandle

    Content to request.

If the number of arguments is an odd number, this method assumes that the
first argument is an instance of `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:

- uri
- method
- content
- headers

These must return the same type of values as their counterparts in
`HTTP::Request`.

You must encode all the queries or this method will die, saying
`Wide character in ...`.

### `$furl->get($url :Str, $headers :ArrayRef[Str] )`

This is an easy-to-use alias to `request()`, sending the `GET` method.

### `$furl->head($url :Str, $headers :ArrayRef[Str] )`

This is an easy-to-use alias to `request()`, sending the `HEAD` method.

### `$furl->post($url :Str, $headers :ArrayRef[Str], $content :Any)`

This is an easy-to-use alias to `request()`, sending the `POST` method.

### `$furl->put($url :Str, $headers :ArrayRef[Str], $content :Any)`

This is an easy-to-use alias to `request()`, sending the `PUT` method.

### `$furl->delete($url :Str, $headers :ArrayRef[Str] )`

This is an easy-to-use alias to `request()`, sending the `DELETE` method.

### `$furl->env_proxy()`

Loads proxy settings from `$ENV{HTTP_PROXY}` and `$ENV{NO_PROXY}`.

# TIPS

- [IO::Socket::SSL](https://metacpan.org/pod/IO%3A%3ASocket%3A%3ASSL) preloading

    Furl interprets the `timeout` argument as the maximum time the module is permitted to spend before returning an error.

    The module also lazy-loads [IO::Socket::SSL](https://metacpan.org/pod/IO%3A%3ASocket%3A%3ASSL) 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.

# FAQ

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

- I need more speed.

    See [Furl::HTTP](https://metacpan.org/pod/Furl%3A%3AHTTP), which provides the low level interface of [Furl](https://metacpan.org/pod/Furl).
    It is faster than `Furl.pm` since [Furl::HTTP](https://metacpan.org/pod/Furl%3A%3AHTTP) does not create response objects.

- How do you use cookie\_jar?

    Furl does not directly support the cookie\_jar option available in LWP. You can use [HTTP::Cookies](https://metacpan.org/pod/HTTP%3A%3ACookies), [HTTP::Request](https://metacpan.org/pod/HTTP%3A%3ARequest), [HTTP::Response](https://metacpan.org/po...

        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.

- 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;
            }
        );