use Bugzilla::Error;
use Bugzilla::Install::Util qw(extension_code_files);
-use File::Basename qw(basename);
+use File::Basename;
+use File::Spec;
####################
# Subclass Methods #
sub load {
my ($class, $extension_file, $config_file) = @_;
- require $config_file if $config_file;
-
my $package;
+
# This is needed during checksetup.pl, because Extension packages can
# only be loaded once (they return "1" the second time they're loaded,
- # instead of their name). If an extension has only an Extension.pm,
- # and no Config.pm, the Extension.pm gets loaded by
- # Bugzilla::Install::Requirements before this load() method is ever
- # called.
+ # instead of their name). During checksetup.pl, extensions are loaded
+ # once by Bugzilla::Install::Requirements, and then later again via
+ # Bugzilla->extensions (because of hooks).
my $map = Bugzilla->request_cache->{extension_requirement_package_map};
+
+ if ($config_file) {
+ if ($map and defined $map->{$config_file}) {
+ $package = $map->{$config_file};
+ }
+ else {
+ my $name = require $config_file;
+ if ($name =~ /^\d+$/) {
+ ThrowCodeError('extension_must_return_name',
+ { extension => $config_file,
+ returned => $name });
+ }
+ $package = "${class}::$name";
+ }
+
+ # This allows people to override modify_inc in Config.pm, if they
+ # want to.
+ if ($package->can('modify_inc')) {
+ $package->modify_inc($config_file);
+ }
+ else {
+ modify_inc($package, $config_file);
+ }
+ }
+
if ($map and defined $map->{$extension_file}) {
$package = $map->{$extension_file};
+ $package->modify_inc($extension_file) if !$config_file;
}
else {
my $name = require $extension_file;
{ extension => $extension_file, returned => $name });
}
$package = "${class}::$name";
+ $package->modify_inc($extension_file) if !$config_file;
}
if (!eval { $package->NAME }) {
return \@packages;
}
+# Modifies @INC so that extensions can use modules like
+# "use Bugzilla::Extension::Foo::Bar", when Bar.pm is in the lib/
+# directory of the extension.
+sub modify_inc {
+ my ($class, $file) = @_;
+ my $lib_dir = File::Spec->catdir(dirname($file), 'lib');
+ # Allow Config.pm to override my_inc, if it wants to.
+ if ($class->can('my_inc')) {
+ unshift(@INC, sub { $class->my_inc($lib_dir, @_); });
+ }
+ else {
+ unshift(@INC, sub { my_inc($class, $lib_dir, @_); });
+ }
+}
+
+# This is what gets put into @INC by modify_inc.
+sub my_inc {
+ my ($class, $lib_dir, undef, $file) = @_;
+ my @class_parts = split('::', $class);
+ my ($vol, $dir, $file_name) = File::Spec->splitpath($file);
+ my @dir_parts = File::Spec->splitdir($dir);
+ # Validate that this is a sub-package of Bugzilla::Extension::Foo ($class).
+ for (my $i = 0; $i < scalar(@class_parts); $i++) {
+ return if !@dir_parts;
+ if (File::Spec->case_tolerant) {
+ return if lc($class_parts[$i]) ne lc($dir_parts[0]);
+ }
+ else {
+ return if $class_parts[$i] ne $dir_parts[0];
+ }
+ shift(@dir_parts);
+ }
+ # For Bugzilla::Extension::Foo::Bar, this would look something like
+ # extensions/Example/lib/Bar.pm
+ my $resolved_path = File::Spec->catfile($lib_dir, @dir_parts, $file_name);
+ open(my $fh, '<', $resolved_path);
+ return $fh;
+}
+
####################
# Instance Methods #
####################
If any of this is confusing, just look at the code of the Example extension.
It uses this method to specify requirements.
+=head2 Libraries
+
+Extensions often want to have their own Perl modules. Your extension
+can load any Perl module in its F<lib/> directory. (So, if your extension is
+F<extensions/Foo/>, then your Perl modules go into F<extensions/Foo/lib/>.)
+
+However, the C<package> name of your libraries will not work quite
+like normal Perl modules do. F<extensions/Foo/lib/Bar.pm> is
+loaded as C<Bugzilla::Extension::Foo::Bar>. Or, to say it another way,
+C<use Bugzilla::Extension::Foo::Bar;> loads F<extensions/Foo/lib/Bar.pm>,
+which should have C<package Bugzilla::Extension::Foo::Bar;> as its package
+name.
+
+This allows any place in Bugzilla to load your modules, which is important
+for some hooks. It even allows other extensions to load your modules. It
+even allows you to install your modules into the global Perl install
+as F<Bugzilla/Extension/Foo/Bar.pm>, if you'd like, which helps allow CPAN
+distribution of Bugzilla extensions.
+
+B<Note:> If you want to C<use> or C<require> a module that's in
+F<extensions/Foo/lib/> at the top level of your F<Extension.pm>,
+you must have a F<Config.pm> (see above) with at least the C<NAME>
+constant defined in it.
+
=head2 Disabling Your Extension
If you want your extension to be totally ignored by Bugzilla (it will
package Bugzilla::Hook;
use strict;
-use Bugzilla::Constants;
sub process {
my ($name, $args) = @_;
foreach my $extension (@{ Bugzilla->extensions }) {
- local @INC = @INC;
- my $ext_dir = bz_locations()->{'extensionsdir'};
- my $ext_name = $extension->NAME;
- unshift(@INC, "$ext_dir/$ext_name/lib");
if ($extension->can($name)) {
$extension->$name($args);
}
use strict;
use base qw(Bugzilla::Extension);
-use Bugzilla::Util qw(
- diff_arrays
- html_quote
-);
+use Bugzilla::Util qw(diff_arrays html_quote);
+
+# This is extensions/Example/lib/Util.pm. I can load this here in my
+# Extension.pm only because I have a Config.pm.
+use Bugzilla::Extension::Example::Util;
use Data::Dumper;
my ($self, $params) = @_;
my $modules = $params->{modules};
if (exists $modules->{Example}) {
- $modules->{Example} = 'extensions/Example/lib/AuthLogin.pm';
+ $modules->{Example} = 'Bugzilla/Extension/Example/Auth/Login.pm';
}
}
my ($self, $params) = @_;
my $modules = $params->{modules};
if (exists $modules->{Example}) {
- $modules->{Example} = 'extensions/Example/lib/AuthVerify.pm';
+ $modules->{Example} = 'Bugzilla/Extension/Example/Auth/Verify.pm';
}
}
my ($self, $params) = @_;
my $config = $params->{config};
- $config->{Example} = "extensions::Example::lib::ConfigExample";
+ $config->{Example} = "Bugzilla::Extension::Example::Config";
}
sub config_add_panels {
my ($self, $params) = @_;
my $modules = $params->{panel_modules};
- $modules->{Example} = "extensions::Example::lib::ConfigExample";
+ $modules->{Example} = "Bugzilla::Extension::Example::Config";
}
sub config_modify_panels {
my ($self, $params) = @_;
my $dispatch = $params->{dispatch};
- $dispatch->{Example} = "extensions::Example::lib::WSExample";
+ $dispatch->{Example} = "Bugzilla::Extension::Example::WebService";
}
sub webservice_error_codes {
--- /dev/null
+# -*- Mode: perl; indent-tabs-mode: nil -*-
+#
+# The contents of this file are subject to the Mozilla Public
+# License Version 1.1 (the "License"); you may not use this file
+# except in compliance with the License. You may obtain a copy of
+# the License at http://www.mozilla.org/MPL/
+#
+# Software distributed under the License is distributed on an "AS
+# IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
+# implied. See the License for the specific language governing
+# rights and limitations under the License.
+#
+# The Original Code is the Bugzilla Example Plugin.
+#
+# The Initial Developer of the Original Code is Canonical Ltd.
+# Portions created by Canonical are Copyright (C) 2008 Canonical Ltd.
+# All Rights Reserved.
+#
+# Contributor(s): Max Kanat-Alexander <mkanat@bugzilla.org>
+
+package Bugzilla::Extension::Example::Auth::Login;
+use strict;
+use base qw(Bugzilla::Auth::Login);
+use constant user_can_create_account => 0;
+use Bugzilla::Constants;
+
+# Always returns no data.
+sub get_login_info {
+ return { failure => AUTH_NODATA };
+}
+
+1;
--- /dev/null
+# -*- Mode: perl; indent-tabs-mode: nil -*-
+#
+# The contents of this file are subject to the Mozilla Public
+# License Version 1.1 (the "License"); you may not use this file
+# except in compliance with the License. You may obtain a copy of
+# the License at http://www.mozilla.org/MPL/
+#
+# Software distributed under the License is distributed on an "AS
+# IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
+# implied. See the License for the specific language governing
+# rights and limitations under the License.
+#
+# The Original Code is the Bugzilla Example Plugin.
+#
+# The Initial Developer of the Original Code is Canonical Ltd.
+# Portions created by Canonical are Copyright (C) 2008 Canonical Ltd.
+# All Rights Reserved.
+#
+# Contributor(s): Max Kanat-Alexander <mkanat@bugzilla.org>
+
+package Bugzilla::Extension::Example::Auth::Verify;
+use strict;
+use base qw(Bugzilla::Auth::Verify);
+use Bugzilla::Constants;
+
+# A verifier that always fails.
+sub check_credentials {
+ return { failure => AUTH_NO_SUCH_USER };
+}
+
+1;
--- /dev/null
+# -*- Mode: perl; indent-tabs-mode: nil -*-
+#
+# The contents of this file are subject to the Mozilla Public
+# License Version 1.1 (the "License"); you may not use this file
+# except in compliance with the License. You may obtain a copy of
+# the License at http://www.mozilla.org/MPL/
+#
+# Software distributed under the License is distributed on an "AS
+# IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
+# implied. See the License for the specific language governing
+# rights and limitations under the License.
+#
+# The Original Code is the Bugzilla Example Plugin.
+#
+# The Initial Developer of the Original Code is Canonical Ltd.
+# Portions created by Canonical Ltd. are Copyright (C) 2008
+# Canonical Ltd. All Rights Reserved.
+#
+# Contributor(s): Max Kanat-Alexander <mkanat@bugzilla.org>
+# Bradley Baetz <bbaetz@acm.org>
+
+package Bugzilla::Extension::Example::Config;
+use strict;
+use warnings;
+
+use Bugzilla::Config::Common;
+
+sub get_param_list {
+ my ($class) = @_;
+
+ my @param_list = (
+ {
+ name => 'example_string',
+ type => 't',
+ default => 'EXAMPLE',
+ },
+ );
+ return @param_list;
+}
+
+1;
--- /dev/null
+# -*- Mode: perl; indent-tabs-mode: nil -*-
+#
+# The contents of this file are subject to the Mozilla Public
+# License Version 1.1 (the "License"); you may not use this file
+# except in compliance with the License. You may obtain a copy of
+# the License at http://www.mozilla.org/MPL/
+#
+# Software distributed under the License is distributed on an "AS
+# IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
+# implied. See the License for the specific language governing
+# rights and limitations under the License.
+#
+# The Original Code is the Bugzilla Bug Tracking System.
+#
+# The Initial Developer of the Original Code is Everything Solved, Inc.
+# Portions created by Everything Solved, Inc. are Copyright (C) 2009
+# Everything Solved, Inc. All Rights Reserved.
+#
+# Contributor(s): Max Kanat-Alexander <mkanat@bugzilla.org>
+
+package Bugzilla::Extension::Example::Util;
+use strict;
+use warnings;
+
+# This file exists only to demonstrate how to use and name your
+# modules in an extension.
+
+1;
--- /dev/null
+# -*- Mode: perl; indent-tabs-mode: nil -*-
+#
+# The contents of this file are subject to the Mozilla Public
+# License Version 1.1 (the "License"); you may not use this file
+# except in compliance with the License. You may obtain a copy of
+# the License at http://www.mozilla.org/MPL/
+#
+# Software distributed under the License is distributed on an "AS
+# IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
+# implied. See the License for the specific language governing
+# rights and limitations under the License.
+#
+# The Original Code is the Bugzilla Bug Tracking System.
+#
+# The Initial Developer of the Original Code is Everything Solved, Inc.
+# Portions created by Everything Solved, Inc. are Copyright (C) 2007
+# Everything Solved, Inc. All Rights Reserved.
+#
+# Contributor(s): Max Kanat-Alexander <mkanat@bugzilla.org>
+
+package Bugzilla::Extension::Example::WebService;
+use strict;
+use warnings;
+use base qw(Bugzilla::WebService);
+use Bugzilla::Error;
+
+# This can be called as Example.hello() from the WebService.
+sub hello { return 'Hello!'; }
+
+sub throw_an_error { ThrowUserError('example_my_error') }
+
+1;
projects / thirdparty / bugzilla.git / commitdiff
