LWP::UserAgent::Plugin - LWP::UserAgent with plugins
This document describes version 0.004 of LWP::UserAgent::Plugin (from Perl distribution LWP-UserAgent-Plugin), released on 2020-08-13.
# set plugins to use, globally use LWP::UserAgent::Plugin Retry=>{retries=>3, retry_delay=>2}, 'Cache'; my $ua = LWP::UserAgent::Plugin->new; my $res; $res = $ua->get("http://www.example.com/"); # will retry a few times if failed $res = $ua->get("http://www.example.com/"); # will get cached response # to set plugins locally { my @old_plugins = LWP::UserAgent::Plugin->set_plugins(Retry=>{max_attempts=>3, delay=>2}, 'Cache'); # do stuffs LWP::UserAgent::Plugin->set_plugins(@old_plugins); }
EARLY RELEASE, THINGS MIGHT STILL CHANGE A LOT.
Like HTTP::Tiny::Plugin, LWP::UserAgent::Plugin allows you to extend functionalities of LWP::UserAgent using plugins instead of subclassing. This makes it easy to combine several functionalities together. (Ironically, LWP::UserAgent::Plugin itself is a subclass of LWP::UserAgent, but the plugins need not be.)
A plugin should be module named under LWP::UserAgent::Plugin::, e.g. LWP::UserAgent::Plugin::Cache, LWP::UserAgent::Plugin::Some::Other::Name, etc.
LWP::UserAgent::Plugin::
Plugins are used either via import arguments to LWP::UserAgent::Plugin:
use LWP::UserAgent::Plugin Retry=>{retries=>3, retry_delay=>2}, 'Cache';
or via calling "set_plugins".
Plugin can define zero or more hooks (as methods with the same name as the hook) that will be executed during various stages.
Hooks will be called with argument $r, a hash that contains various information. Keys that are common for all hooks:
$r
method
The related LWP::UserAgent method. For example, in before_request and after_request hook, the value is request.
before_request
after_request
request
config
Hash.
ua
Object. The LWP::UserAgent object.
hook
The current hook name.
The hook name.
argv
Array. Arguments passed to hook-related method. For example, for "before_request" and "after_request" hooks, argv will contain arguments (@_) passed to request().
@_
request()
response
Object. The HTTP::Response object. Hooks can modify this.
Hooks can return an integer, which can be used to signal declination/success/failure as well as flow control. The following values are possible:
-1
Declare decline (i.e. try next hook).
Declare failure status (for the stage). For a stage that only wants a single plugin to respond, this will stop hook execution for that stage and the next plugin in line will not be called. For a stage that wants to execute all plugins, this will still continue to the next plugin. The status of the stage is from the status of the plugin called last.
1
Declare success/OK status (for the stage). For a stage that only wants a single plugin to respond, this will stop hook execution for that stage and the next plugin in line will not be called. For a stage that wants to execute all plugins, this will still continue to the next plugin. The status of the stage is from the status of the plugin called last.
99
Skip execution of hook-related method. For example, if we return 99 in "before_request" then request() will be skipped.
Will also immediately stop hook execution for that stage.
98
Repeat execution of hook-related method. For example, if we return 98 in "after_request" then request() will be repeated.
Below is the list of hooks in order of execution during a request:
Will be called before request(). All plugins will be called. Stage will interpret 99 (skip calling request()).
Will be called before request(). All plugins will be called. Stage will interpret 98 (repeat calling request()).
before_mirror
Will be called before mirror(). All plugins will be called. Stage will interpret 99 (skip calling mirror()).
mirror()
after_mirror
Will be called before request(). All plugins will be called. Stage will interpret 98 (repeat calling mirror()).
Usage:
LWP::UserAgent::Plugin->set_plugins('Plugin1', 'Plugin2'=>{arg=>val, ...}, ...);
Class method. Set plugins to use (and replace the previous set of plugins used). Will return a list containing previous set of plugins.
Argument is a list of plugin names, with/without the LWP::UserAgent::Plugin:: prefix. After each plugin name, an optional hashref can be specified to configure the plugin.
Bool. If set to true, will produce more trace log statements.
A JSON-encoded array. If set, will call "set_plugins" with the decoded value.
Please visit the project's homepage at https://metacpan.org/release/LWP-UserAgent-Plugin.
Source repository is at https://github.com/perlancar/perl-LWP-UserAgent-Plugin.
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=LWP-UserAgent-Plugin
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
LWP::UserAgent
HTTP::Tiny::Plugin
LWP::UserAgent::Patch::Plugin
perlancar <perlancar@cpan.org>
This software is copyright (c) 2020, 2019 by perlancar@cpan.org.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install LWP::UserAgent::Plugin, copy and paste the appropriate command in to your terminal.
cpanm
cpanm LWP::UserAgent::Plugin
CPAN shell
perl -MCPAN -e shell install LWP::UserAgent::Plugin
For more information on module installation, please visit the detailed CPAN module installation guide.