Bugzilla::Util - Generic utility functions for bugzilla
use Bugzilla::Util;
# Functions for dealing with variable tainting
trick_taint($var);
detaint_natural($var);
detaint_signed($var);
# Functions for quoting
html_quote($var);
url_quote($var);
xml_quote($var);
email_filter($var);
# Functions that tell you about your environment
my $is_cgi = i_am_cgi();
my $is_webservice = i_am_webservice();
my $urlbase = correct_urlbase();
# Data manipulation
($removed, $added) = diff_arrays(\@old, \@new);
# Functions for manipulating strings
$val = trim(" abc ");
$wrapped = wrap_comment($comment);
# Functions for formatting time
format_time($time);
datetime_from($time, $timezone);
# Cryptographic Functions
$crypted_password = bz_crypt($password);
$new_password = generate_random_password($password_length);
# Validation Functions
validate_email_syntax($email);
check_email_syntax($email);
validate_date($date);
# DB-related functions
on_main_db {
... code here ...
};
This package contains various utility functions which do not belong anywhere else.
It is not intended as a general dumping group for something which people feel might be useful somewhere, someday. Do not add methods to this package unless it is intended to be used for a significant number of files, and it does not belong anywhere else.
This package provides several types of routines:
Several functions are available to deal with tainted variables. Use these with care to avoid security holes.
trick_taint($val)Tricks perl into untainting a particular variable.
Use trick_taint() when you know that there is no way that the data in a scalar can be tainted, but taint mode still bails on it.
WARNING!! Using this routine on data that really could be tainted defeats the purpose of taint mode. It should only be used on variables that have been sanity checked in some way and have been determined to be OK.
detaint_natural($num)This routine detaints a natural number. It returns a true value if the value passed in was a valid natural number, else it returns false. You MUST check the result of this routine to avoid security holes.
detaint_signed($num)This routine detaints a signed integer. It returns a true value if the value passed in was a valid signed integer, else it returns false. You MUST check the result of this routine to avoid security holes.
Some values may need to be quoted from perl. However, this should in general be done in the template where possible.
html_quote($val)Returns a value quoted for use in HTML, with &, <, >, " and @ being replaced with their appropriate HTML entities. Also, Unicode BiDi controls are deleted.
html_light_quote($val)Returns a string where only explicitly allowed HTML elements and attributes are kept. All HTML elements and attributes not being in the whitelist are either escaped (if HTML::Scrubber is not installed) or removed.
url_quote($val)Quotes characters so that they may be included as part of a url.
css_class_quote($val)Quotes characters so that they may be used as CSS class names. Spaces and forward slashes are replaced by underscores.
xml_quote($val)This is similar to html_quote, except that ' is escaped to '. This is kept separate from html_quote partly for compatibility with previous code (for ') and partly for future handling of non-ASCII characters.
email_filterRemoves the hostname from email addresses in the string, if the user currently viewing Bugzilla is logged out. If the user is logged-in, this filter just returns the input string.
Functions returning information about your environment or location.
i_am_cgi()Tells you whether or not you are being run as a CGI script in a web server. For example, it would return false if the caller is running in a command-line script.
i_am_webservice()Tells you whether or not the current usage mode is WebServices related such as JSONRPC or XMLRPC.
correct_urlbase()Returns either the sslbase or urlbase parameter, depending on the current setting for the ssl_redirect parameter.
remote_ip()Returns the IP address of the remote client. If Bugzilla is behind a trusted proxy, it will get the remote IP address by looking at the X-Forwarded-For header.
validate_ip($ip)Returns the sanitized IP address if it is a valid IPv4 or IPv6 address, else returns undef.
use_attachbase()Returns true if an alternate host is used to display attachments; false otherwise.
diff_arrays(\@old, \@new) Description: Takes two arrayrefs, and will tell you what it takes to
get from @old to @new.
Params: @old = array that you are changing from
@new = array that you are changing to
Returns: A list of two arrayrefs. The first is a reference to an
array containing items that were removed from @old. The
second is a reference to an array containing items
that were added to @old. If both returned arrays are
empty, @old and @new contain the same values.
trim($str)Removes any leading or trailing whitespace from a string. This routine does not modify the existing string.
wrap_hard($string, $size)Wraps a string, so that a line is never longer than $size. Returns the string, wrapped.
wrap_comment($comment)Takes a bug comment, and wraps it to the appropriate length. The length is currently specified in Bugzilla::Constants::COMMENT_COLS. Lines beginning with ">" are assumed to be quotes, and they will not be wrapped.
The intended use of this function is to wrap comments that are about to be displayed or emailed. Generally, wrapped text should not be stored in the database.
find_wrap_point($string, $maxpos)Search for a comma, a whitespace or a hyphen to split $string, within the first $maxpos characters. If none of them is found, just split $string at $maxpos. The search starts at $maxpos and goes back to the beginning of the string.
join_activity_entries($field, $current_change, $new_change)Joins two strings together so they appear as one. The field name is specified as the method of joining the two strings depends on this. Returns the combined string.
is_7bit_clean($str)Returns true is the string contains only 7-bit characters (ASCII 32 through 126, ASCII 10 (LineFeed) and ASCII 13 (Carrage Return).
disable_utf8()Disable utf8 on STDOUT (and display raw data instead).
detect_encoding($str)Guesses what encoding a given data is encoded in, returning the canonical name of the detected encoding (which may be different from the MIME charset specification).
clean_text($str) Returns the parameter "cleaned" by exchanging non-printable characters with spaces. Specifically characters (ASCII 0 through 31) and (ASCII 127) will become ASCII 32 (Space).get_textThis is a method of getting localized strings within Bugzilla code. Use this when you don't want to display a whole template, you just want a particular string.
It uses the global/message.txt.tmpl template to return a string.
$message - The identifier for the message.$vars - A hashref. Any variables you want to pass to the template.A string.
template_varThis is a method of getting the value of a variable from a template in Perl code. The available variables are in the global/field-descs.none.tmpl template. Just pass in the name of the variable that you want the value of.
format_time($time)Takes a time and converts it to the desired format and timezone. If no format is given, the routine guesses the correct one and returns an empty array if it cannot. If no timezone is given, the user's timezone is used, as defined in his preferences.
This routine is mainly called from templates to filter dates, see "FILTER time" in Bugzilla::Template.
datetime_from($time, $timezone)Returns a DateTime object given a date string. If the string is not in some valid date format that strptime understands, we return undef.
You can optionally specify a timezone for the returned date. If not specified, defaults to the currently-logged-in user's timezone, or the Bugzilla server's local timezone if there isn't a logged-in user.
bz_crypt($password, $salt)Takes a string and returns a hashed (encrypted) value for it, using a random salt. An optional salt string may also be passed in.
Please always use this function instead of the built-in perl crypt function, when checking or setting a password. Bugzilla does not use crypt.
generate_random_password($password_length)Returns an alphanumeric string with the specified length (10 characters by default). Use this function to generate passwords and tokens.
validate_email_syntax($email)Do a syntax checking for a legal email address and returns 1 if the check is successful, else returns 0. Untaints $email if successful.
check_email_syntax($email)Do a syntax checking for a legal email address and throws an error if the check fails. Untaints $email if successful.
validate_date($date)Make sure the date has the correct format and returns 1 if the check is successful, else returns 0.
on_main_dbRuns a block of code always on the main DB. Useful for when you're inside a subroutine and need to do some writes to the database, but don't know if Bugzilla is currently using the shadowdb or not. Used like:
on_main_db {
my $dbh = Bugzilla->dbh;
$dbh->do("INSERT ...");
}