index : forums	master
	The forums.mageia.org Website	Maat [maat]

aboutsummaryrefslogtreecommitdiffstats

log msg author committer range

path: root/phpBB/index.php

blob: c67fe95514638da136661e4b6919efbb0dbdebc2 (plain)

<?php /*************************************************************************** * index.php * ------------------- * begin : Saturday, Feb 13, 2001 * copyright : (C) 2001 The phpBB Group * email : support@phpbb.com * * $Id$ * * ***************************************************************************/ /*************************************************************************** * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * ***************************************************************************/ $phpbb_root_path = "./"; include($phpbb_root_path . 'extension.inc'); include($phpbb_root_path . 'common.'.$phpEx); // // Start session management // $userdata = session_pagestart($user_ip, PAGE_INDEX, $session_length); init_userprefs($userdata); // // End session management // $viewcat = (!empty($HTTP_GET_VARS['viewcat'])) ? $HTTP_GET_VARS['viewcat'] : -1; if( isset($HTTP_GET_VARS['mark']) || isset($HTTP_POST_VARS['mark']) ) { $mark_read = ( isset($HTTP_POST_VARS['mark']) ) ? $HTTP_POST_VARS['mark'] : $HTTP_GET_VARS['mark']; } else { $mark_read = ""; } // // Handle marking posts // if( $mark_read == "forums" ) { $sql = "SELECT f.forum_id, t.topic_id FROM " . FORUMS_TABLE . " f, " . TOPICS_TABLE . " t, " . POSTS_TABLE . " p WHERE t.forum_id = f.forum_id AND p.post_id = t.topic_last_post_id AND p.post_time > " . $userdata['session_last_visit'] . " AND t.topic_moved_id = NULL"; if(!$t_result = $db->sql_query($sql)) { message_die(GENERAL_ERROR, "Could not query new topic information", "", __LINE__, __FILE__, $sql); } if( $mark_read_rows = $db->sql_numrows($t_result) ) { $mark_read_list = $db->sql_fetchrowset($t_result); for($i = 0; $i < $mark_read_rows; $i++ ) { $forum_id = $mark_read_list[$i]['forum_id']; $topic_id = $mark_read_list[$i]['topic_id']; if( empty($HTTP_COOKIE_VARS['phpbb2_' . $forum_id . '_' . $topic_id]) ) { setcookie('phpbb2_' . $forum_id . '_' . $topic_id, time(), 0, $board_config['cookie_path'], $board_config['cookie_domain'], $board_config['cookie_secure']); } else { if( isset($HTTP_COOKIE_VARS['phpbb2_' . $forum_id . '_' . $topic_id]) ) { setcookie('phpbb2_' . $forum_id . '_' . $topic_id, time(), 0, $board_config['cookie_path'], $board_config['cookie_domain'], $board_config['cookie_secure']); } } } } $template->assign_vars(array( "META" => '<meta http-equiv="refresh" content="3;url=index.' . $phpEx . '">') ); $message = $lang['Forums_marked_read'] . "<br /><br />" . $lang['Click'] . " <a href=\"index.$phpEx\">" . $lang['HERE'] . "</a> " . $lang['to_return_index']; message_die(GENERAL_MESSAGE, $message); } // // End handle marking posts // // // If you don't use these stats on your index // you may want to consider removing them since // it will reduce the number of queries speeding // up page generation a little // $total_posts = get_db_stat('postcount'); $total_users = get_db_stat('usercount'); $total_topics = get_db_stat('topiccount'); $newest_userdata = get_db_stat('newestuser'); $newest_user = $newest_userdata['username']; $newest_uid = $newest_userdata['user_id']; // // Start page proper // $sql = "SELECT c.cat_id, c.cat_title, c.cat_order FROM " . CATEGORIES_TABLE . " c, " . FORUMS_TABLE . " f WHERE f.cat_id = c.cat_id GROUP BY c.cat_id, c.cat_title, c.cat_order ORDER BY c.cat_order"; if(!$q_categories = $db->sql_query($sql)) { message_die(GENERAL_ERROR, "Could not query categories list", "", __LINE__, __FILE__, $sql); } if($total_categories = $db->sql_numrows($q_categories)) { $category_rows = $db->sql_fetchrowset($q_categories); $limit_forums = ""; // // Define appropriate SQL // switch(SQL_LAYER) { case 'postgresql': $limit_forums = ($viewcat != -1) ? "AND f.cat_id = $viewcat " : ""; $sql = "SELECT f.*, p.post_time, u.username, u.user_id FROM " . FORUMS_TABLE . " f, " . POSTS_TABLE . " p, " . USERS_TABLE . " u WHERE p.post_id = f.forum_last_post_id AND u.user_id = p.poster_id $limit_forums UNION ( SELECT f.*, NULL, NULL, NULL FROM " . FORUMS_TABLE . " f WHERE NOT EXISTS ( SELECT p.post_time FROM " . POSTS_TABLE . " p WHERE p.post_id = f.forum_last_post_id ) $limit_forums )"; break; case 'oracle': $limit_forums = ($viewcat != -1) ? "AND f.cat_id = $viewcat " : ""; $sql = "SELECT f.*, p.post_time, u.username, u.user_id FROM " . FORUMS_TABLE . " f, " . POSTS_TABLE . " p, " . USERS_TABLE . " u WHERE p.post_id = f.forum_last_post_id(+) AND u.user_id = p.poster_id(+) $limit_forums ORDER BY f.cat_id, f.forum_order"; break; default: $limit_forums = ($viewcat != -1) ? "WHERE f.cat_id = $viewcat " : ""; $sql = "SELECT f.*, p.post_time, u.username, u.user_id FROM (( " . FORUMS_TABLE . " f LEFT JOIN " . POSTS_TABLE . " p ON p.post_id = f.forum_last_post_id ) LEFT JOIN " . USERS_TABLE . " u ON u.user_id = p.poster_id ) $limit_forums ORDER BY f.cat_id, f.forum_order"; break; } if(!$q_forums = $db->sql_query($sql)) { message_die(GENERAL_ERROR, "Could not query forums information", "", __LINE__, __FILE__, $sql); } if( !$total_forums = $db->sql_numrows($q_forums) ) { message_die(GENERAL_MESSAGE, $lang['No_forums']); } $forum_rows = $db->sql_fetchrowset($q_forums); $sql = "SELECT f.forum_id, t.topic_id, p.post_time FROM " . FORUMS_TABLE . " f, " . TOPICS_TABLE . " t, " . POSTS_TABLE . " p WHERE t.forum_id = f.forum_id AND p.post_id = t.topic_last_post_id AND p.post_time > " . $userdata['session_last_visit'] . " AND t.topic_moved_id IS NULL"; if(!$new_topic_ids = $db->sql_query($sql)) { message_die(GENERAL_ERROR, "Could not query new topic information", "", __LINE__, __FILE__, $sql); } while( $topic_data = $db->sql_fetchrow($new_topic_ids) ) { $new_topic_data[$topic_data['forum_id']][$topic_data['topic_id']] = $topic_data['post_time']; } // // Obtain list of moderators of each forum // $sql = "SELECT aa.forum_id, g.group_name, g.group_id, g.group_single_user, u.user_id, u.username FROM " . AUTH_ACCESS_TABLE . " aa, " . USER_GROUP_TABLE . " ug, " . GROUPS_TABLE . " g, " . USERS_TABLE . " u WHERE aa.auth_mod = " . TRUE . " AND ug.group_id = aa.group_id AND g.group_id = aa.group_id AND u.user_id = ug.user_id ORDER BY aa.forum_id, g.group_id, u.user_id"; if(!$q_forum_mods = $db->sql_query($sql)) { message_die(GENERAL_ERROR, "Could not query forum moderator information", "", __LINE__, __FILE__, $sql); } $forum_mods_list = $db->sql_fetchrowset($q_forum_mods); for($i = 0; $i < count($forum_mods_list); $i++) { if($forum_mods_list[$i]['group_single_user'] || !$forum_mods_list[$i]['group_id']) { $forum_mods_single_user[$forum_mods_list[$i]['forum_id']][] = 1; $forum_mods_name[$forum_mods_list[$i]['forum_id']][] = $forum_mods_list[$i]['username']; $forum_mods_id[$forum_mods_list[$i]['forum_id']][] = $forum_mods_list[$i]['user_id']; } else { $forum_mods_single_user[$forum_mods_list[$i]['forum_id']][] = 0; $forum_mods_name[$forum_mods_list[$i]['forum_id']][] = $forum_mods_list[$i]['group_name']; $forum_mods_id[$forum_mods_list[$i]['forum_id']][] = $forum_mods_list[$i]['group_id']; } } // // Find which forums are visible for this user // $is_auth_ary = auth(AUTH_VIEW, AUTH_LIST_ALL, $userdata, $forum_rows); $template->set_filenames(array( "body" => "index_body.tpl") ); $template->assign_vars(array( "TOTAL_POSTS" => $total_posts, "TOTAL_USERS" => $total_users, "TOTAL_TOPICS" => $total_topics, "NEWEST_USER" => $newest_user, "NEWEST_UID" => $newest_uid, "USERS_BROWSING" => $users_browsing, "L_FORUM_LOCKED" => $lang['Forum_is_locked'], "L_MARK_FORUMS_READ" => $lang['Mark_all_forums'], "L_SEARCH_NEW" => $lang['Search_new'], "U_SEARCH_NEW" => append_sid("search.$phpEx?search_id=newposts"), "U_MARK_READ" => append_sid("index.$phpEx?mark=forums"), "U_NEWEST_USER_PROFILE" => append_sid("profile.$phpEx?mode=viewprofile&amp;" . POST_USERS_URL . "=$newest_uid")) ); // // Okay, let's build the index // $gen_cat = array(); for($i = 0; $i < $total_categories; $i++) { $cat_id = $category_rows[$i]['cat_id']; $count = 0; for($j = 0; $j < $total_forums; $j++) { $forum_id = $forum_rows[$j]['forum_id']; if( $is_auth_ary[$forum_id]['auth_view'] && ( ($forum_rows[$j]['cat_id'] == $cat_id && $viewcat == -1) || $cat_id == $viewcat) ) { if(!$gen_cat[$cat_id]) { $template->assign_block_vars("catrow", array( "CAT_ID" => $cat_id, "CAT_DESC" => $category_rows[$i]['cat_title'], "U_VIEWCAT" => append_sid("index.$phpEx?viewcat=$cat_id")) ); $gen_cat[$cat_id] = 1; } if($forum_rows[$j]['forum_status'] == FORUM_LOCKED) { $folder_image = "<img src=\"" . $images['forum_locked'] . "\" alt=\"" . $lang['Forum_locked'] . "\" />"; } else { $unread_topics = false; if( count($new_topic_data[$forum_id]) ) { while( list($check_topic_id, $check_post_time) = each($new_topic_data[$forum_id]) ) { if( !isset($HTTP_COOKIE_VARS['phpbb2_' . $forum_id . '_' . $check_topic_id]) ) { $unread_topics = true; } else { if($HTTP_COOKIE_VARS['phpbb2_' . $forum_id . '_' . $check_topic_id] < $check_post_time ) { $unread_topics = true; } } } } $folder_image = ( $unread_topics ) ? "<img src=\"" . $images['forum_new'] . "\" alt=\"" . $lang['New_posts'] . "\" />" : "<img src=\"" . $images['forum'] . "\" alt=\"" . $lang['No_new_posts'] . "\" />"; } $posts = $forum_rows[$j]['forum_posts']; $topics = $forum_rows[$j]['forum_topics']; if($forum_rows[$j]['username'] != "" && $forum_rows[$j]['post_time'] > 0) { $last_post_time = create_date($board_config['default_dateformat'], $forum_rows[$j]['post_time'], $board_config['board_timezone']); $last_post = $last_post_time . "<br />" . $lang['by'] . " "; $last_post .= ( $forum_rows[$j]['user_id'] == ANONYMOUS ) ? $forum_rows[$j]['username'] . " " : "<a href=\"" . append_sid("profile.$phpEx?mode=viewprofile&amp;" . POST_USERS_URL . "=" . $forum_rows[$j]['user_id']) . "\">" . $forum_rows[$j]['username'] . "</a> "; $last_post .= "<a href=\"" . append_sid("viewtopic.$phpEx?" . POST_POST_URL . "=" . $forum_rows[$j]['forum_last_post_id']) . "#" . $forum_rows[$j]['forum_last_post_id'] . "\"><img src=\"" . $images['icon_latest_reply'] . "\" border=\"0\" alt=\"" . $lang['View_latest_post'] . "\" /></a>"; } else { $last_post = $lang['No_Posts']; } $mod_count = 0; $moderators_links = ""; for($mods = 0; $mods < count($forum_mods_name[$forum_id]); $mods++) { if( !strstr($moderators_links, $forum_mods_name[$forum_id][$mods]) ) { if($mods > 0) { $moderators_links .= ", "; } if( !($mod_count % 2) && $mod_count != 0 ) { $moderators_links .= "<br />"; } if( $forum_mods_single_user[$forum_id][$mods]) { $moderators_links .= "<a href=\"" . append_sid("profile.$phpEx?mode=viewprofile&amp;" . POST_USERS_URL . "=" . $forum_mods_id[$forum_id][$mods]) . "\">" . $forum_mods_name[$forum_id][$mods] . "</a>"; } else { $moderators_links .= "<a href=\"" . append_sid("groupcp.$phpEx?" . POST_GROUPS_URL . "=" . $forum_mods_id[$forum_id][$mods]) . "\">" . $forum_mods_name[$forum_id][$mods] . "</a>"; } $mod_count++; } } if($moderators_links == "") { $moderators_links = "&nbsp;"; } $row_color = ( !($count%2) ) ? $theme['td_color1'] : $theme['td_color2']; $row_class = ( !($count%2) ) ? $theme['td_class1'] : $theme['td_class2']; $template->assign_block_vars("catrow.forumrow", array( "ROW_COLOR" => "#" . $row_color, "ROW_CLASS" => $row_class, "FOLDER" => $folder_image, "FORUM_NAME" => $forum_rows[$j]['forum_name'], "FORUM_DESC" => $forum_rows[$j]['forum_desc'], "POSTS" => $forum_rows[$j]['forum_posts'], "TOPICS" => $forum_rows[$j]['forum_topics'], "LAST_POST" => $last_post, "MODERATORS" => $moderators_links, "U_VIEWFORUM" => append_sid("viewforum.$phpEx?" . POST_FORUM_URL . "=$forum_id")) ); $count++; } else if($viewcat != -1) { if(!$gen_cat[$cat_id]) { $template->assign_block_vars("catrow", array( "CAT_ID" => $cat_id, "CAT_DESC" => $category_rows[$i]['cat_title'], "U_VIEWCAT" => append_sid("index.$phpEx?viewcat=$cat_id")) ); $gen_cat[$cat_id] = 1; } } } } // for ... categories }// if ... total_categories else { message_die(GENERAL_MESSAGE, $lang['No_forums']); } // // Output page header and open the index body template // we do this here because of the mark topics read cookie // code // $page_title = $lang['Forum_Index']; include($phpbb_root_path . 'includes/page_header.'.$phpEx); // // Generate the page // $template->pparse("body"); include($phpbb_root_path . 'includes/page_tail.'.$phpEx); ?>

generated by cgit v1.2.1 (git 2.21.0) at 2025-12-27 13:43:10 +0000

# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at http://mozilla.org/MPL/2.0/.
#
# This Source Code Form is "Incompatible With Secondary Licenses", as
# defined by the Mozilla Public License, v. 2.0.

package Bugzilla::WebService::Bug;

use 5.10.1;
use strict;
use warnings;

use parent qw(Bugzilla::WebService);

use Bugzilla::Comment;
use Bugzilla::Comment::TagWeights;
use Bugzilla::Constants;
use Bugzilla::Error;
use Bugzilla::Field;
use Bugzilla::WebService::Constants;
use Bugzilla::WebService::Util qw(extract_flags filter filter_wants validate translate);
use Bugzilla::Bug;
use Bugzilla::BugMail;
use Bugzilla::Util qw(trick_taint trim diff_arrays detaint_natural);
use Bugzilla::Version;
use Bugzilla::Milestone;
use Bugzilla::Status;
use Bugzilla::Token qw(issue_hash_token);
use Bugzilla::Search;
use Bugzilla::Product;
use Bugzilla::FlagType;
use Bugzilla::Search::Quicksearch;

use List::Util qw(max);
use List::MoreUtils qw(uniq);
use Storable qw(dclone);

#############
# Constants #
#############

use constant PRODUCT_SPECIFIC_FIELDS => qw(version target_milestone component);

use constant DATE_FIELDS => {
    comments => ['new_since'],
    history  => ['new_since'],
    search   => ['last_change_time', 'creation_time'],
};

use constant BASE64_FIELDS => {
    add_attachment => ['data'],
};

use constant READ_ONLY => qw(
    attachments
    comments
    fields
    get
    history
    legal_values
    search
);

use constant PUBLIC_METHODS => qw(
    add_attachment
    add_comment
    attachments
    comments
    create
    fields
    get
    history
    legal_values
    possible_duplicates
    render_comment
    search
    search_comment_tags
    update
    update_attachment
    update_comment_tags
    update_see_also
    update_tags
);

use constant ATTACHMENT_MAPPED_SETTERS => {
    file_name => 'filename',
    summary   => 'description',
};

use constant ATTACHMENT_MAPPED_RETURNS => {
    description => 'summary',
    ispatch     => 'is_patch',
    isprivate   => 'is_private',
    isobsolete  => 'is_obsolete',
    filename    => 'file_name',
    mimetype    => 'content_type',
};

###########
# Methods #
###########

sub fields {
    my ($self, $params) = validate(@_, 'ids', 'names');

    Bugzilla->switch_to_shadow_db();

    my @fields;
    if (defined $params->{ids}) {
        my $ids = $params->{ids};
        foreach my $id (@$ids) {
            my $loop_field = Bugzilla::Field->check({ id => $id });
            push(@fields, $loop_field);
        }
    }

    if (defined $params->{names}) {
        my $names = $params->{names};
        foreach my $field_name (@$names) {
            my $loop_field = Bugzilla::Field->check($field_name);
            # Don't push in duplicate fields if we also asked for this field
            # in "ids".
            if (!grep($_->id == $loop_field->id, @fields)) {
                push(@fields, $loop_field);
            }
        }
    }

    if (!defined $params->{ids} and !defined $params->{names}) {
        @fields = @{ Bugzilla->fields({ obsolete => 0 }) };
    }

    my @fields_out;
    foreach my $field (@fields) {
        my $visibility_field = $field->visibility_field
                               ? $field->visibility_field->name : undef;
        my $vis_values = $field->visibility_values;
        my $value_field = $field->value_field
                          ? $field->value_field->name : undef;

        my (@values, $has_values);
        if ( ($field->is_select and $field->name ne 'product')
             or grep($_ eq $field->name, PRODUCT_SPECIFIC_FIELDS)
             or $field->name eq 'keywords')
        {
             $has_values = 1;
             @values = @{ $self->_legal_field_values({ field => $field }) };
        } 

        if (grep($_ eq $field->name, PRODUCT_SPECIFIC_FIELDS)) {
             $value_field = 'product';
        }

        my %field_data = (
           id                => $self->type('int', $field->id),
           type              => $self->type('int', $field->type),
           is_custom         => $self->type('boolean', $field->custom),
           name              => $self->type('string', $field->name),
           display_name      => $self->type('string', $field->description),
           is_mandatory      => $self->type('boolean', $field->is_mandatory),
           is_on_bug_entry   => $self->type('boolean', $field->enter_bug),
           visibility_field  => $self->type('string', $visibility_field),
           visibility_values =>
              [ map { $self->type('string', $_->name) } @$vis_values ],
        );
        if ($has_values) {
           $field_data{value_field} = $self->type('string', $value_field);
           $field_data{values}      = \@values;
        };
        push(@fields_out, filter $params, \%field_data);
    }

    return { fields => \@fields_out };
}

sub _legal_field_values {
    my ($self, $params) = @_;
    my $field = $params->{field};
    my $field_name = $field->name;
    my $user = Bugzilla->user;

    my @result;
    if (grep($_ eq $field_name, PRODUCT_SPECIFIC_FIELDS)) {
        my @list;
        if ($field_name eq 'version') {
            @list = Bugzilla::Version->get_all;
        }
        elsif ($field_name eq 'component') {
            @list = Bugzilla::Component->get_all;
        }
        else {
            @list = Bugzilla::Milestone->get_all;
        }

        foreach my $value (@list) {
            my $sortkey = $field_name eq 'target_milestone'
                          ? $value->sortkey : 0;
            # XXX This is very slow for large numbers of values.
            my $product_name = $value->product->name;
            if ($user->can_see_product($product_name)) {
                push(@result, {
                    name     => $self->type('string', $value->name),
                    sort_key => $self->type('int', $sortkey),
                    sortkey  => $self->type('int', $sortkey), # deprecated
                    visibility_values => [$self->type('string', $product_name)],
                    is_active         => $self->type('boolean', $value->is_active),
                });
            }
        }
    }

    elsif ($field_name eq 'bug_status') {
        my @status_all = Bugzilla::Status->get_all;
        my $initial_status = bless({ id => 0, name => '', is_open => 1, sortkey => 0,
                                     can_change_to => Bugzilla::Status->can_change_to },
                                   'Bugzilla::Status');
        unshift(@status_all, $initial_status);

        foreach my $status (@status_all) {
            my @can_change_to;
            foreach my $change_to (@{ $status->can_change_to }) {
                # There's no need to note that a status can transition
                # to itself.
                next if $change_to->id == $status->id;
                my %change_to_hash = (
                    name => $self->type('string', $change_to->name),
                    comment_required => $self->type('boolean', 
                        $change_to->comment_required_on_change_from($status)),
                );
                push(@can_change_to, \%change_to_hash);
            }

            push (@result, {
               name     => $self->type('string', $status->name),
               is_open  => $self->type('boolean', $status->is_open),
               sort_key => $self->type('int', $status->sortkey),
               sortkey  => $self->type('int', $status->sortkey), # deprecated
               can_change_to => \@can_change_to,
               visibility_values => [],
            });
        }
    }

    elsif ($field_name eq 'keywords') {
        my @legal_keywords = Bugzilla::Keyword->get_all;
        foreach my $value (@legal_keywords) {
            push (@result, {
               name     => $self->type('string', $value->name),
               description => $self->type('string', $value->description),
            });
        }
    }
    else {
        my @values = Bugzilla::Field::Choice->type($field)->get_all();
        foreach my $value (@values) {
            my $vis_val = $value->visibility_value;
            push(@result, {
                name     => $self->type('string', $value->name),
                sort_key => $self->type('int'   , $value->sortkey),
                sortkey  => $self->type('int'   , $value->sortkey), # deprecated
                visibility_values => [
                    defined $vis_val ? $self->type('string', $vis_val->name) 
                                     : ()
                ],
            });
        }
    }

    return \@result;
}

sub comments {
    my ($self, $params) = validate(@_, 'ids', 'comment_ids');

    if (!(defined $params->{ids} || defined $params->{comment_ids})) {
        ThrowCodeError('params_required',
                       { function => 'Bug.comments',
                         params   => ['ids', 'comment_ids'] });
    }

    my $bug_ids = $params->{ids} || [];
    my $comment_ids = $params->{comment_ids} || [];

    my $dbh  = Bugzilla->switch_to_shadow_db();
    my $user = Bugzilla->user;

    my %bugs;
    foreach my $bug_id (@$bug_ids) {
        my $bug = Bugzilla::Bug->check($bug_id);
        # We want the API to always return comments in the same order.
   
        my $comments = $bug->comments({ order => 'oldest_to_newest',
                                        after => $params->{new_since} });
        my @result;
        foreach my $comment (@$comments) {
            next if $comment->is_private && !$user->is_insider;
            push(@result, $self->_translate_comment($comment, $params));
        }
        $bugs{$bug->id}{'comments'} = \@result;
    }

    my %comments;
    if (scalar @$comment_ids) {
        my @ids = map { trim($_) } @$comment_ids;
        my $comment_data = Bugzilla::Comment->new_from_list(\@ids);

        # See if we were passed any invalid comment ids.
        my %got_ids = map { $_->id => 1 } @$comment_data;
        foreach my $comment_id (@ids) {
            if (!$got_ids{$comment_id}) {
                ThrowUserError('comment_id_invalid', { id => $comment_id });
            }
        }
 
        # Now make sure that we can see all the associated bugs.
        my %got_bug_ids = map { $_->bug_id => 1 } @$comment_data;
        Bugzilla::Bug->check($_) foreach (keys %got_bug_ids);

        foreach my $comment (@$comment_data) {
            if ($comment->is_private && !$user->is_insider) {
                ThrowUserError('comment_is_private', { id => $comment->id });
            }
            $comments{$comment->id} =
                $self->_translate_comment($comment, $params);
        }
    }

    return { bugs => \%bugs, comments => \%comments };
}

sub render_comment {
    my ($self, $params) = @_;

    unless (defined $params->{text}) {
        ThrowCodeError('params_required',
                       { function => 'Bug.render_comment',
                         params   => ['text'] });
    }

    Bugzilla->switch_to_shadow_db();
    my $bug = $params->{id} ? Bugzilla::Bug->check($params->{id}) : undef;

    my $tmpl = '[% text FILTER quoteUrls(bug) %]';
    my $html;
    my $template = Bugzilla->template;
    $template->process(
        \$tmpl,
        { bug => $bug, text => $params->{text}},
        \$html
    );

    return { html => $html };
}

# Helper for Bug.comments
sub _translate_comment {
    my ($self, $comment, $filters, $types, $prefix) = @_;
    my $attach_id = $comment->is_about_attachment ? $comment->extra_data
                                                  : undef;

    my $comment_hash = {
        id         => $self->type('int', $comment->id),
        bug_id     => $self->type('int', $comment->bug_id),
        creator    => $self->type('email', $comment->author->login),
        time       => $self->type('dateTime', $comment->creation_ts),
        creation_time => $self->type('dateTime', $comment->creation_ts),
        is_private => $self->type('boolean', $comment->is_private),
        text       => $self->type('string', $comment->body_full),
        attachment_id => $self->type('int', $attach_id),
        count      => $self->type('int', $comment->count),
    };

    # Don't load comment tags unless enabled
    if (Bugzilla->params->{'comment_taggers_group'}) {
        $comment_hash->{tags} = [
            map { $self->type('string', $_) }
            @{ $comment->tags }
        ];
    }

    return filter($filters, $comment_hash, $types, $prefix);
}

sub get {
    my ($self, $params) = validate(@_, 'ids');

    Bugzilla->switch_to_shadow_db() unless Bugzilla->user->id;

    my $ids = $params->{ids};
    defined $ids || ThrowCodeError('param_required', { param => 'ids' });

    my (@bugs, @faults, @hashes);

    # Cache permissions for bugs. This highly reduces the number of calls to the DB.
    # visible_bugs() is only able to handle bug IDs, so we have to skip aliases.
    my @int = grep { $_ =~ /^\d+$/ } @$ids;
    Bugzilla->user->visible_bugs(\@int);

    foreach my $bug_id (@$ids) {
        my $bug;
        if ($params->{permissive}) {
            eval { $bug = Bugzilla::Bug->check($bug_id); };
            if ($@) {
                push(@faults, {id => $bug_id,
                               faultString => $@->faultstring,
                               faultCode => $@->faultcode,
                              }
                    );
                undef $@;
                next;
            }
        }
        else {
            $bug = Bugzilla::Bug->check($bug_id);
        }
        push(@bugs, $bug);
        push(@hashes, $self->_bug_to_hash($bug, $params));
    }

    # Set the ETag before inserting the update tokens
    # since the tokens will always be unique even if
    # the data has not changed.
    $self->bz_etag(\@hashes);

    $self->_add_update_tokens($params, \@bugs, \@hashes);

    return { bugs => \@hashes, faults => \@faults };
}

# this is a function that gets bug activity for list of bug ids 
# it can be called as the following:
# $call = $rpc->call( 'Bug.history', { ids => [1,2] });
sub history {
    my ($self, $params) = validate(@_, 'ids');

    Bugzilla->switch_to_shadow_db();

    my $ids = $params->{ids};
    defined $ids || ThrowCodeError('param_required', { param => 'ids' });

    my %api_name = reverse %{ Bugzilla::Bug::FIELD_MAP() };
    $api_name{'bug_group'} = 'groups';

    my @return;
    foreach my $bug_id (@$ids) {
        my %item;
        my $bug = Bugzilla::Bug->check($bug_id);
        $bug_id = $bug->id;
        $item{id} = $self->type('int', $bug_id);

        my ($activity) = $bug->get_activity(undef, $params->{new_since});

        my @history;
        foreach my $changeset (@$activity) {
            my %bug_history;
            $bug_history{when} = $self->type('dateTime', $changeset->{when});
            $bug_history{who}  = $self->type('string', $changeset->{who});
            $bug_history{changes} = [];
            foreach my $change (@{ $changeset->{changes} }) {
                my $api_field = $api_name{$change->{fieldname}} || $change->{fieldname};
                my $attach_id = delete $change->{attachid};
                if ($attach_id) {
                    $change->{attachment_id} = $self->type('int', $attach_id);
                }
                $change->{removed} = $self->type('string', $change->{removed});
                $change->{added}   = $self->type('string', $change->{added});
                $change->{field_name} = $self->type('string', $api_field);
                delete $change->{fieldname};
                push (@{$bug_history{changes}}, $change);
            }
            
            push (@history, \%bug_history);
        }

        $item{history} = \@history;

        # alias is returned in case users passes a mixture of ids and aliases
        # then they get to know which bug activity relates to which value  
        # they passed
        $item{alias} = [ map { $self->type('string', $_) } @{ $bug->alias } ];

        push(@return, \%item);
    }

    return { bugs => \@return };
}

sub search {
    my ($self, $params) = @_;
    my $user = Bugzilla->user;
    my $dbh  = Bugzilla->dbh;

    Bugzilla->switch_to_shadow_db();

    my $match_params = dclone($params);
    delete $match_params->{include_fields};
    delete $match_params->{exclude_fields};

    # Determine whether this is a quicksearch query
    if (exists $match_params->{quicksearch}) {
        my $quicksearch = quicksearch($match_params->{'quicksearch'});
        my $cgi = Bugzilla::CGI->new($quicksearch);
        $match_params = $cgi->Vars;
    }

    if ( defined($match_params->{offset}) and !defined($match_params->{limit}) ) {
        ThrowCodeError('param_required',
                       { param => 'limit', function => 'Bug.search()' });
    }

    my $max_results = Bugzilla->params->{max_search_results};
    unless (defined $match_params->{limit} && $match_params->{limit} == 0) {
        if (!defined $match_params->{limit} || $match_params->{limit} > $max_results) {
            $match_params->{limit} = $max_results;
        }
    }
    else {
        delete $match_params->{limit};
        delete $match_params->{offset};
    }

    $match_params = Bugzilla::Bug::map_fields($match_params);

    my %options = ( fields => ['bug_id'] );

    # Find the highest custom field id
    my @field_ids = grep(/^f(\d+)$/, keys %$match_params);
    my $last_field_id = @field_ids ? max @field_ids + 1 : 1;

    # Do special search types for certain fields.
    if (my $change_when = delete $match_params->{'delta_ts'}) {
        $match_params->{"f${last_field_id}"} = 'delta_ts';
        $match_params->{"o${last_field_id}"} = 'greaterthaneq';
        $match_params->{"v${last_field_id}"} = $change_when;
        $last_field_id++;
    }
    if (my $creation_when = delete $match_params->{'creation_ts'}) {
        $match_params->{"f${last_field_id}"} = 'creation_ts';
        $match_params->{"o${last_field_id}"} = 'greaterthaneq';
        $match_params->{"v${last_field_id}"} = $creation_when;
        $last_field_id++;
    }

    # Some fields require a search type such as short desc, keywords, etc.
    foreach my $param (qw(short_desc longdesc status_whiteboard bug_file_loc)) {
        if (defined $match_params->{$param} && !defined $match_params->{$param . '_type'}) {
            $match_params->{$param . '_type'} = 'allwordssubstr';
        }
    }
    if (defined $match_params->{'keywords'} && !defined $match_params->{'keywords_type'}) {
        $match_params->{'keywords_type'} = 'allwords';
    }

    # Backwards compatibility with old method regarding role search
    $match_params->{'reporter'} = delete $match_params->{'creator'} if $match_params->{'creator'};
    foreach my $role (qw(assigned_to reporter qa_contact longdesc cc)) {
        next if !exists $match_params->{$role};
        my $value = delete $match_params->{$role};
        $match_params->{"f${last_field_id}"} = $role;
        $match_params->{"o${last_field_id}"} = "anywordssubstr";
        $match_params->{"v${last_field_id}"} = ref $value ? join(" ", @{$value}) : $value;
        $last_field_id++;
    }

    # If no other parameters have been passed other than limit and offset
    # then we throw error if system is configured to do so.
    if (!grep(!/^(limit|offset)$/, keys %$match_params)
        && !Bugzilla->params->{search_allow_no_criteria})
    {
        ThrowUserError('buglist_parameters_required');
    }

    $options{order}  = [ split(/\s*,\s*/, delete $match_params->{order}) ] if $match_params->{order};
    $options{params} = $match_params;

    my $search = new Bugzilla::Search(%options);
    my ($data) = $search->data;

    if (!scalar @$data) {
        return { bugs => [] };
    }

    # Search.pm won't return bugs that the user shouldn't see so no filtering is needed.
    my @bug_ids = map { $_->[0] } @$data;
    my %bug_objects = map { $_->id => $_ } @{ Bugzilla::Bug->new_from_list(\@bug_ids) };
    my @bugs = map { $bug_objects{$_} } @bug_ids;
    @bugs = map { $self->_bug_to_hash($_, $params) } @bugs;

    return { bugs => \@bugs };
}

sub possible_duplicates {
    my ($self, $params) = validate(@_, 'products');
    my $user = Bugzilla->user;

    Bugzilla->switch_to_shadow_db();

    # Undo the array-ification that validate() does, for "summary".
    $params->{summary} || ThrowCodeError('param_required',
        { function => 'Bug.possible_duplicates', param => 'summary' });

    my @products;
    foreach my $name (@{ $params->{'products'} || [] }) {
        my $object = $user->can_enter_product($name, THROW_ERROR);
        push(@products, $object);
    }

    my $possible_dupes = Bugzilla::Bug->possible_duplicates(
        { summary => $params->{summary}, products => \@products,
          limit   => $params->{limit} });
    my @hashes = map { $self->_bug_to_hash($_, $params) } @$possible_dupes;
    $self->_add_update_tokens($params, $possible_dupes, \@hashes);
    return { bugs => \@hashes };
}

sub update {
    my ($self, $params) = validate(@_, 'ids');

    my $user = Bugzilla->login(LOGIN_REQUIRED);
    my $dbh = Bugzilla->dbh;

    # We skip certain fields because their set_ methods actually use
    # the external names instead of the internal names.
    $params = Bugzilla::Bug::map_fields($params, 
        { summary => 1, platform => 1, severity => 1, url => 1 });

    my $ids = delete $params->{ids};
    defined $ids || ThrowCodeError('param_required', { param => 'ids' });

    my @bugs = map { Bugzilla::Bug->check_for_edit($_) } @$ids;

    my %values = %$params;
    $values{other_bugs} = \@bugs;

    if (exists $values{comment} and exists $values{comment}{comment}) {
        $values{comment}{body} = delete $values{comment}{comment};
    }

    # Prevent bugs that could be triggered by specifying fields that
    # have valid "set_" functions in Bugzilla::Bug, but shouldn't be
    # called using those field names.
    delete $values{dependencies};

    # For backwards compatibility, treat alias string or array as a set action
    if (exists $values{alias}) {
        if (not ref $values{alias}) {
            $values{alias} = { set => [ $values{alias} ] };
        }
        elsif (ref $values{alias} eq 'ARRAY') {
            $values{alias} = { set => $values{alias} };
        }
    }

    my $flags = delete $values{flags};

    foreach my $bug (@bugs) {
        $bug->set_all(\%values);
        if ($flags) {
            my ($old_flags, $new_flags) = extract_flags($flags, $bug);
            $bug->set_flags($old_flags, $new_flags);
        }
    }

    my %all_changes;
    $dbh->bz_start_transaction();
    foreach my $bug (@bugs) {
        $all_changes{$bug->id} = $bug->update();
    }
    $dbh->bz_commit_transaction();

    foreach my $bug (@bugs) {
        $bug->send_changes($all_changes{$bug->id});
    }

    my %api_name = reverse %{ Bugzilla::Bug::FIELD_MAP() };
    # This doesn't normally belong in FIELD_MAP, but we do want to translate
    # "bug_group" back into "groups".
    $api_name{'bug_group'} = 'groups';

    my @result;
    foreach my $bug (@bugs) {
        my %hash = (
            id               => $self->type('int', $bug->id),
            last_change_time => $self->type('dateTime', $bug->delta_ts),
            changes          => {},
        );

        # alias is returned in case users pass a mixture of ids and aliases,
        # so that they can know which set of changes relates to which value
        # they passed.
        $hash{alias} = [ map { $self->type('string', $_) } @{ $bug->alias } ];

        my %changes = %{ $all_changes{$bug->id} };
        foreach my $field (keys %changes) {
            my $change = $changes{$field};
            my $api_field = $api_name{$field} || $field;
            # We normalize undef to an empty string, so that the API
            # stays consistent for things like Deadline that can become
            # empty.
            $change->[0] = '' if !defined $change->[0];
            $change->[1] = '' if !defined $change->[1];
            $hash{changes}->{$api_field} = {
                removed => $self->type('string', $change->[0]),
                added   => $self->type('string', $change->[1]) 
            };
        }

        push(@result, \%hash);
    }

    return { bugs => \@result };
}

sub create {
    my ($self, $params) = @_;
    my $dbh = Bugzilla->dbh;

    Bugzilla->login(LOGIN_REQUIRED);

    $params = Bugzilla::Bug::map_fields($params);

    my $flags = delete $params->{flags};

    # We start a nested transaction in case flag setting fails
    # we want the bug creation to roll back as well.
    $dbh->bz_start_transaction();

    my $bug = Bugzilla::Bug->create($params);

    # Set bug flags
    if ($flags) {
        my ($flags, $new_flags) = extract_flags($flags, $bug);
        $bug->set_flags($flags, $new_flags);
        $bug->update($bug->creation_ts);
    }

    $dbh->bz_commit_transaction();

    $bug->send_changes();

    return { id => $self->type('int', $bug->bug_id) };
}

sub legal_values {
    my ($self, $params) = @_;

    Bugzilla->switch_to_shadow_db();

    defined $params->{field} 
        or ThrowCodeError('param_required', { param => 'field' });

    my $field = Bugzilla::Bug::FIELD_MAP->{$params->{field}} 
                || $params->{field};

    my @global_selects =
        @{ Bugzilla->fields({ is_select => 1, is_abnormal => 0 }) };

    my $values;
    if (grep($_->name eq $field, @global_selects)) {
        # The field is a valid one.
        trick_taint($field);
        $values = get_legal_field_values($field);
    }
    elsif (grep($_ eq $field, PRODUCT_SPECIFIC_FIELDS)) {
        my $id = $params->{product_id};
        defined $id || ThrowCodeError('param_required',
            { function => 'Bug.legal_values', param => 'product_id' });
        grep($_->id eq $id, @{Bugzilla->user->get_accessible_products})
            || ThrowUserError('product_access_denied', { id => $id });

        my $product = new Bugzilla::Product($id);
        my @objects;
        if ($field eq 'version') {
            @objects = @{$product->versions};
        }
        elsif ($field eq 'target_milestone') {
            @objects = @{$product->milestones};
        }
        elsif ($field eq 'component') {
            @objects = @{$product->components};
        }

        $values = [map { $_->name } @objects];
    }
    else {
        ThrowCodeError('invalid_field_name', { field => $params->{field} });
    }

    my @result;
    foreach my $val (@$values) {
        push(@result, $self->type('string', $val));
    }

    return { values => \@result };
}

sub add_attachment {
    my ($self, $params) = validate(@_, 'ids');
    my $dbh = Bugzilla->dbh;

    Bugzilla->login(LOGIN_REQUIRED);
    defined $params->{ids}
        || ThrowCodeError('param_required', { param => 'ids' });
    defined $params->{data}
        || ThrowCodeError('param_required', { param => 'data' });

    my @bugs = map { Bugzilla::Bug->check_for_edit($_) } @{ $params->{ids} };

    my @created;
    $dbh->bz_start_transaction();
    my $timestamp = $dbh->selectrow_array('SELECT LOCALTIMESTAMP(0)');

    my $flags = delete $params->{flags};

    foreach my $bug (@bugs) {
        my $attachment = Bugzilla::Attachment->create({
            bug         => $bug,
            creation_ts => $timestamp,
            data        => $params->{data},
            description => $params->{summary},
            filename    => $params->{file_name},
            mimetype    => $params->{content_type},
            ispatch     => $params->{is_patch},
            isprivate   => $params->{is_private},
        });

        if ($flags) {
            my ($old_flags, $new_flags) = extract_flags($flags, $bug, $attachment);
            $attachment->set_flags($old_flags, $new_flags);
        }

        $attachment->update($timestamp);
        my $comment = $params->{comment} || '';
        $attachment->bug->add_comment($comment, 
            { isprivate  => $attachment->isprivate,
              type       => CMT_ATTACHMENT_CREATED,
              extra_data => $attachment->id });
        push(@created, $attachment);
    }
    $_->bug->update($timestamp) foreach @created;
    $dbh->bz_commit_transaction();

    $_->send_changes() foreach @bugs;

    my @created_ids = map { $_->id } @created;

    return { ids => \@created_ids };
}

sub update_attachment {
    my ($self, $params) = validate(@_, 'ids');

    my $user = Bugzilla->login(LOGIN_REQUIRED);
    my $dbh = Bugzilla->dbh;

    my $ids = delete $params->{ids};
    defined $ids || ThrowCodeError('param_required', { param => 'ids' });

    # Some fields cannot be sent to set_all
    foreach my $key (qw(login password token)) {
        delete $params->{$key};
    }

    $params = translate($params, ATTACHMENT_MAPPED_SETTERS);

    # Get all the attachments, after verifying that they exist and are editable
    my @attachments = ();
    my %bugs = ();
    foreach my $id (@$ids) {
        my $attachment = Bugzilla::Attachment->new($id)
          || ThrowUserError("invalid_attach_id", { attach_id => $id });
        my $bug = $attachment->bug;
        $attachment->_check_bug;

        push @attachments, $attachment;
        $bugs{$bug->id} = $bug;
    }

    my $flags = delete $params->{flags};
    my $comment = delete $params->{comment};

    # Update the values
    foreach my $attachment (@attachments) {
        my ($update_flags, $new_flags) = $flags
            ? extract_flags($flags, $attachment->bug, $attachment)
            : ([], []);
        if ($attachment->validate_can_edit) {
            $attachment->set_all($params);
            $attachment->set_flags($update_flags, $new_flags) if $flags;
        }
        elsif (scalar @$update_flags && !scalar(@$new_flags) && !scalar keys %$params) {
            # Requestees can set flags targetted to them, even if they cannot
            # edit the attachment. Flag setters can edit their own flags too.
            my %flag_list = map { $_->{id} => $_ } @$update_flags;
            my $flag_objs = Bugzilla::Flag->new_from_list([ keys %flag_list ]);
            my @editable_flags;
            foreach my $flag_obj (@$flag_objs) {
                if ($flag_obj->setter_id == $user->id
                    || ($flag_obj->requestee_id && $flag_obj->requestee_id == $user->id))
                {
                    push(@editable_flags, $flag_list{$flag_obj->id});
                }
            }
            if (!scalar @editable_flags) {
                ThrowUserError("illegal_attachment_edit", { attach_id => $attachment->id });
            }
            $attachment->set_flags(\@editable_flags, []);
        }
        else {
            ThrowUserError("illegal_attachment_edit", { attach_id => $attachment->id });
        }
    }

    $dbh->bz_start_transaction();

    # Do the actual update and get information to return to user
    my @result;
    foreach my $attachment (@attachments) {
        my $changes = $attachment->update();

        if ($comment = trim($comment)) {
            $attachment->bug->add_comment($comment,
                { isprivate  => $attachment->isprivate,
                  type       => CMT_ATTACHMENT_UPDATED,
                  extra_data => $attachment->id });
        }

        $changes = translate($changes, ATTACHMENT_MAPPED_RETURNS);

        my %hash = (
            id               => $self->type('int', $attachment->id),
            last_change_time => $self->type('dateTime', $attachment->modification_time),
            changes          => {},
        );

        foreach my $field (keys %$changes) {
            my $change = $changes->{$field};

            # We normalize undef to an empty string, so that the API
            # stays consistent for things like Deadline that can become
            # empty.
            $hash{changes}->{$field} = {
                removed => $self->type('string', $change->[0] // ''),
                added   => $self->type('string', $change->[1] // '')
            };
        }

        push(@result, \%hash);
    }

    $dbh->bz_commit_transaction();

    # Email users about the change
    foreach my $bug (values %bugs) {
        $bug->update();
        $bug->send_changes();
    }

    # Return the information to the user
    return { attachments => \@result };
}

sub add_comment {
    my ($self, $params) = @_;

    # The user must login in order add a comment
    my $user = Bugzilla->login(LOGIN_REQUIRED);

    # Check parameters
    defined $params->{id} 
        || ThrowCodeError('param_required', { param => 'id' }); 
    my $comment = $params->{comment}; 
    (defined $comment && trim($comment) ne '')
        || ThrowCodeError('param_required', { param => 'comment' });
    
    my $bug = Bugzilla::Bug->check_for_edit($params->{id});

    # Backwards-compatibility for versions before 3.6    
    if (defined $params->{private}) {
        $params->{is_private} = delete $params->{private};
    }
    # Append comment
    $bug->add_comment($comment, { isprivate => $params->{is_private},
                                  work_time => $params->{work_time} });
    $bug->update();

    my $new_comment_id = $bug->{added_comments}[0]->id;

    # Send mail.
    Bugzilla::BugMail::Send($bug->bug_id, { changer => $user });

    return { id => $self->type('int', $new_comment_id) };
}

sub update_see_also {
    my ($self, $params) = @_;

    my $user = Bugzilla->login(LOGIN_REQUIRED);

    # Check parameters
    $params->{ids}
        || ThrowCodeError('param_required', { param => 'id' });
    my ($add, $remove) = @$params{qw(add remove)};
    ($add || $remove)
        or ThrowCodeError('params_required', { params => ['add', 'remove'] });

    my @bugs;
    foreach my $id (@{ $params->{ids} }) {
        my $bug = Bugzilla::Bug->check_for_edit($id);
        push(@bugs, $bug);
        if ($remove) {
            $bug->remove_see_also($_) foreach @$remove;
        }
        if ($add) {
            $bug->add_see_also($_) foreach @$add;
        }
    }
    
    my %changes;
    foreach my $bug (@bugs) {
        my $change = $bug->update();
        if (my $see_also = $change->{see_also}) {
            $changes{$bug->id}->{see_also} = {
                removed => [split(', ', $see_also->[0])],
                added   => [split(', ', $see_also->[1])],
            };
        }
        else {
            # We still want a changes entry, for API consistency.
            $changes{$bug->id}->{see_also} = { added => [], removed => [] };
        }

        Bugzilla::BugMail::Send($bug->id, { changer => $user });
    }

    return { changes => \%changes };
}

sub attachments {
    my ($self, $params) = validate(@_, 'ids', 'attachment_ids');

    Bugzilla->switch_to_shadow_db() unless Bugzilla->user->id;

    if (!(defined $params->{ids}
          or defined $params->{attachment_ids}))
    {
        ThrowCodeError('param_required',
                       { function => 'Bug.attachments', 
                         params   => ['ids', 'attachment_ids'] });
    }

    my $ids = $params->{ids} || [];
    my $attach_ids = $params->{attachment_ids} || [];

    my %bugs;
    foreach my $bug_id (@$ids) {
        my $bug = Bugzilla::Bug->check($bug_id);
        $bugs{$bug->id} = [];
        foreach my $attach (@{$bug->attachments}) {
            push @{$bugs{$bug->id}},
                $self->_attachment_to_hash($attach, $params);
        }
    }

    my %attachments;
    foreach my $attach (@{Bugzilla::Attachment->new_from_list($attach_ids)}) {
        Bugzilla::Bug->check($attach->bug_id);
        if ($attach->isprivate && !Bugzilla->user->is_insider) {
            ThrowUserError('auth_failure', {action    => 'access',
                                            object    => 'attachment',
                                            attach_id => $attach->id});
        }
        $attachments{$attach->id} =
            $self->_attachment_to_hash($attach, $params);
    }

    return { bugs => \%bugs, attachments => \%attachments };
}

sub update_tags {
    my ($self, $params) = @_;

    Bugzilla->login(LOGIN_REQUIRED);

    my $ids  = $params->{ids};
    my $tags = $params->{tags};

    ThrowCodeError('param_required',
                   { function => 'Bug.update_tags', 
                     param    => 'ids' }) if !defined $ids;

    ThrowCodeError('param_required',
                   { function => 'Bug.update_tags', 
                     param    => 'tags' }) if !defined $tags;

    my %changes;
    foreach my $bug_id (@$ids) {
        my $bug = Bugzilla::Bug->check($bug_id);
        my @old_tags = @{ $bug->tags };

        $bug->remove_tag($_) foreach @{ $tags->{remove} || [] };
        $bug->add_tag($_) foreach @{ $tags->{add} || [] };

        my ($removed, $added) = diff_arrays(\@old_tags, $bug->tags);

        my @removed = map { $self->type('string', $_) } @$removed;
        my @added   = map { $self->type('string', $_) } @$added;

        $changes{$bug->id}->{tags} = {
            removed => \@removed,
            added   => \@added
        };
    }

    return { changes => \%changes };
}

sub update_comment_tags {
    my ($self, $params) = @_;

    my $user = Bugzilla->login(LOGIN_REQUIRED);
    Bugzilla->params->{'comment_taggers_group'}
        || ThrowUserError("comment_tag_disabled");
    $user->can_tag_comments
        || ThrowUserError("auth_failure",
                          { group  => Bugzilla->params->{'comment_taggers_group'},
                            action => "update",
                            object => "comment_tags" });

    my $comment_id  = $params->{comment_id}
        // ThrowCodeError('param_required',
                          { function => 'Bug.update_comment_tags',
                            param    => 'comment_id' });

    my $comment = Bugzilla::Comment->new($comment_id)
        || return [];
    $comment->bug->check_is_visible();
    if ($comment->is_private && !$user->is_insider) {
        ThrowUserError('comment_is_private', { id => $comment_id });
    }

    my $dbh = Bugzilla->dbh;
    $dbh->bz_start_transaction();
    foreach my $tag (@{ $params->{add} || [] }) {
        $comment->add_tag($tag) if defined $tag;
    }
    foreach my $tag (@{ $params->{remove} || [] }) {
        $comment->remove_tag($tag) if defined $tag;
    }
    $comment->update();
    $dbh->bz_commit_transaction();

    return $comment->tags;
}

sub search_comment_tags {
    my ($self, $params) = @_;

    Bugzilla->login(LOGIN_REQUIRED);
    Bugzilla->params->{'comment_taggers_group'}
        || ThrowUserError("comment_tag_disabled");
    Bugzilla->user->can_tag_comments
        || ThrowUserError("auth_failure", { group  => Bugzilla->params->{'comment_taggers_group'},
                                            action => "search",
                                            object => "comment_tags"});

    my $query = $params->{query};
    $query
        // ThrowCodeError('param_required', { param => 'query' });
    my $limit = $params->{limit} || 7;
    detaint_natural($limit)
        || ThrowCodeError('param_must_be_numeric', { param    => 'limit',
                                                     function => 'Bug.search_comment_tags' });


    my $tags = Bugzilla::Comment::TagWeights->match({
        WHERE => {
            'tag LIKE ?' => "\%$query\%",
        },
        LIMIT => $limit,
    });
    return [ map { $_->tag } @$tags ];
}

##############################
# Private Helper Subroutines #
##############################

# A helper for get() and search(). This is done in this fashion in order
# to produce a stable API and to explicitly type return values.
# The internals of Bugzilla::Bug are not stable enough to just
# return them directly.

sub _bug_to_hash {
    my ($self, $bug, $params) = @_;

    # All the basic bug attributes are here, in alphabetical order.
    # A bug attribute is "basic" if it doesn't require an additional
    # database call to get the info.
    my %item = %{ filter $params, {
        # No need to format $bug->deadline specially, because Bugzilla::Bug
        # already does it for us.
        deadline         => $self->type('string', $bug->deadline),
        id               => $self->type('int', $bug->bug_id),
        is_confirmed     => $self->type('boolean', $bug->everconfirmed),
        op_sys           => $self->type('string', $bug->op_sys),
        platform         => $self->type('string', $bug->rep_platform),
        priority         => $self->type('string', $bug->priority),
        resolution       => $self->type('string', $bug->resolution),
        severity         => $self->type('string', $bug->bug_severity),
        status           => $self->type('string', $bug->bug_status),
        summary          => $self->type('string', $bug->short_desc),
        target_milestone => $self->type('string', $bug->target_milestone),
        url              => $self->type('string', $bug->bug_file_loc),
        version          => $self->type('string', $bug->version),
        whiteboard       => $self->type('string', $bug->status_whiteboard),
    } };

    # First we handle any fields that require extra work (such as date parsing
    # or SQL calls).
    if (filter_wants $params, 'alias') {
        $item{alias} = [ map { $self->type('string', $_) } @{ $bug->alias } ];
    }
    if (filter_wants $params, 'assigned_to') {
        $item{'assigned_to'} = $self->type('email', $bug->assigned_to->login);
        $item{'assigned_to_detail'} = $self->_user_to_hash($bug->assigned_to, $params, undef, 'assigned_to');
    }
    if (filter_wants $params, 'blocks') {
        my @blocks = map { $self->type('int', $_) } @{ $bug->blocked };
        $item{'blocks'} = \@blocks;
    }
    if (filter_wants $params, 'classification') {
        $item{classification} = $self->type('string', $bug->classification);
    }
    if (filter_wants $params, 'component') {
        $item{component} = $self->type('string', $bug->component);
    }
    if (filter_wants $params, 'cc') {
        my @cc = map { $self->type('email', $_) } @{ $bug->cc };
        $item{'cc'} = \@cc;
        $item{'cc_detail'} = [ map { $self->_user_to_hash($_, $params, undef, 'cc') } @{ $bug->cc_users } ];
    }
    if (filter_wants $params, 'creation_time') {
        $item{'creation_time'} = $self->type('dateTime', $bug->creation_ts);
    }
    if (filter_wants $params, 'creator') {
        $item{'creator'} = $self->type('email', $bug->reporter->login);
        $item{'creator_detail'} = $self->_user_to_hash($bug->reporter, $params, undef, 'creator');
    }
    if (filter_wants $params, 'depends_on') {
        my @depends_on = map { $self->type('int', $_) } @{ $bug->dependson };
        $item{'depends_on'} = \@depends_on;
    }
    if (filter_wants $params, 'dupe_of') {
        $item{'dupe_of'} = $self->type('int', $bug->dup_id);
    }
    if (filter_wants $params, 'groups') {
        my @groups = map { $self->type('string', $_->name) }
                     @{ $bug->groups_in };
        $item{'groups'} = \@groups;
    }
    if (filter_wants $params, 'is_open') {
        $item{'is_open'} = $self->type('boolean', $bug->status->is_open);
    }
    if (filter_wants $params, 'keywords') {
        my @keywords = map { $self->type('string', $_->name) }
                       @{ $bug->keyword_objects };
        $item{'keywords'} = \@keywords;
    }
    if (filter_wants $params, 'last_change_time') {
        $item{'last_change_time'} = $self->type('dateTime', $bug->delta_ts);
    }
    if (filter_wants $params, 'product') {
        $item{product} = $self->type('string', $bug->product);
    }
    if (filter_wants $params, 'qa_contact') {
        my $qa_login = $bug->qa_contact ? $bug->qa_contact->login : '';
        $item{'qa_contact'} = $self->type('email', $qa_login);
        if ($bug->qa_contact) {
            $item{'qa_contact_detail'} = $self->_user_to_hash($bug->qa_contact, $params, undef, 'qa_contact');
        }
    }
    if (filter_wants $params, 'see_also') {
        my @see_also = map { $self->type('string', $_->name) }
                       @{ $bug->see_also };
        $item{'see_also'} = \@see_also;
    }
    if (filter_wants $params, 'flags') {
        $item{'flags'} = [ map { $self->_flag_to_hash($_) } @{$bug->flags} ];
    }
    if (filter_wants $params, 'tags', 'extra') {
        $item{'tags'} = $bug->tags;
    }

    # And now custom fields
    my @custom_fields = Bugzilla->active_custom_fields;
    foreach my $field (@custom_fields) {
        my $name = $field->name;
        next if !filter_wants($params, $name, ['default', 'custom']);
        if ($field->type == FIELD_TYPE_BUG_ID) {
            $item{$name} = $self->type('int', $bug->$name);
        }
        elsif ($field->type == FIELD_TYPE_DATETIME
               || $field->type == FIELD_TYPE_DATE)
        {
            $item{$name} = $self->type('dateTime', $bug->$name);
        }
        elsif ($field->type == FIELD_TYPE_MULTI_SELECT) {
            my @values = map { $self->type('string', $_) } @{ $bug->$name };
            $item{$name} = \@values;
        }
        else {
            $item{$name} = $self->type('string', $bug->$name);
        }
    }

    # Timetracking fields are only sent if the user can see them.
    if (Bugzilla->user->is_timetracker) {
        if (filter_wants $params, 'estimated_time') {
            $item{'estimated_time'} = $self->type('double', $bug->estimated_time);
        }
        if (filter_wants $params, 'remaining_time') {
            $item{'remaining_time'} = $self->type('double', $bug->remaining_time);
        }
        if (filter_wants $params, 'actual_time') {
            $item{'actual_time'} = $self->type('double', $bug->actual_time);
        }
    }

    # The "accessible" bits go here because they have long names and it
    # makes the code look nicer to separate them out.
    if (filter_wants $params, 'is_cc_accessible') {
        $item{'is_cc_accessible'} = $self->type('boolean', $bug->cclist_accessible);
    }
    if (filter_wants $params, 'is_creator_accessible') {
        $item{'is_creator_accessible'} = $self->type('boolean', $bug->reporter_accessible);
    }

    return \%item;
}

sub _user_to_hash {
    my ($self, $user, $filters, $types, $prefix) = @_;
    my $item = filter $filters, {
        id        => $self->type('int', $user->id),
        real_name => $self->type('string', $user->name),
        name      => $self->type('email', $user->login),
        email     => $self->type('email', $user->email),
    }, $types, $prefix;
    return $item;
}

sub _attachment_to_hash {
    my ($self, $attach, $filters, $types, $prefix) = @_;

    my $item = filter $filters, {
        creation_time    => $self->type('dateTime', $attach->attached),
        last_change_time => $self->type('dateTime', $attach->modification_time),
        id               => $self->type('int', $attach->id),
        bug_id           => $self->type('int', $attach->bug_id),
        file_name        => $self->type('string', $attach->filename),
        summary          => $self->type('string', $attach->description),
        content_type     => $self->type('string', $attach->contenttype),
        is_private       => $self->type('int', $attach->isprivate),
        is_obsolete      => $self->type('int', $attach->isobsolete),
        is_patch         => $self->type('int', $attach->ispatch),
    }, $types, $prefix;

    # creator requires an extra lookup, so we only send them if
    # the filter wants them.
    if (filter_wants $filters, 'creator', $types, $prefix) {
        $item->{'creator'} = $self->type('email', $attach->attacher->login);
    }

    if (filter_wants $filters, 'data', $types, $prefix) {
        $item->{'data'} = $self->type('base64', $attach->data);
    }

    if (filter_wants $filters, 'size', $types, $prefix) {
        $item->{'size'} = $self->type('int', $attach->datasize);
    }

    if (filter_wants $filters, 'flags', $types, $prefix) {
        $item->{'flags'} = [ map { $self->_flag_to_hash($_) } @{$attach->flags} ];
    }

    return $item;
}

sub _flag_to_hash {
    my ($self, $flag) = @_;

    my $item = {
        id                => $self->type('int', $flag->id),
        name              => $self->type('string', $flag->name),
        type_id           => $self->type('int', $flag->type_id),
        creation_date     => $self->type('dateTime', $flag->creation_date), 
        modification_date => $self->type('dateTime', $flag->modification_date), 
        status            => $self->type('string', $flag->status)
    };

    foreach my $field (qw(setter requestee)) {
        my $field_id = $field . "_id";
        $item->{$field} = $self->type('email', $flag->$field->login)
            if $flag->$field_id;
    }

    return $item;
}

sub _add_update_tokens {
    my ($self, $params, $bugs, $hashes) = @_;

    return if !Bugzilla->user->id;
    return if !filter_wants($params, 'update_token');

    for(my $i = 0; $i < @$bugs; $i++) {
        my $token = issue_hash_token([$bugs->[$i]->id, $bugs->[$i]->delta_ts]);
        $hashes->[$i]->{'update_token'} = $self->type('string', $token);
    }
}

1;

__END__

=head1 NAME

Bugzilla::Webservice::Bug - The API for creating, changing, and getting the
details of bugs.

=head1 DESCRIPTION

This part of the Bugzilla API allows you to file a new bug in Bugzilla,
or get information about bugs that have already been filed.

=head1 METHODS

See L<Bugzilla::WebService> for a description of how parameters are passed,
and what B<STABLE>, B<UNSTABLE>, and B<EXPERIMENTAL> mean.

Although the data input and output is the same for JSONRPC, XMLRPC and REST,
the directions for how to access the data via REST is noted in each method
where applicable.

=head1 Utility Functions

=head2 fields

B<UNSTABLE>

=over

=item B<Description>

Get information about valid bug fields, including the lists of legal values
for each field.

=item B<REST>

You have several options for retreiving information about fields. The first
part is the request method and the rest is the related path needed.

To get information about all fields:

GET /rest/field/bug

To get information related to a single field:

GET /rest/field/bug/<id_or_name>

The returned data format is the same as below.

=item B<Params>

You can pass either field ids or field names.

B<Note>: If neither C<ids> nor C<names> is specified, then all
non-obsolete fields will be returned.

In addition to the parameters below, this method also accepts the
standard L<include_fields|Bugzilla::WebService/include_fields> and
L<exclude_fields|Bugzilla::WebService/exclude_fields> arguments.

=over

=item C<ids>   (array) - An array of integer field ids.

=item C<names> (array) - An array of strings representing field names.

=back

=item B<Returns>

A hash containing a single element, C<fields>. This is an array of hashes,
containing the following keys:

=over

=item C<id>

C<int> An integer id uniquely identifying this field in this installation only.

=item C<type>

C<int> The number of the fieldtype. The following values are defined:

=over

=item C<0> Unknown

=item C<1> Free Text

=item C<2> Drop Down

=item C<3> Multiple-Selection Box

=item C<4> Large Text Box

=item C<5> Date/Time

=item C<6> Bug Id

=item C<7> Bug URLs ("See Also")

=item C<8> Keywords

=item C<9> Date

=item C<10> Integer value

=back

=item C<is_custom>

C<boolean> True when this is a custom field, false otherwise.

=item C<name>

C<string> The internal name of this field. This is a unique identifier for
this field. If this is not a custom field, then this name will be the same
across all Bugzilla installations.

=item C<display_name>

C<string> The name of the field, as it is shown in the user interface.

=item C<is_mandatory>

C<boolean> True if the field must have a value when filing new bugs.
Also, mandatory fields cannot have their value cleared when updating
bugs.

=item C<is_on_bug_entry>

C<boolean> For custom fields, this is true if the field is shown when you
enter a new bug. For standard fields, this is currently always false,
even if the field shows up when entering a bug. (To know whether or not
a standard field is valid on bug entry, see L</create>.)

=item C<visibility_field>

C<string>  The name of a field that controls the visibility of this field
in the user interface. This field only appears in the user interface when
the named field is equal to one of the values in C<visibility_values>.
Can be null.

=item C<visibility_values>

C<array> of C<string>s This field is only shown when C<visibility_field>
matches one of these values. When C<visibility_field> is null,
then this is an empty array.

=item C<value_field>

C<string>  The name of the field that controls whether or not particular
values of the field are shown in the user interface. Can be null.

=item C<values>

This is an array of hashes, representing the legal values for
select-type (drop-down and multiple-selection) fields. This is also
populated for the C<component>, C<version>, C<target_milestone>, and C<keywords>
fields, but not for the C<product> field (you must use
L<Product.get_accessible_products|Bugzilla::WebService::Product/get_accessible_products>
for that.

For fields that aren't select-type fields, this will simply be an empty
array.

Each hash has the following keys:

=over 

=item C<name>

C<string> The actual value--this is what you would specify for this
field in L</create>, etc.

=item C<sort_key>

C<int> Values, when displayed in a list, are sorted first by this integer
and then secondly by their name.

=item C<sortkey>

B<DEPRECATED> - Use C<sort_key> instead.

=item C<visibility_values>

If C<value_field> is defined for this field, then this value is only shown
if the C<value_field> is set to one of the values listed in this array.
Note that for per-product fields, C<value_field> is set to C<'product'>
and C<visibility_values> will reflect which product(s) this value appears in.

=item C<is_active>

C<boolean> This value is defined only for certain product specific fields
such as version, target_milestone or component. When true, the value is active,
otherwise the value is not active.

=item C<description>

C<string> The description of the value. This item is only included for the
C<keywords> field.

=item C<is_open>

C<boolean> For C<bug_status> values, determines whether this status
specifies that the bug is "open" (true) or "closed" (false). This item
is only included for the C<bug_status> field.

=item C<can_change_to>

For C<bug_status> values, this is an array of hashes that determines which
statuses you can transition to from this status. (This item is only included
for the C<bug_status> field.)

Each hash contains the following items:

=over

=item C<name>

the name of the new status

=item C<comment_required>

this C<boolean> True if a comment is required when you change a bug into
this status using this transition.

=back

=back

=back

=item B<Errors>

=over

=item 51 (Invalid Field Name or Id)

You specified an invalid field name or id.

=back

=item B<History>

=over

=item Added in Bugzilla B<3.6>.

=item The C<is_mandatory> return value was added in Bugzilla B<4.0>.

=item C<sortkey> was renamed to C<sort_key> in Bugzilla B<4.2>.

=item C<is_active> return key for C<values> was added in Bugzilla B<4.4>.

=item REST API call added in Bugzilla B<5.0>

=back

=back

=head2 legal_values

B<DEPRECATED> - Use L</fields> instead.

=over

=item B<Description>

Tells you what values are allowed for a particular field.

=item B<REST>

To get information on the values for a field based on field name:

GET /rest/field/bug/<field_name>/values

To get information based on field name and a specific product:

GET /rest/field/bug/<field_name>/<product_id>/values

The returned data format is the same as below.

=item B<Params>

=over

=item C<field> - The name of the field you want information about.
This should be the same as the name you would use in L</create>, below.

=item C<product_id> - If you're picking a product-specific field, you have
to specify the id of the product you want the values for.

=back

=item B<Returns> 

C<values> - An array of strings: the legal values for this field.
The values will be sorted as they normally would be in Bugzilla.

=item B<Errors>

=over

=item 106 (Invalid Product)

You were required to specify a product, and either you didn't, or you
specified an invalid product (or a product that you can't access).

=item 108 (Invalid Field Name)

You specified a field that doesn't exist or isn't a drop-down field.

=back

=item B<History>

=over

=item REST API call added in Bugzilla B<5.0>.

=back

=back

=head1 Bug Information

=head2 attachments

B<EXPERIMENTAL>

=over

=item B<Description>

It allows you to get data about attachments, given a list of bugs
and/or attachment ids.

B<Note>: Private attachments will only be returned if you are in the 
insidergroup or if you are the submitter of the attachment.

=item B<REST>

To get all current attachments for a bug:

GET /rest/bug/<bug_id>/attachment

To get a specific attachment based on attachment ID:

GET /rest/bug/attachment/<attachment_id>

The returned data format is the same as below.

=item B<Params>

B<Note>: At least one of C<ids> or C<attachment_ids> is required.

=over

=item C<ids>

See the description of the C<ids> parameter in the L</get> method.

=item C<attachment_ids>

C<array> An array of integer attachment ids.

=back

Also accepts the L<include_fields|Bugzilla::WebService/include_fields>,
and L<exclude_fields|Bugzilla::WebService/exclude_fields> arguments.

=item B<Returns>

A hash containing two elements: C<bugs> and C<attachments>. The return
value looks like this:

 {
     bugs => {
         1345 => [
             { (attachment) },
             { (attachment) }
         ],
         9874 => [
             { (attachment) },
             { (attachment) }
         ],
     },

     attachments => {
         234 => { (attachment) },
         123 => { (attachment) },
     }
 }

The attachments of any bugs that you specified in the C<ids> argument in
input are returned in C<bugs> on output. C<bugs> is a hash that has integer
bug IDs for keys and the values are arrayrefs that contain hashes as attachments.
(Fields for attachments are described below.)

For any attachments that you specified directly in C<attachment_ids>, they
are returned in C<attachments> on output. This is a hash where the attachment
ids point directly to hashes describing the individual attachment.

The fields for each attachment (where it says C<(attachment)> in the
diagram above) are:

=over

=item C<data>

C<base64> The raw data of the attachment, encoded as Base64.

=item C<size>

C<int> The length (in bytes) of the attachment.

=item C<creation_time>

C<dateTime> The time the attachment was created.

=item C<last_change_time>

C<dateTime> The last time the attachment was modified.

=item C<id>

C<int> The numeric id of the attachment.

=item C<bug_id>

C<int> The numeric id of the bug that the attachment is attached to.

=item C<file_name>

C<string> The file name of the attachment.

=item C<summary>

C<string> A short string describing the attachment.

=item C<content_type>

C<string> The MIME type of the attachment.

=item C<is_private>

C<boolean> True if the attachment is private (only visible to a certain
group called the "insidergroup"), False otherwise.

=item C<is_obsolete>

C<boolean> True if the attachment is obsolete, False otherwise.

=item C<is_patch>

C<boolean> True if the attachment is a patch, False otherwise.

=item C<creator>

C<string> The login name of the user that created the attachment.

=item C<flags>

An array of hashes containing the information about flags currently set
for each attachment. Each flag hash contains the following items:

=over

=item C<id> 

C<int> The id of the flag.

=item C<name>

C<string> The name of the flag.

=item C<type_id>

C<int> The type id of the flag.

=item C<creation_date>

C<dateTime> The timestamp when this flag was originally created.

=item C<modification_date>

C<dateTime> The timestamp when the flag was last modified.

=item C<status>

C<string> The current status of the flag.

=item C<setter>

C<string> The login name of the user who created or last modified the flag.

=item C<requestee>

C<string> The login name of the user this flag has been requested to be granted or denied.
Note, this field is only returned if a requestee is set.

=back

=back

=item B<Errors>

This method can throw all the same errors as L</get>. In addition,
it can also throw the following error:

=over

=item 304 (Auth Failure, Attachment is Private)

You specified the id of a private attachment in the C<attachment_ids>
argument, and you are not in the "insider group" that can see
private attachments.

=back

=item B<History>

=over

=item Added in Bugzilla B<3.6>.

=item In Bugzilla B<4.0>, the C<attacher> return value was renamed to
C<creator>.

=item In Bugzilla B<4.0>, the C<description> return value was renamed to
C<summary>.

=item The C<data> return value was added in Bugzilla B<4.0>.

=item In Bugzilla B<4.2>, the C<is_url> return value was removed
(this attribute no longer exists for attachments).

=item The C<size> return value was added in Bugzilla B<4.4>.

=item The C<flags> array was added in Bugzilla B<4.4>.

=item REST API call added in Bugzilla B<5.0>.

=back

=back


=head2 comments

B<STABLE>

=over

=item B<Description>

This allows you to get data about comments, given a list of bugs 
and/or comment ids.

=item B<REST>

To get all comments for a particular bug using the bug ID or alias:

GET /rest/bug/<id_or_alias>/comment

To get a specific comment based on the comment ID:

GET /rest/bug/comment/<comment_id>

The returned data format is the same as below.

=item B<Params>

B<Note>: At least one of C<ids> or C<comment_ids> is required.

In addition to the parameters below, this method also accepts the
standard L<include_fields|Bugzilla::WebService/include_fields> and
L<exclude_fields|Bugzilla::WebService/exclude_fields> arguments.

=over

=item C<ids>

C<array> An array that can contain both bug IDs and bug aliases.
All of the comments (that are visible to you) will be returned for the
specified bugs.

=item C<comment_ids> 

C<array> An array of integer comment_ids. These comments will be
returned individually, separate from any other comments in their
respective bugs.

=item C<new_since>

C<dateTime> If specified, the method will only return comments I<newer>
than this time. This only affects comments returned from the C<ids>
argument. You will always be returned all comments you request in the
C<comment_ids> argument, even if they are older than this date.

=back

=item B<Returns>

Two items are returned:

=over

=item C<bugs>

This is used for bugs specified in C<ids>. This is a hash,
where the keys are the numeric ids of the bugs, and the value is
a hash with a single key, C<comments>, which is an array of comments.
(The format of comments is described below.)

Note that any individual bug will only be returned once, so if you
specify an id multiple times in C<ids>, it will still only be
returned once.

=item C<comments>

Each individual comment requested in C<comment_ids> is returned here,
in a hash where the numeric comment id is the key, and the value
is the comment. (The format of comments is described below.) 

=back

A "comment" as described above is a hash that contains the following
keys:

=over

=item id

C<int> The globally unique ID for the comment.

=item bug_id

C<int> The ID of the bug that this comment is on.

=item attachment_id

C<int> If the comment was made on an attachment, this will be the
ID of that attachment. Otherwise it will be null.

=item count

C<int> The number of the comment local to the bug. The Description is 0,
comments start with 1.

=item text

C<string> The actual text of the comment.

=item creator

C<string> The login name of the comment's author.

=item time

C<dateTime> The time (in Bugzilla's timezone) that the comment was added.

=item creation_time

C<dateTime> This is exactly same as the C<time> key. Use this field instead of
C<time> for consistency with other methods including L</get> and L</attachments>.
For compatibility, C<time> is still usable. However, please note that C<time>
may be deprecated and removed in a future release.

=item is_private

C<boolean> True if this comment is private (only visible to a certain
group called the "insidergroup"), False otherwise.

=back

=item B<Errors>

This method can throw all the same errors as L</get>. In addition,
it can also throw the following errors:

=over

=item 110 (Comment Is Private)

You specified the id of a private comment in the C<comment_ids>
argument, and you are not in the "insider group" that can see
private comments.

=item 111 (Invalid Comment ID)

You specified an id in the C<comment_ids> argument that is invalid--either
you specified something that wasn't a number, or there is no comment with
that id.

=back

=item B<History>

=over

=item Added in Bugzilla B<3.4>.

=item C<attachment_id> was added to the return value in Bugzilla B<3.6>.

=item In Bugzilla B<4.0>, the C<author> return value was renamed to
C<creator>.

=item C<count> was added to the return value in Bugzilla B<4.4>.

=item C<creation_time> was added in Bugzilla B<4.4>.

=item REST API call added in Bugzilla B<5.0>.

=back

=back


=head2 get

B<STABLE>

=over

=item B<Description>

Gets information about particular bugs in the database.

=item B<REST>

To get information about a particular bug using its ID or alias:

GET /rest/bug/<id_or_alias>

The returned data format is the same as below.

=item B<Params>

In addition to the parameters below, this method also accepts the
standard L<include_fields|Bugzilla::WebService/include_fields> and
L<exclude_fields|Bugzilla::WebService/exclude_fields> arguments.

=over

=item C<ids>

An array of numbers and strings.

If an element in the array is entirely numeric, it represents a bug_id
from the Bugzilla database to fetch. If it contains any non-numeric 
characters, it is considered to be a bug alias instead, and the bug with 
that alias will be loaded. 

=item C<permissive> B<EXPERIMENTAL>

C<boolean> Normally, if you request any inaccessible or invalid bug ids,
Bug.get will throw an error. If this parameter is True, instead of throwing an
error we return an array of hashes with a C<id>, C<faultString> and C<faultCode> 
for each bug that fails, and return normal information for the other bugs that 
were accessible.

=back

=item B<Returns>

Two items are returned:

=over

=item C<bugs>

An array of hashes that contains information about the bugs with 
the valid ids. Each hash contains the following items:

These fields are returned by default or by specifying C<_default>
in C<include_fields>.

=over

=item C<actual_time>

C<double> The total number of hours that this bug has taken (so far).

If you are not in the time-tracking group, this field will not be included
in the return value.

=item C<alias>

C<array> of C<string>s The unique aliases of this bug. An empty array will be
returned if this bug has no aliases.

=item C<assigned_to>

C<string> The login name of the user to whom the bug is assigned.

=item C<assigned_to_detail> 

C<hash> A hash containing detailed user information for the assigned_to. To see the 
keys included in the user detail hash, see below.

=item C<blocks>

C<array> of C<int>s. The ids of bugs that are "blocked" by this bug.

=item C<cc>

C<array> of C<string>s. The login names of users on the CC list of this
bug.

=item C<cc_detail>

C<array> of hashes containing detailed user information for each of the cc list
members. To see the keys included in the user detail hash, see below.

=item C<classification>

C<string> The name of the current classification the bug is in.

=item C<component>

C<string> The name of the current component of this bug.

=item C<creation_time>

C<dateTime> When the bug was created.

=item C<creator>

C<string> The login name of the person who filed this bug (the reporter).

=item C<creator_detail> 

C<hash> A hash containing detailed user information for the creator. To see the 
keys included in the user detail hash, see below.

=item C<deadline>

C<string> The day that this bug is due to be completed, in the format
C<YYYY-MM-DD>.

=item C<depends_on>

C<array> of C<int>s. The ids of bugs that this bug "depends on".

=item C<dupe_of>

C<int> The bug ID of the bug that this bug is a duplicate of. If this bug 
isn't a duplicate of any bug, this will be null.

=item C<estimated_time>

C<double> The number of hours that it was estimated that this bug would
take.

If you are not in the time-tracking group, this field will not be included
in the return value.

=item C<flags>

An array of hashes containing the information about flags currently set
for the bug. Each flag hash contains the following items:

=over

=item C<id> 

C<int> The id of the flag.

=item C<name>

C<string> The name of the flag.

=item C<type_id>

C<int> The type id of the flag.

=item C<creation_date>

C<dateTime> The timestamp when this flag was originally created.

=item C<modification_date>

C<dateTime> The timestamp when the flag was last modified.

=item C<status>

C<string> The current status of the flag.

=item C<setter>

C<string> The login name of the user who created or last modified the flag.

=item C<requestee>

C<string> The login name of the user this flag has been requested to be granted or denied.
Note, this field is only returned if a requestee is set.

=back

=item C<groups>

C<array> of C<string>s. The names of all the groups that this bug is in.

=item C<id>

C<int> The unique numeric id of this bug.

=item C<is_cc_accessible>

C<boolean> If true, this bug can be accessed by members of the CC list,
even if they are not in the groups the bug is restricted to.

=item C<is_confirmed>

C<boolean> True if the bug has been confirmed. Usually this means that
the bug has at some point been moved out of the C<UNCONFIRMED> status
and into another open status.

=item C<is_open>

C<boolean> True if this bug is open, false if it is closed.

=item C<is_creator_accessible>

C<boolean> If true, this bug can be accessed by the creator (reporter)
of the bug, even if they are not a member of the groups the bug
is restricted to.

=item C<keywords>

C<array> of C<string>s. Each keyword that is on this bug.

=item C<last_change_time>

C<dateTime> When the bug was last changed.

=item C<op_sys>

C<string> The name of the operating system that the bug was filed against.

=item C<platform>

C<string> The name of the platform (hardware) that the bug was filed against.

=item C<priority>

C<string> The priority of the bug.

=item C<product>

C<string> The name of the product this bug is in.

=item C<qa_contact>

C<string> The login name of the current QA Contact on the bug.

=item C<qa_contact_detail>

C<hash> A hash containing detailed user information for the qa_contact. To see the
keys included in the user detail hash, see below.

=item C<remaining_time>

C<double> The number of hours of work remaining until work on this bug
is complete.

If you are not in the time-tracking group, this field will not be included
in the return value.

=item C<resolution>

C<string> The current resolution of the bug, or an empty string if the bug
is open.

=item C<see_also>

B<UNSTABLE>

C<array> of C<string>s. The URLs in the See Also field on the bug.

=item C<severity>

C<string> The current severity of the bug.

=item C<status>

C<string> The current status of the bug.

=item C<summary>

C<string> The summary of this bug.

=item C<target_milestone>

C<string> The milestone that this bug is supposed to be fixed by, or for
closed bugs, the milestone that it was fixed for.

=item C<update_token>

C<string> The token that you would have to pass to the F<process_bug.cgi>
page in order to update this bug. This changes every time the bug is
updated.

This field is not returned to logged-out users.

=item C<url>

B<UNSTABLE>

C<string> A URL that demonstrates the problem described in
the bug, or is somehow related to the bug report.

=item C<version>

C<string> The version the bug was reported against.

=item C<whiteboard>

C<string> The value of the "status whiteboard" field on the bug.

=item I<custom fields>

Every custom field in this installation will also be included in the
return value. Most fields are returned as C<string>s. However, some
field types have different return values.

Normally custom fields are returned by default similar to normal bug
fields or you can specify only custom fields by using C<_custom> in
C<include_fields>.

=over

=item Bug ID Fields - C<int>

=item Multiple-Selection Fields - C<array> of C<string>s.

=item Date/Time Fields - C<dateTime>

=back 

=item I<user detail hashes> 

Each user detail hash contains the following items:

=over

=item C<id>

C<int> The user id for this user.

=item C<real_name>

C<string> The 'real' name for this user, if any.

=item C<name>

C<string> The user's Bugzilla login.

=item C<email>

C<string> The user's email address. Currently this is the same value as the name.

=back

=back

These fields are returned only by specifying "_extra" or the field name in "include_fields".

=over

=item C<tags>

C<array> of C<string>s.  Each array item is a tag name.

Note that tags are personal to the currently logged in user.

=back

=item C<faults> B<EXPERIMENTAL>

An array of hashes that contains invalid bug ids with error messages
returned for them. Each hash contains the following items:

=over

=item id

C<int> The numeric bug_id of this bug.

=item faultString 

C<string> This will only be returned for invalid bugs if the C<permissive>
argument was set when calling Bug.get, and it is an error indicating that 
the bug id was invalid.

=item faultCode

C<int> This will only be returned for invalid bugs if the C<permissive>
argument was set when calling Bug.get, and it is the error code for the 
invalid bug error.

=back

=back

=item B<Errors>

=over

=item 100 (Invalid Bug Alias)

If you specified an alias and there is no bug with that alias.

=item 101 (Invalid Bug ID)

The bug_id you specified doesn't exist in the database.

=item 102 (Access Denied)

You do not have access to the bug_id you specified.

=back

=item B<History>

=over

=item C<permissive> argument added to this method's params in Bugzilla B<3.4>.

=item The following properties were added to this method's return values
in Bugzilla B<3.4>:

=over

=item For C<bugs>

=over

=item assigned_to

=item component 

=item dupe_of

=item is_open

=item priority

=item product

=item resolution

=item severity

=item status

=back 

=item C<faults>

=back 

=item In Bugzilla B<4.0>, the following items were added to the C<bugs>
return value: C<blocks>, C<cc>, C<classification>, C<creator>,
C<deadline>, C<depends_on>, C<estimated_time>, C<is_cc_accessible>, 
C<is_confirmed>, C<is_creator_accessible>, C<groups>, C<keywords>,
C<op_sys>, C<platform>, C<qa_contact>, C<remaining_time>, C<see_also>,
C<target_milestone>, C<update_token>, C<url>, C<version>, C<whiteboard>,
and all custom fields.

=item The C<flags> array was added in Bugzilla B<4.4>.

=item The C<actual_time> item was added to the C<bugs> return value
in Bugzilla B<4.4>.

=item REST API call added in Bugzilla B<5.0>.

=item In Bugzilla B<5.0>, the following items were added to the bugs return value: C<assigned_to_detail>, C<creator_detail>, C<qa_contact_detail>. 

=back

=back

=head2 history

B<EXPERIMENTAL>

=over

=item B<Description>

Gets the history of changes for particular bugs in the database.

=item B<REST>

To get the history for a specific bug ID:

GET /rest/bug/<bug_id>/history

The returned data format will be the same as below.

=item B<Params>

=over

=item C<ids>

An array of numbers and strings.

If an element in the array is entirely numeric, it represents a bug_id 
from the Bugzilla database to fetch. If it contains any non-numeric 
characters, it is considered to be a bug alias instead, and the data bug 
with that alias will be loaded.

=item C<new_since>

C<dateTime> If specified, the method will only return changes I<newer>
than this time.

=back

=item B<Returns>

A hash containing a single element, C<bugs>. This is an array of hashes,
containing the following keys:

=over

=item id

C<int> The numeric id of the bug.

=item alias

C<array> of C<string>s The unique aliases of this bug. An empty array will be
returned if this bug has no aliases.

=item history

C<array> An array of hashes, each hash having the following keys:

=over

=item when

C<dateTime> The date the bug activity/change happened.

=item who

C<string> The login name of the user who performed the bug change.

=item changes

C<array> An array of hashes which contain all the changes that happened
to the bug at this time (as specified by C<when>). Each hash contains 
the following items:

=over

=item field_name

C<string> The name of the bug field that has changed.

=item removed

C<string> The previous value of the bug field which has been deleted 
by the change.

=item added

C<string> The new value of the bug field which has been added by the change.

=item attachment_id

C<int> The id of the attachment that was changed. This only appears if 
the change was to an attachment, otherwise C<attachment_id> will not be
present in this hash.

=back

=back

=back

=item B<Errors>

The same as L</get>.

=item B<History>

=over

=item Added in Bugzilla B<3.4>.

=item Field names returned by the C<field_name> field changed to be
consistent with other methods. Since Bugzilla B<4.4>, they now match
names used by L<Bug.update|/"update"> for consistency.

=item REST API call added Bugzilla B<5.0>.

=item Added C<new_since> parameter if Bugzilla B<5.0>.

=back

=back

=head2 possible_duplicates

B<UNSTABLE>

=over

=item B<Description>

Allows a user to find possible duplicate bugs based on a set of keywords
such as a user may use as a bug summary. Optionally the search can be
narrowed down to specific products.

=item B<Params>

=over

=item C<summary> (string) B<Required> - A string of keywords defining
the type of bug you are trying to report.

=item C<products> (array) - One or more product names to narrow the
duplicate search to. If omitted, all bugs are searched.

=back

=item B<Returns>

The same as L</get>.

Note that you will only be returned information about bugs that you
can see. Bugs that you can't see will be entirely excluded from the
results. So, if you want to see private bugs, you will have to first 
log in and I<then> call this method.

=item B<Errors>

=over

=item 50 (Param Required)

You must specify a value for C<summary> containing a string of keywords to 
search for duplicates.

=back

=item B<History>

=over

=item Added in Bugzilla B<4.0>.

=item The C<product> parameter has been renamed to C<products> in
Bugzilla B<5.0>.

=back

=back

=head2 search

B<UNSTABLE>

=over

=item B<Description>

Allows you to search for bugs based on particular criteria.

=item <REST>

To search for bugs:

GET /bug

The URL parameters and the returned data format are the same as below.

=item B<Params>

Unless otherwise specified in the description of a parameter, bugs are
returned if they match I<exactly> the criteria you specify in these 
parameters. That is, we don't match against substrings--if a bug is in
the "Widgets" product and you ask for bugs in the "Widg" product, you
won't get anything.

Criteria are joined in a logical AND. That is, you will be returned
bugs that match I<all> of the criteria, not bugs that match I<any> of
the criteria.

Each parameter can be either the type it says, or an array of the types
it says. If you pass an array, it means "Give me bugs with I<any> of
these values." For example, if you wanted bugs that were in either
the "Foo" or "Bar" products, you'd pass:

 product => ['Foo', 'Bar']

Some Bugzillas may treat your arguments case-sensitively, depending
on what database system they are using. Most commonly, though, Bugzilla is
not case-sensitive with the arguments passed (because MySQL is the
most-common database to use with Bugzilla, and MySQL is not case sensitive).

In addition to the fields listed below, you may also use criteria that
is similar to what is used in the Advanced Search screen of the Bugzilla
UI. This includes fields specified by C<Search by Change History> and
C<Custom Search>. The easiest way to determine what the field names are and what
format Bugzilla expects, is to first construct your query using the
Advanced Search UI, execute it and use the query parameters in they URL
as your key/value pairs for the WebService call. With REST, you can
just reuse the query parameter portion in the REST call itself.

=over

=item C<alias>

C<array> of C<string>s The unique aliases of this bug. An empty array will be
returned if this bug has no aliases.

=item C<assigned_to>

C<string> The login name of a user that a bug is assigned to.

=item C<component>

C<string> The name of the Component that the bug is in. Note that
if there are multiple Components with the same name, and you search
for that name, bugs in I<all> those Components will be returned. If you
don't want this, be sure to also specify the C<product> argument.

=item C<creation_time>

C<dateTime> Searches for bugs that were created at this time or later.
May not be an array.

=item C<creator>

C<string> The login name of the user who created the bug.

You can also pass this argument with the name C<reporter>, for
backwards compatibility with older Bugzillas.

=item C<id>

C<int> The numeric id of the bug.

=item C<last_change_time>

C<dateTime> Searches for bugs that were modified at this time or later.
May not be an array.

=item C<limit>

C<int> Limit the number of results returned to C<int> records. If the limit
is more than zero and higher than the maximum limit set by the administrator,
then the maximum limit will be used instead. If you set the limit equal to zero,
then all matching results will be returned instead.

=item C<offset>

C<int> Used in conjunction with the C<limit> argument, C<offset> defines
the starting position for the search. For example, given a search that
would return 100 bugs, setting C<limit> to 10 and C<offset> to 10 would return
bugs 11 through 20 from the set of 100.

=item C<op_sys>

C<string> The "Operating System" field of a bug.

=item C<platform>

C<string> The Platform (sometimes called "Hardware") field of a bug.

=item C<priority>

C<string> The Priority field on a bug.

=item C<product>

C<string> The name of the Product that the bug is in.

=item C<resolution>

C<string> The current resolution--only set if a bug is closed. You can
find open bugs by searching for bugs with an empty resolution.

=item C<severity>

C<string> The Severity field on a bug.

=item C<status>

C<string> The current status of a bug (not including its resolution,
if it has one, which is a separate field above).

=item C<summary>

C<string> Searches for substrings in the single-line Summary field on
bugs. If you specify an array, then bugs whose summaries match I<any> of the
passed substrings will be returned.

Note that unlike searching in the Bugzilla UI, substrings are not split
on spaces. So searching for C<foo bar> will match "This is a foo bar"
but not "This foo is a bar". C<['foo', 'bar']>, would, however, match
the second item.

=item C<tags>

C<string> Searches for a bug with the specified tag.  If you specify an
array, then any bugs that match I<any> of the tags will be returned.

Note that tags are personal to the currently logged in user.

=item C<target_milestone>

C<string> The Target Milestone field of a bug. Note that even if this
Bugzilla does not have the Target Milestone field enabled, you can
still search for bugs by Target Milestone. However, it is likely that
in that case, most bugs will not have a Target Milestone set (it
defaults to "---" when the field isn't enabled).

=item C<qa_contact>

C<string> The login name of the bug's QA Contact. Note that even if
this Bugzilla does not have the QA Contact field enabled, you can
still search for bugs by QA Contact (though it is likely that no bug
will have a QA Contact set, if the field is disabled).

=item C<url>

C<string> The "URL" field of a bug.

=item C<version>

C<string> The Version field of a bug.

=item C<whiteboard>

C<string> Search the "Status Whiteboard" field on bugs for a substring.
Works the same as the C<summary> field described above, but searches the
Status Whiteboard field.

=item C<quicksearch>

C<string> Search for bugs using quicksearch syntax.

=back

=item B<Returns>

The same as L</get>.

Note that you will only be returned information about bugs that you
can see. Bugs that you can't see will be entirely excluded from the
results. So, if you want to see private bugs, you will have to first 
log in and I<then> call this method.

=item B<Errors>

If you specify an invalid value for a particular field, you just won't
get any results for that value.

=over

=item 1000 (Parameters Required)

You may not search without any search terms.

=back

=item B<History>

=over

=item Added in Bugzilla B<3.4>.

=item Searching by C<votes> was removed in Bugzilla B<4.0>.

=item The C<reporter> input parameter was renamed to C<creator>
in Bugzilla B<4.0>.

=item In B<4.2.6> and newer, added the ability to return all results if
C<limit> is set equal to zero. Otherwise maximum results returned are limited
by system configuration.

=item REST API call added in Bugzilla B<5.0>.

=item Updated to allow for full search capability similar to the Bugzilla UI
in Bugzilla B<5.0>.

=item Updated to allow quicksearch capability in Bugzilla B<5.0>.

=back

=back


=head1 Bug Creation and Modification

=head2 create

B<STABLE>

=over

=item B<Description>

This allows you to create a new bug in Bugzilla. If you specify any
invalid fields, an error will be thrown stating which field is invalid.
If you specify any fields you are not allowed to set, they will just be
set to their defaults or ignored.

You cannot currently set all the items here that you can set on enter_bug.cgi.

The WebService interface may allow you to set things other than those listed
here, but realize that anything undocumented is B<UNSTABLE> and will very
likely change in the future.

=item B<REST>

To create a new bug in Bugzilla:

POST /rest/bug

The params to include in the POST body as well as the returned data format,
are the same as below.

=item B<Params>

Some params must be set, or an error will be thrown. These params are
marked B<Required>.

Some parameters can have defaults set in Bugzilla, by the administrator.
If these parameters have defaults set, you can omit them. These parameters
are marked B<Defaulted>.

Clients that want to be able to interact uniformly with multiple
Bugzillas should always set both the params marked B<Required> and those 
marked B<Defaulted>, because some Bugzillas may not have defaults set
for B<Defaulted> parameters, and then this method will throw an error
if you don't specify them.

The descriptions of the parameters below are what they mean when Bugzilla is
being used to track software bugs. They may have other meanings in some
installations.

=over

=item C<product> (string) B<Required> - The name of the product the bug
is being filed against.

=item C<component> (string) B<Required> - The name of a component in the
product above.

=item C<summary> (string) B<Required> - A brief description of the bug being
filed.

=item C<version> (string) B<Required> - A version of the product above;
the version the bug was found in.

=item C<description> (string) B<Defaulted> - The initial description for 
this bug. Some Bugzilla installations require this to not be blank.

=item C<op_sys> (string) B<Defaulted> - The operating system the bug was
discovered on.

=item C<platform> (string) B<Defaulted> - What type of hardware the bug was
experienced on.

=item C<priority> (string) B<Defaulted> - What order the bug will be fixed
in by the developer, compared to the developer's other bugs.

=item C<severity> (string) B<Defaulted> - How severe the bug is.

=item C<alias> (array) - A brief alias for the bug that can be used
instead of a bug number when accessing this bug. Must be unique in
all of this Bugzilla.

=item C<assigned_to> (username) - A user to assign this bug to, if you
don't want it to be assigned to the component owner.

=item C<cc> (array) - An array of usernames to CC on this bug.

=item C<comment_is_private> (boolean) - If set to true, the description
is private, otherwise it is assumed to be public.

=item C<groups> (array) - An array of group names to put this
bug into. You can see valid group names on the Permissions
tab of the Preferences screen, or, if you are an administrator,
in the Groups control panel.
If you don't specify this argument, then the bug will be added into
all the groups that are set as being "Default" for this product. (If
you want to avoid that, you should specify C<groups> as an empty array.)

=item C<qa_contact> (username) - If this installation has QA Contacts
enabled, you can set the QA Contact here if you don't want to use
the component's default QA Contact.

=item C<status> (string) - The status that this bug should start out as.
Note that only certain statuses can be set on bug creation.

=item C<resolution> (string) - If you are filing a closed bug, then
you will have to specify a resolution. You cannot currently specify
a resolution of C<DUPLICATE> for new bugs, though. That must be done
with L</update>.

=item C<target_milestone> (string) - A valid target milestone for this
product.

=item C<flags>

C<array> An array of hashes with flags to add to the bug. To create a flag,
at least the status and the type_id or name must be provided. An optional
requestee can be passed if the flag type is requestable to a specific user.

=over

=item C<name>

C<string> The name of the flag type.

=item C<type_id>

C<int> The internal flag type id.

=item C<status>

C<string> The flags new status (i.e. "?", "+", "-" or "X" to clear a flag).

=item C<requestee>

C<string> The login of the requestee if the flag type is requestable to a specific user.

=back

=back

In addition to the above parameters, if your installation has any custom
fields, you can set them just by passing in the name of the field and
its value as a string.

=item B<Returns>

A hash with one element, C<id>. This is the id of the newly-filed bug.

=item B<Errors>

=over

=item 51 (Invalid Object)

You specified a field value that is invalid. The error message will have
more details.

=item 103 (Invalid Alias)

The alias you specified is invalid for some reason. See the error message
for more details.

=item 104 (Invalid Field)

One of the drop-down fields has an invalid value, or a value entered in a
text field is too long. The error message will have more detail.

=item 105 (Invalid Component)

You didn't specify a component.

=item 106 (Invalid Product)

Either you didn't specify a product, this product doesn't exist, or
you don't have permission to enter bugs in this product.

=item 107 (Invalid Summary)

You didn't specify a summary for the bug.

=item 116 (Dependency Loop)

You specified values in the C<blocks> or C<depends_on> fields
that would cause a circular dependency between bugs.

=item 120 (Group Restriction Denied)

You tried to restrict the bug to a group which does not exist, or which
you cannot use with this product.

=item 129 (Flag Status Invalid)

The flag status is invalid.

=item 130 (Flag Modification Denied)

You tried to request, grant, or deny a flag but only a user with the required
permissions may make the change.

=item 131 (Flag not Requestable from Specific Person)

You can't ask a specific person for the flag.

=item 133 (Flag Type not Unique)

The flag type specified matches several flag types. You must specify
the type id value to update or add a flag.

=item 134 (Inactive Flag Type)

The flag type is inactive and cannot be used to create new flags.

=item 504 (Invalid User)

Either the QA Contact, Assignee, or CC lists have some invalid user
in them. The error message will have more details.

=back

=item B<History>

=over

=item Before B<3.0.4>, parameters marked as B<Defaulted> were actually
B<Required>, due to a bug in Bugzilla.

=item The C<groups> argument was added in Bugzilla B<4.0>. Before
Bugzilla 4.0, bugs were only added into Mandatory groups by this
method. Since Bugzilla B<4.0.2>, passing an illegal group name will
throw an error. In Bugzilla 4.0 and 4.0.1, illegal group names were
silently ignored.

=item The C<comment_is_private> argument was added in Bugzilla B<4.0>.
Before Bugzilla 4.0, you had to use the undocumented C<commentprivacy>
argument.

=item Error 116 was added in Bugzilla B<4.0>. Before that, dependency
loop errors had a generic code of C<32000>.

=item The ability to file new bugs with a C<resolution> was added in
Bugzilla B<4.4>.

=item REST API call added in Bugzilla B<5.0>.

=back

=back


=head2 add_attachment

B<STABLE>

=over

=item B<Description>

This allows you to add an attachment to a bug in Bugzilla.

=item B<REST>

To create attachment on a current bug:

POST /rest/bug/<bug_id>/attachment

The params to include in the POST body, as well as the returned
data format are the same as below. The C<ids> param will be
overridden as it it pulled from the URL path.

=item B<Params>

=over

=item C<ids>

B<Required> C<array> An array of ints and/or strings--the ids
or aliases of bugs that you want to add this attachment to.
The same attachment and comment will be added to all
these bugs.

=item C<data>

B<Required> C<base64> or C<string> The content of the attachment.
If the content of the attachment is not ASCII text, you must encode
it in base64 and declare it as the C<base64> type.

=item C<file_name>

B<Required> C<string> The "file name" that will be displayed
in the UI for this attachment.

=item C<summary>

B<Required> C<string> A short string describing the
attachment.

=item C<content_type>

B<Required> C<string> The MIME type of the attachment, like
C<text/plain> or C<image/png>.

=item C<comment>

C<string> A comment to add along with this attachment.

=item C<is_patch>

C<boolean> True if Bugzilla should treat this attachment as a patch.
If you specify this, you do not need to specify a C<content_type>.
The C<content_type> of the attachment will be forced to C<text/plain>.

Defaults to False if not specified.

=item C<is_private>

C<boolean> True if the attachment should be private (restricted
to the "insidergroup"), False if the attachment should be public.

Defaults to False if not specified.

=item C<flags>

C<array> An array of hashes with flags to add to the attachment. to create a flag,
at least the status and the type_id or name must be provided. An optional requestee
can be passed if the flag type is requestable to a specific user.

=over

=item C<name>

C<string> The name of the flag type.

=item C<type_id>

C<int> The internal flag type id.

=item C<status>

C<string> The flags new status (i.e. "?", "+", "-" or "X" to clear a flag).

=item C<requestee>

C<string> The login of the requestee if the flag type is requestable to a specific user.

=back

=back

=item B<Returns>

A single item C<ids>, which contains an array of the
attachment id(s) created.

=item B<Errors>

This method can throw all the same errors as L</get>, plus:

=over

=item 129 (Flag Status Invalid)

The flag status is invalid.

=item 130 (Flag Modification Denied)

You tried to request, grant, or deny a flag but only a user with the required
permissions may make the change.

=item 131 (Flag not Requestable from Specific Person)

You can't ask a specific person for the flag.

=item 133 (Flag Type not Unique)

The flag type specified matches several flag types. You must specify
the type id value to update or add a flag.

=item 134 (Inactive Flag Type)

The flag type is inactive and cannot be used to create new flags.

=item 600 (Attachment Too Large)

You tried to attach a file that was larger than Bugzilla will accept.

=item 601 (Invalid MIME Type)

You specified a C<content_type> argument that was blank, not a valid
MIME type, or not a MIME type that Bugzilla accepts for attachments.

=item 603 (File Name Not Specified)

You did not specify a valid for the C<file_name> argument.

=item 604 (Summary Required)

You did not specify a value for the C<summary> argument.

=item 606 (Empty Data)

You set the "data" field to an empty string.

=back

=item B<History>

=over

=item Added in Bugzilla B<4.0>.

=item The C<is_url> parameter was removed in Bugzilla B<4.2>.

=item The return value has changed in Bugzilla B<4.4>.

=item REST API call added in Bugzilla B<5.0>.

=back

=back


=head2 update_attachment

B<UNSTABLE>

=over

=item B<Description>

This allows you to update attachment metadata in Bugzilla.

=item B<REST>

To update attachment metadata on a current attachment:

PUT /rest/bug/attachment/<attach_id>

The params to include in the POST body, as well as the returned
data format are the same as below. The C<ids> param will be
overridden as it it pulled from the URL path.

=item B<Params>

=over

=item C<ids>

B<Required> C<array> An array of integers -- the ids of the attachments you
want to update.

=item C<file_name>

C<string> The "file name" that will be displayed
in the UI for this attachment.

=item C<summary>

C<string> A short string describing the
attachment.

=item C<comment>

C<string> An optional comment to add to the attachment's bug.

=item C<content_type>

C<string> The MIME type of the attachment, like
C<text/plain> or C<image/png>.

=item C<is_patch>

C<boolean> True if Bugzilla should treat this attachment as a patch.
If you specify this, you do not need to specify a C<content_type>.
The C<content_type> of the attachment will be forced to C<text/plain>.

=item C<is_private>

C<boolean> True if the attachment should be private (restricted
to the "insidergroup"), False if the attachment should be public.

=item C<is_obsolete>

C<boolean> True if the attachment is obsolete, False otherwise.

=item C<flags>

C<array> An array of hashes with changes to the flags. The following values
can be specified. At least the status and one of type_id, id, or name must
be specified. If a type_id or name matches a single currently set flag,
the flag will be updated unless new is specified.

=over

=item C<name>

C<string> The name of the flag that will be created or updated.

=item C<type_id>

C<int> The internal flag type id that will be created or updated. You will
need to specify the C<type_id> if more than one flag type of the same name exists.

=item C<status>

C<string> The flags new status (i.e. "?", "+", "-" or "X" to clear a flag).

=item C<requestee>

C<string> The login of the requestee if the flag type is requestable to a specific user.

=item C<id>

C<int> Use id to specify the flag to be updated. You will need to specify the C<id>
if more than one flag is set of the same name.

=item C<new>

C<boolean> Set to true if you specifically want a new flag to be created.

=back

=item B<Returns>

A C<hash> with a single field, "attachments". This points to an array of hashes
with the following fields:

=over

=item C<id>

C<int> The id of the attachment that was updated.

=item C<last_change_time>

C<dateTime> The exact time that this update was done at, for this attachment.
If no update was done (that is, no fields had their values changed and
no comment was added) then this will instead be the last time the attachment
was updated.

=item C<changes>

C<hash> The changes that were actually done on this bug. The keys are
the names of the fields that were changed, and the values are a hash
with two keys:

=over