blob: aece3b7def297027d4fdf45ccd645d490014dc5b [file] [log] [blame]
# 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::User::Setting;
use 5.10.1;
use strict;
use warnings;
use parent qw(Exporter);
# Module stuff
@Bugzilla::User::Setting::EXPORT = qw(
get_all_settings
get_defaults
add_setting
clear_settings_cache
);
use Bugzilla::Error;
use Bugzilla::Util qw(trick_taint get_text);
###############################
### Module Initialization ###
###############################
sub new {
my $invocant = shift;
my $setting_name = shift;
my $user_id = shift;
my $class = ref($invocant) || $invocant;
my $subclass = '';
# Create a ref to an empty hash and bless it
my $self = {};
my $dbh = Bugzilla->dbh;
# Confirm that the $setting_name is properly formed;
# if not, throw a code error.
#
# NOTE: due to the way that setting names are used in templates,
# they must conform to to the limitations set for HTML NAMEs and IDs.
#
if ( !($setting_name =~ /^[a-zA-Z][-.:\w]*$/) ) {
ThrowCodeError("setting_name_invalid", { name => $setting_name });
}
# If there were only two parameters passed in, then we need
# to retrieve the information for this setting ourselves.
if (scalar @_ == 0) {
my ($default, $is_enabled, $value);
($default, $is_enabled, $value, $subclass) =
$dbh->selectrow_array(
q{SELECT default_value, is_enabled, setting_value, subclass
FROM setting
LEFT JOIN profile_setting
ON setting.name = profile_setting.setting_name
WHERE name = ?
AND profile_setting.user_id = ?},
undef,
$setting_name, $user_id);
# if not defined, then grab the default value
if (! defined $value) {
($default, $is_enabled, $subclass) =
$dbh->selectrow_array(
q{SELECT default_value, is_enabled, subclass
FROM setting
WHERE name = ?},
undef,
$setting_name);
}
$self->{'is_enabled'} = $is_enabled;
$self->{'default_value'} = $default;
# IF the setting is enabled, AND the user has chosen a setting
# THEN return that value
# ELSE return the site default, and note that it is the default.
if ( ($is_enabled) && (defined $value) ) {
$self->{'value'} = $value;
} else {
$self->{'value'} = $default;
$self->{'isdefault'} = 1;
}
}
else {
# If the values were passed in, simply assign them and return.
$self->{'is_enabled'} = shift;
$self->{'default_value'} = shift;
$self->{'value'} = shift;
$self->{'is_default'} = shift;
$subclass = shift;
}
if ($subclass) {
eval('require ' . $class . '::' . $subclass);
$@ && ThrowCodeError('setting_subclass_invalid',
{'subclass' => $subclass});
$class = $class . '::' . $subclass;
}
bless($self, $class);
$self->{'_setting_name'} = $setting_name;
$self->{'_user_id'} = $user_id;
return $self;
}
###############################
### Subroutine Definitions ###
###############################
sub add_setting {
my ($name, $values, $default_value, $subclass, $force_check,
$silently) = @_;
my $dbh = Bugzilla->dbh;
my $exists = _setting_exists($name);
return if ($exists && !$force_check);
($name && length( $default_value // '' ))
|| ThrowCodeError("setting_info_invalid");
if ($exists) {
# If this setting exists, we delete it and regenerate it.
$dbh->do('DELETE FROM setting_value WHERE name = ?', undef, $name);
$dbh->do('DELETE FROM setting WHERE name = ?', undef, $name);
# Remove obsolete user preferences for this setting.
if (defined $values && scalar(@$values)) {
my $list = join(', ', map {$dbh->quote($_)} @$values);
$dbh->do("DELETE FROM profile_setting
WHERE setting_name = ? AND setting_value NOT IN ($list)",
undef, $name);
}
}
elsif (!$silently) {
print get_text('install_setting_new', { name => $name }) . "\n";
}
$dbh->do(q{INSERT INTO setting (name, default_value, is_enabled, subclass)
VALUES (?, ?, 1, ?)},
undef, ($name, $default_value, $subclass));
my $sth = $dbh->prepare(q{INSERT INTO setting_value (name, value, sortindex)
VALUES (?, ?, ?)});
my $sortindex = 5;
foreach my $key (@$values){
$sth->execute($name, $key, $sortindex);
$sortindex += 5;
}
}
sub get_all_settings {
my ($user_id) = @_;
my $settings = {};
my $dbh = Bugzilla->dbh;
my $cache_key = "user_settings.$user_id";
my $rows = Bugzilla->memcached->get_config({ key => $cache_key });
if (!$rows) {
$rows = $dbh->selectall_arrayref(
q{SELECT name, default_value, is_enabled, setting_value, subclass
FROM setting
LEFT JOIN profile_setting
ON setting.name = profile_setting.setting_name
AND profile_setting.user_id = ?}, undef, ($user_id));
Bugzilla->memcached->set_config({ key => $cache_key, data => $rows });
}
foreach my $row (@$rows) {
my ($name, $default_value, $is_enabled, $value, $subclass) = @$row;
my $is_default;
if ( ($is_enabled) && (defined $value) ) {
$is_default = 0;
} else {
$value = $default_value;
$is_default = 1;
}
$settings->{$name} = new Bugzilla::User::Setting(
$name, $user_id, $is_enabled,
$default_value, $value, $is_default, $subclass);
}
return $settings;
}
sub clear_settings_cache {
my ($user_id) = @_;
Bugzilla->memcached->clear_config({ key => "user_settings.$user_id" });
}
sub get_defaults {
my ($user_id) = @_;
my $dbh = Bugzilla->dbh;
my $default_settings = {};
$user_id ||= 0;
my $rows = $dbh->selectall_arrayref(q{SELECT name, default_value, is_enabled, subclass
FROM setting});
foreach my $row (@$rows) {
my ($name, $default_value, $is_enabled, $subclass) = @$row;
$default_settings->{$name} = new Bugzilla::User::Setting(
$name, $user_id, $is_enabled, $default_value, $default_value, 1,
$subclass);
}
return $default_settings;
}
sub set_default {
my ($setting_name, $default_value, $is_enabled) = @_;
my $dbh = Bugzilla->dbh;
my $sth = $dbh->prepare(q{UPDATE setting
SET default_value = ?, is_enabled = ?
WHERE name = ?});
$sth->execute($default_value, $is_enabled, $setting_name);
}
sub _setting_exists {
my ($setting_name) = @_;
my $dbh = Bugzilla->dbh;
return $dbh->selectrow_arrayref(
"SELECT 1 FROM setting WHERE name = ?", undef, $setting_name) || 0;
}
sub legal_values {
my ($self) = @_;
return $self->{'legal_values'} if defined $self->{'legal_values'};
my $dbh = Bugzilla->dbh;
$self->{'legal_values'} = $dbh->selectcol_arrayref(
q{SELECT value
FROM setting_value
WHERE name = ?
ORDER BY sortindex},
undef, $self->{'_setting_name'});
return $self->{'legal_values'};
}
sub validate_value {
my $self = shift;
if (grep(/^$_[0]$/, @{$self->legal_values()})) {
trick_taint($_[0]);
}
else {
ThrowCodeError('setting_value_invalid',
{'name' => $self->{'_setting_name'},
'value' => $_[0]});
}
}
sub reset_to_default {
my ($self) = @_;
my $dbh = Bugzilla->dbh;
my $sth = $dbh->do(q{ DELETE
FROM profile_setting
WHERE setting_name = ?
AND user_id = ?},
undef, $self->{'_setting_name'}, $self->{'_user_id'});
$self->{'value'} = $self->{'default_value'};
$self->{'is_default'} = 1;
}
sub set {
my ($self, $value) = @_;
my $dbh = Bugzilla->dbh;
my $query;
if ($self->{'is_default'}) {
$query = q{INSERT INTO profile_setting
(setting_value, setting_name, user_id)
VALUES (?,?,?)};
} else {
$query = q{UPDATE profile_setting
SET setting_value = ?
WHERE setting_name = ?
AND user_id = ?};
}
$dbh->do($query, undef, $value, $self->{'_setting_name'}, $self->{'_user_id'});
$self->{'value'} = $value;
$self->{'is_default'} = 0;
}
1;
__END__
=head1 NAME
Bugzilla::User::Setting - Object for a user preference setting
=head1 SYNOPSIS
Setting.pm creates a setting object, which is a hash containing the user
preference information for a single preference for a single user. These
are usually accessed through the "settings" object of a user, and not
directly.
=head1 DESCRIPTION
use Bugzilla::User::Setting;
my $settings;
$settings->{$setting_name} = new Bugzilla::User::Setting(
$setting_name, $user_id);
OR
$settings->{$setting_name} = new Bugzilla::User::Setting(
$setting_name, $user_id, $is_enabled,
$default_value, $value, $is_default);
=head1 CLASS FUNCTIONS
=over 4
=item C<add_setting($name, \@values, $default_value, $subclass, $force_check)>
Description: Checks for the existence of a setting, and adds it
to the database if it does not yet exist.
Params: C<$name> - string - the name of the new setting
C<$values> - arrayref - contains the new choices
for the new Setting.
C<$default_value> - string - the site default
C<$subclass> - string - name of the module returning
the list of valid values. This means legal values are
not stored in the DB.
C<$force_check> - boolean - when true, the existing setting
and all its values are deleted and replaced by new data.
Returns: a pointer to a hash of settings
=item C<get_all_settings($user_id)>
Description: Provides the user's choices for each setting in the
system; if the user has made no choice, uses the site
default instead.
Params: C<$user_id> - integer - the user id.
Returns: a pointer to a hash of settings
=item C<get_defaults($user_id)>
Description: When a user is not logged in, they must use the site
defaults for every settings; this subroutine provides them.
Params: C<$user_id> (optional) - integer - the user id. Note that
this optional parameter is mainly for internal use only.
Returns: A pointer to a hash of settings. If $user_id was passed, set
the user_id value for each setting.
=item C<set_default($setting_name, $default_value, $is_enabled)>
Description: Sets the global default for a given setting. Also sets
whether users are allowed to choose their own value for
this setting, or if they must use the global default.
Params: C<$setting_name> - string - the name of the setting
C<$default_value> - string - the new default value for this setting
C<$is_enabled> - boolean - if false, all users must use the global default
Returns: nothing
=item C<clear_settings_cache($user_id)>
Description: Clears cached settings data for the specified user. Must be
called after updating any user's setting.
Params: C<$user_id> - integer - the user id.
Returns: nothing
=begin private
=item C<_setting_exists>
Description: Determines if a given setting exists in the database.
Params: C<$setting_name> - string - the setting name
Returns: boolean - true if the setting already exists in the DB.
=end private
=back
=head1 METHODS
=over 4
=item C<legal_values($setting_name)>
Description: Returns all legal values for this setting
Params: none
Returns: A reference to an array containing all legal values
=item C<validate_value>
Description: Determines whether a value is valid for the setting
by checking against the list of legal values.
Untaints the parameter if the value is indeed valid,
and throws a setting_value_invalid code error if not.
Params: An lvalue containing a candidate for a setting value
Returns: nothing
=item C<reset_to_default>
Description: If a user chooses to use the global default for a given
setting, their saved entry is removed from the database via
this subroutine.
Params: none
Returns: nothing
=item C<set($value)>
Description: If a user chooses to use their own value rather than the
global value for a given setting, OR changes their value for
a given setting, this subroutine is called to insert or
update the database as appropriate.
Params: C<$value> - string - the new value for this setting for this user.
Returns: nothing
=back