View on
MetaCPAN
Dean Hamstead > BZ-Client-4.4002 > BZ::Client

Download:
BZ-Client-4.4002.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

Open  0
View/Report Bugs
Module Version: 4.4002   Source  

NAME ^

BZ::Client - A client for the Bugzilla web services API.

VERSION ^

version 4.4002

SYNOPSIS ^

  my $client = BZ::Client->new( url       => $url,
                                user      => $user,
                                password  => $password,
                                autologin => 0 );
  $client->login();

BUGZILLA VERSIONS ^

Please note that this BZ::Client module is aimed at the XMLRPC API available in Bugzilla 5.0 and earlier.

For 5.1 and later, which have a totally different REST API, please see Net::Bugzilla.

As such, I welcome all patches (via pull request) for functionality relating to 5.0 and earlier.

I will only actively hunt down bugs relating to the 'maintained' Bugzilla server softwares. Please upgrade your server and duplicate the problem, or see the above commitment to accept patches to fix for older versions.

CLASS METHODS ^

This section lists the class methods of BZ::Client.

new

  my $client = BZ::Client->new( url      => $url,
                                user     => $user,
                                password => $password );

  my $client = BZ::Client->new( url      => $url,
                                api_key  => $api_key );

The new method constructs a new instance of BZ::Client. Whenever you want to connect to the Bugzilla server, you must first create a Bugzilla client. The methods input is a hash of parameters.

For debugging, you can pass in a subref named logger which will be fed debugging information as the client works. Also the logDirectory option is a directory where the raw http content will be dumped.

Parameters

url

The Bugzilla servers URL, for example https://bugzilla.mozilla.org/.

api_key

API keys were introduced in 5.0.

An API Key can be obtained in the web interface of your Bugzilla server, with the following steps:

1. Click 'Preferences' link
2. Click 'API Keys' tab
3. Click the checkbox next to 'Generate a new API key...'
4. If you like, add some description in the textbox
5. Click the 'Submit Changes' button
6. Key appears in the table under the 'Existing API keys' subheading
user

The user name to use when logging in to the Bugzilla server. Typically, this will be your email address.

password

The password to use when logging in to the Bugzilla server.

autologin

If set to 1 (true), will try to log in (if not already logged in) when the first API call is made. This is default.

If set to 0, will try APi calls without logging in. You can still call $client->login() to log in manually.

Note: once you're logged in, you'll stay that way until you call "logout"

restrictlogin

If set to 1 (true), will ask Bugzilla to restrict logins to your IP only. Generally this is a good idea, but may caused problems if you are using a loadbalanced forward proxy.

Default: 0

connect

A hashref with options for HTTP::Tiny, this is passed through so the bellow are for reference only:

http_proxy, https_proxy, proxy

Nominates a proxy for HTTP, HTTPS or both, respectively.

You might also use $ENV{all_proxy}, $ENV{http_proxy}, $ENV{https_proxy} or $ENV{all_proxy}.

timeout

Request timeout in seconds (default is 60)

verify_SSL

A boolean that indicates whether to validate the SSL certificate of an "https" connection (default is false)

Connect Via Socks Proxy

Try something like:

 use HTTP::Tiny; # load this manually
 use IO::Socket::Socks::Wrapper (
  'HTTP::Tiny::Handle::connect()' => {
    ProxyAddr    => 'localhost',
    ProxyPort    => 1080,
    SocksVersion => 4,
    Timeout      => 15
    }
  );
  use BZ::Client ...etc

INSTANCE METHODS ^

This section lists the methods, which an instance of BZ::Client can perform.

url

 $url = $client->url();
 $client->url( $url );

Returns or sets the Bugzilla servers URL.

user

 $user = $client->user();
 $client->user( $user );

Returns or sets the user name to use when logging in to the Bugzilla server. Typically, this will be your email address.

password

 $password = $client->password();
 $client->password( $password );

Returns or sets the password to use when logging in to the Bugzilla server.

autologin

If login is automatically called, or not.

login

Used to login to the Bugzilla server. By default, there is no need to call this method explicitly: It is done automatically, whenever required.

If autologin is set to 0, call this to log in.

is_logged_in

Returns 1 if logged in, otherwise 0.

logout

Deletes local cookies and calls Bugzilla's logout function

logger

Sets or gets the logging function. Argument is a coderef. Returns undef if none.

 $logger = $client->logger();

 $client->logger(
     sub {
         my ($level, $msg) = @_;
         print STDERR "$level $message\n";
         return 1
     });

Also can be set via "new", e.g.

 $client = BZ::Client->new( logger => sub { },
                            url    => $url
                            user   => $user,
                            password => $password );

log

 $client->log( $level, $message );

Sends log messages to whatever is loaded via "logger".

api_call

 $response = $client->api_call( $methodName, $params, $options );

Used by subclasses of BZ::Client::API to invoke methods of the Bugzilla API. The method name and the hash ref of parameters are sent to the Bugzilla server. The options hash ref adjusts the behaviour of this function when calls are made.

The params and options hash refs are optional, although certain param values may be required depending on the method name being called. This client library relies upon the Bugzilla server to enforce any method parameter requirements, so insufficient requests will still be sent to the server for it to then reject them.

Returns a hash ref of named result objects.

Options

empty_response_ok

With this set, an empty response is not considered an error. In this case, api_call returns 1 to indicate success.

cookies

This is used internally to set cookies with the log in functions. Don't touch this.

EXCEPTION HANDLING ^

See BZ::Client::Exception

ERROR CODES ^

300 (Invalid Username or Password)

The username does not exist, or the password is wrong.

301 (Login Disabled)

The ability to login with this account has been disabled. A reason may be specified with the error.

305 (New Password Required)

The current password is correct, but the user is asked to change his password.

50 (Param Required)

A login or password parameter was not provided.

TESTING ^

Bugzilla maintains demos of all supported versions and trunk at https://landfill.bugzilla.org

You might consider using that for testing against live versions.

SEE ALSO ^

BZ::Client::Exception

AUTHORS ^

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2017 by Dean Hamstad.

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

syntax highlighting: