Dancer::Plugin(3pm)

💖 Dancer::Plugin — the helper for writing Dancer plugins 💖

okay bestie, so this is the User Contributed Perl Documentation page for Dancer::Plugin (that's the manual name, Dancer::Plugin(3pm), iykyk). It's the little toolkit that lets you build your own Dancer plugins and honestly it's giving main character energy for module authors. Let's get into it ✨

---

🌸 VERSION 🌸

version 1.3522 — yes, the version, she's specific, we love that for her 💅

---

✨ SYNOPSIS ✨

here's the whole vibe in code form. a plugin:

package Dancer::Plugin::LinkBlocker;
use Dancer ':syntax';
use Dancer::Plugin;

register block_links_from => sub {
  my $conf = plugin_setting();
  my $re = join ('|', @{$conf->{hosts}});
  before sub {
      if (request->referer && request->referer =~ /$re/) {
          status 403 || $conf->{http_code};
      }
  };
};

register_plugin;
1;

and then in your application:

package My::Webapp;

use Dancer ':syntax';
use Dancer::Plugin::LinkBlocker;

block_links_from; # this is exported by the plugin

see how block_links_from just shows up in your app like it's been there the whole time? that's the plugin exporting it, periodt 🫶

---

👑 DESCRIPTION 👑

Create plugins for Dancer. that's it, that's the whole mission, no cap 🔥

---

🦋 PLUGINS 🦋

You can extend Dancer by writing your own Plugin. yes bestie, you can just make one 💖

A plugin is a module that exports a bunch of symbols to the current namespace (the caller will see all the symbols defined via "register").

heads up: you have to "use" the plugin wherever you want to use its symbols. not optional, not negotiable.

For instance, if you have Webapp::App1 and Webapp::App2, both loaded from your main application, they both need to "use FooPlugin" if they want to use the symbols exported by "FooPlugin". like, both of them. individually. no sneaky inheriting the vibes through the main app, sorry 🙈

🎀 METHODS 🎀

• register — Lets you define a keyword that will be exported by the plugin. like so:

register my_symbol_to_export => sub {
    # ... some code
};

• register_plugin — A Dancer plugin must end with this statement. she's the closer, the final bow 🎬 This lets the plugin register all the symbols define with "register" as exported symbols (via the Exporter module).

and the cute part: a Dancer plugin inherits from Dancer::Plugin and Exporter transparently. free inheritance, we love a generous queen 👑

• register_hook — Allows a plugin to declare a list of supported hooks. Any hook declared like so can be executed by the plugin with "execute_hooks".

register_hook 'foo';
register_hook 'foo', 'bar', 'baz';

• execute_hooks — Allows a plugin to execute the hooks attached at the given position

execute_hooks 'some_hook';

The hook must have been registered by the plugin first, with "register_hook". so register before you execute, in that order, always ⭐

• plugin_setting — Configuration for plugin should be structured like this in the config.yml of the application:

plugins:
  plugin_name:
    key: value

If "plugin_setting" is called inside a plugin, the appropriate configuration will be returned. The "plugin_name" should be the name of the package, or, if the plugin name is under the Dancer::Plugin:: namespace (which is recommended), the remaining part of the plugin name.

little detail that will bite you: Enclose the remaining part in quotes if it contains ::, e.g. for Dancer::Plugin::Foo::Bar, use:

plugins:
  "Foo::Bar":
    key: value

• plugin_args — To easy migration and interoperability between Dancer 1 and Dancer 2 you can use this method to obtain the arguments or parameters passed to a plugin-defined keyword. Although not relevant for Dancer 1 only, or Dancer 2 only, plugins, it is useful for universal plugins.

register foo => sub {
   my ($self, @args) = plugin_args(@_);
   ...
}

Note that Dancer 1 will return undef as the object reference. so Dancer 1 girlies, don't come for that $self, it's not there 💀

---

💜 AUTHORS 💜

This module has been written by Alexis Sukrieh and others. shoutout to the whole squad 🫶✨

---

🌈 LICENSE 🌈

This module is free software and is published under the same terms as Perl itself. free as in freedom, iconic behavior 🎀

---

⭐ AUTHOR ⭐

Dancer Core Developers 💅

---

💖 COPYRIGHT AND LICENSE 💖

This software is copyright (c) 2010 by Alexis Sukrieh.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's the whole page bestie, no notes 🌸 this doc shipped as part of perl v5.40.1, dated 2026-05-05 — go forth and write plugins, you absolute legend 👑💅🦋