NAME
   HTTP::Tiny::Plugin - HTTP::Tiny with plugins

VERSION
   This document describes version 0.003 of HTTP::Tiny::Plugin (from Perl
   distribution HTTP-Tiny-Plugin), released on 2020-08-14.

SYNOPSIS
    # set plugins to use, globally
    use HTTP::Tiny::Plugin Retry=>{retries=>3, retry_delay=>2}, 'Cache';

    my $res;
    $res = HTTP::Tiny::Plugin->new->get("http://www.example.com/");       # will retry a few times if failed
    $res = HTTP::Tiny::Plugin->request(GET => "http://www.example.com/"); # will get cached response

    # to set plugins locally
    {
        my @old_plugins = HTTP::Tiny::Plugin->set_plugins(Retry=>{max_attempts=>3, delay=>2}, 'Cache');
        # do stuffs
        HTTP::Tiny::Plugin->set_plugins(@old_plugins);
    }

DESCRIPTION
   EARLY RELEASE, THINGS MIGHT STILL CHANGE A LOT.

   HTTP::Tiny::Plugin allows you to extend functionalities of HTTP::Tiny
   using plugins instead of subclassing. This makes it easy to combine
   several functionalities together. (Ironically, HTTP::Tiny::Plugin itself
   is a subclass of HTTP::Tiny, but the plugins need not be.)

 Plugins
   A plugin should be module named under "HTTP::Tiny::Plugin::", e.g.
   HTTP::Tiny::Plugin::Cache, HTTP::Tiny::Plugin::Log,
   HTTP::Tiny::Plugin::Some::Other::Name, etc.

   Plugins are used either via import arguments to HTTP::Tiny::Plugin:

    use HTTP::Tiny::Plugin Retry=>{retries=>3, retry_delay=>2}, 'Cache';

   or via calling "set_plugins".

 Hooks
   Plugin can define zero or more hooks (as methods with the same name as
   the hook) that will be executed during various stages.

 Hook arguments
   Hooks will be called with argument $r, a hash that contains various
   information. Keys that are common for all hooks:

   *   config

       Hash.

   *   http

       Object. The HTTP::Tiny object.

   *   ua

       Like "http".

   *   hook

       The current 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()".

   *   response

       Hash. The HTTP::Tiny response. Hooks can modify this.

 Hook return value
   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.

       Will also immediately stop hook execution for that stage.

 List of available hooks
   Below is the list of hooks in order of execution during a request:

   *   before_request_once

       Will be called before "request()" (and before "before_request"
       hook). All plugins will be called. Stage will interpret 99 (skip
       calling "request()"). When request is skipped, request() will return
       undef.

       When an "after_request" plugin returns 98 (repeat), this hook will
       not be repeated, but "before_request" hook will.

   *   before_request

       Will be called before "request()". All plugins will be called. Stage
       will interpret 99 (skip calling "request()", including skipping
       "after_request"). When request is skipped, request() will return
       undef.

       See also: "before_request_once".

   *   after_request

       Will be called after "request()". All plugins will be called. Stage
       will interpret 98 (repeat calling "request()", including the
       "before_request" hook but not the "before_request_once" hook).

METHODS
 set_plugins
   Usage:

    HTTP::Tiny::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
   "HTTP::Tiny::Plugin::" prefix. After each plugin name, an optional
   hashref can be specified to configure the plugin.

ENVIRONMENT
 HTTP_TINY_PLUGINS
   A JSON-encoded array. If set, will call "set_plugins" with the decoded
   value.

HOMEPAGE
   Please visit the project's homepage at
   <https://metacpan.org/release/HTTP-Tiny-Plugin>.

SOURCE
   Source repository is at
   <https://github.com/perlancar/perl-HTTP-Tiny-Plugin>.

BUGS
   Please report any bugs or feature requests on the bugtracker website
   <https://rt.cpan.org/Public/Dist/Display.html?Name=HTTP-Tiny-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.

SEE ALSO
   HTTP::Tiny

   LWP::UserAgent::Plugin

   HTTP::Tiny::Patch::Plugin

AUTHOR
   perlancar <[email protected]>

COPYRIGHT AND LICENSE
   This software is copyright (c) 2020, 2019 by [email protected].

   This is free software; you can redistribute it and/or modify it under
   the same terms as the Perl 5 programming language system itself.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.