1BZ::Client(3)         User Contributed Perl Documentation        BZ::Client(3)
2
3
4

NAME

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

VERSION

9       version 4.4002
10

SYNOPSIS

12         my $client = BZ::Client->new( url       => $url,
13                                       user      => $user,
14                                       password  => $password,
15                                       autologin => 0 );
16         $client->login();
17

BUGZILLA VERSIONS

19       Please note that this BZ::Client module is aimed at the XMLRPC API
20       available in Bugzilla 5.0 and earlier.
21
22       For 5.1 and later, which have a totally different REST API, please see
23       Net::Bugzilla.
24
25       As such, I welcome all patches (via pull request) for functionality
26       relating to 5.0 and earlier.
27
28       I will only actively hunt down bugs relating to the 'maintained'
29       Bugzilla server softwares. Please upgrade your server and duplicate the
30       problem, or see the above commitment to accept patches to fix for older
31       versions.
32

CLASS METHODS

34       This section lists the class methods of BZ::Client.
35
36   new
37         my $client = BZ::Client->new( url      => $url,
38                                       user     => $user,
39                                       password => $password );
40
41         my $client = BZ::Client->new( url      => $url,
42                                       api_key  => $api_key );
43
44       The new method constructs a new instance of BZ::Client. Whenever you
45       want to connect to the Bugzilla server, you must first create a
46       Bugzilla client. The methods input is a hash of parameters.
47
48       For debugging, you can pass in a subref named "logger" which will be
49       fed debugging information as the client works. Also the "logDirectory"
50       option is a directory where the raw http content will be dumped.
51
52       Parameters
53
54       url The Bugzilla servers URL, for example
55           "https://bugzilla.mozilla.org/".
56
57       api_key
58           API keys were introduced in 5.0.
59
60           An API Key can be obtained in the web interface of your Bugzilla
61           server, with the following steps:
62
63           1. Click 'Preferences' link
64           2. Click 'API Keys' tab
65           3. Click the checkbox next to 'Generate a new API key...'
66           4. If you like, add some description in the textbox
67           5. Click the 'Submit Changes' button
68           6. Key appears in the table under the 'Existing API keys'
69           subheading
70       user
71           The user name to use when logging in to the Bugzilla server.
72           Typically, this will be your email address.
73
74       password
75           The password to use when logging in to the Bugzilla server.
76
77       autologin
78           If set to 1 (true), will try to log in (if not already logged in)
79           when the first API call is made. This is default.
80
81           If set to 0, will try APi calls without logging in. You can still
82           call $client->login() to log in manually.
83
84           Note: once you're logged in, you'll stay that way until you call
85           "logout"
86
87       restrictlogin
88           If set to 1 (true), will ask Bugzilla to restrict logins to your IP
89           only.  Generally this is a good idea, but may caused problems if
90           you are using a loadbalanced forward proxy.
91
92           Default: 0
93
94       connect
95           A hashref with options for HTTP::Tiny, this is passed through so
96           the bellow are for reference only:
97
98           http_proxy, https_proxy, proxy
99               Nominates a proxy for HTTP, HTTPS or both, respectively.
100
101               You might also use $ENV{all_proxy}, $ENV{http_proxy},
102               $ENV{https_proxy} or $ENV{all_proxy}.
103
104           timeout
105               Request timeout in seconds (default is 60)
106
107           verify_SSL
108               A boolean that indicates whether to validate the SSL
109               certificate of an "https" connection (default is false)
110
111       Connect Via Socks Proxy
112
113       Try something like:
114
115        use HTTP::Tiny; # load this manually
116        use IO::Socket::Socks::Wrapper (
117         'HTTP::Tiny::Handle::connect()' => {
118           ProxyAddr    => 'localhost',
119           ProxyPort    => 1080,
120           SocksVersion => 4,
121           Timeout      => 15
122           }
123         );
124         use BZ::Client ...etc
125

INSTANCE METHODS

127       This section lists the methods, which an instance of BZ::Client can
128       perform.
129
130   url
131        $url = $client->url();
132        $client->url( $url );
133
134       Returns or sets the Bugzilla servers URL.
135
136   user
137        $user = $client->user();
138        $client->user( $user );
139
140       Returns or sets the user name to use when logging in to the Bugzilla
141       server. Typically, this will be your email address.
142
143   password
144        $password = $client->password();
145        $client->password( $password );
146
147       Returns or sets the password to use when logging in to the Bugzilla
148       server.
149
150   autologin
151       If login is automatically called, or not.
152
153   login
154       Used to login to the Bugzilla server. By default, there is no need to
155       call this method explicitly: It is done automatically, whenever
156       required.
157
158       If autologin is set to 0, call this to log in.
159
160   is_logged_in
161       Returns 1 if logged in, otherwise 0.
162
163   logout
164       Deletes local cookies and calls Bugzilla's logout function
165
166   logger
167       Sets or gets the logging function. Argument is a coderef. Returns
168       "undef" if none.
169
170        $logger = $client->logger();
171
172        $client->logger(
173            sub {
174                my ($level, $msg) = @_;
175                print STDERR "$level $message\n";
176                return 1
177            });
178
179       Also can be set via "new", e.g.
180
181        $client = BZ::Client->new( logger => sub { },
182                                   url    => $url
183                                   user   => $user,
184                                   password => $password );
185
186   log
187        $client->log( $level, $message );
188
189       Sends log messages to whatever is loaded via "logger".
190
191   api_call
192        $response = $client->api_call( $methodName, $params, $options );
193
194       Used by subclasses of BZ::Client::API to invoke methods of the Bugzilla
195       API. The method name and the hash ref of parameters are sent to the
196       Bugzilla server.  The options hash ref adjusts the behaviour of this
197       function when calls are made.
198
199       The params and options hash refs are optional, although certain param
200       values may be required depending on the method name being called. This
201       client library relies upon the Bugzilla server to enforce any method
202       parameter requirements, so insufficient requests will still be sent to
203       the server for it to then reject them.
204
205       Returns a hash ref of named result objects.
206
207       Options
208
209       empty_response_ok
210           With this set, an empty response is not considered an error. In
211           this case, api_call returns 1 to indicate success.
212
213       cookies
214           This is used internally to set cookies with the log in functions.
215           Don't touch this.
216

EXCEPTION HANDLING

218       See BZ::Client::Exception
219

ERROR CODES

221   300 (Invalid Username or Password)
222       The username does not exist, or the password is wrong.
223
224   301 (Login Disabled)
225       The ability to login with this account has been disabled. A reason may
226       be specified with the error.
227
228   305 (New Password Required)
229       The current password is correct, but the user is asked to change his
230       password.
231
232   50 (Param Required)
233       A login or password parameter was not provided.
234

TESTING

236       Bugzilla maintains demos of all supported versions and trunk at
237       <https://landfill.bugzilla.org>
238
239       You might consider using that for testing against live versions.
240

SEE ALSO

242       BZ::Client::Exception
243

AUTHORS

245       ·   Dean Hamstead <dean@bytefoundry.com.au>
246
247       ·   Jochen Wiedmann <jochen.wiedmann@gmail.com>
248
250       This software is copyright (c) 2017 by Dean Hamstad.
251
252       This is free software; you can redistribute it and/or modify it under
253       the same terms as the Perl 5 programming language system itself.
254
255
256
257perl v5.30.1                      2020-01-29                     BZ::Client(3)
Impressum