There is an ongoing outage on the primary CPAN mirror. It is possible to work around the issue by using MetaCPAN as a mirror.

 / 
Dancer2-2.0.0
River stage three • 168 direct dependents • 189 total dependents
⭐ Starred 552 GitHub stars
/ Dancer2::Manual::Extending

NAME

Dancer2::Manual::Extending - A guide to extending Dancer2 via engines and plugins

VERSION

version 2.0.0

Name

Dancer2::Extending - How to Extend Dancer2 by Writing Your Own Engines, Handlers, and Plugins

Introduction

Dancer2 is designed to be flexible and extensible. Whether you need a custom template engine, session engine, serializer, or file handler, Dancer2 provides a clean API that makes it easy to extend its core functionality.

In this document, we’ll cover how to write your own engines, handlers, and plugins for Dancer2. The goal is to give you the tools you need to build custom components that integrate seamlessly into your Dancer2 applications.

Writing Your Own Engine

In Dancer2, engines are used to handle various aspects of your application, such as templates, sessions, serializers, and loggers. Each engine follows a standard interface, making it easy to plug in new implementations.

Writing a Template Engine

A custom template engine must implement the Dancer2::Core::Role::Template role. This role defines the basic methods that any template engine needs to implement.

Example: Custom Template Engine

package Dancer2::Template::MyTemplateEngine;
use Moo;
with 'Dancer2::Core::Role::Template';

# Define the required methods
# ...

sub render {
    my ($self, $template, $tokens) = @_;

    # Your rendering logic here
    return "<html><body>Welcome to Danceyland, $tokens->{'visitor_name'}!</body></html>";
}

1;

In this example, render is the method responsible for processing the template and returning the final output.

To use your custom engine, configure it in your config.yml file:

template: "MyTemplateEngine"

Writing a Session Engine

Session engines handle storing and retrieving session data. All session engines must implement the Dancer2::Core::Role::SessionFactory role.

Example: Custom Session Engine

package Dancer2::Session::MySessionEngine;
use Moo;
with 'Dancer2::Core::Role::SessionFactory';

sub retrieve {
    my ($self, $id) = @_;
    # Fetch session data based on session ID
}

sub create {
    my ($self, $data) = @_;
    # Create a new session
}

sub destroy {
    my ($self, $id) = @_;
    # Destroy the session identified by $id
}

sub flush {
    my ($self, $id, $data) = @_;
    # Save session data
}

1;

This engine defines the basic methods to manage session data.

Writing a Serializer Engine

Serializer engines handle serializing and deserializing data between Perl data structures and different formats like JSON, YAML, or XML.

All serializer engines must implement the Dancer2::Core::Role::Serializer role.

Example: Custom Serializer Engine

package Dancer2::Serializer::MySerializer;
use Moo;
with 'Dancer2::Core::Role::Serializer';

sub serialize {
    my ($self, $content) = @_;
    # Convert $content to a custom format
}

sub deserialize {
    my ($self, $content) = @_;
    # Convert custom format back to Perl data structure
}

sub content_type {
    return 'application/custom';
}

1;

This engine defines the methods needed to serialize and deserialize data.

Writing a Logger Engine

Logger engines are responsible for handling log messages in your application. All logger engines must implement the Dancer2::Core::Role::Logger role.

Example: Custom Logger Engine

package Dancer2::Logger::MyLogger;
use Moo;
with 'Dancer2::Core::Role::Logger';

sub log {
    my ($self, $level, $message) = @_;
    # Custom logging logic here
    warn "[$level] $message";
}

1;

This logger will output log messages to warn, and you can configure it in your config.yml file:

logger: "MyLogger"

Writing Your Own File Handler

File handlers in Dancer2 are responsible for serving static files from disk. If you need custom logic for serving files (such as restricting access or adding dynamic features), you can create your own file handler by consuming the Dancer2::Core::Role::Handler role.

Example: Custom File Handler

package Dancer2::Handler::MyFileHandler;
use Moo;
with 'Dancer2::Core::Role::Handler';

sub methods { qw(GET) }

sub regexp { '/static/:file' }

sub code {
    return sub {
        my $app = shift;
        my $file = $app->request->params->{file};

        # Add custom logic for serving files
        my $file_path = "/path/to/static/files/$file";
        if (-e $file_path) {
            $app->send_file($file_path);
        } else {
            $app->send_error('File not found', 404);
        }
    };
}

sub register {
    my ($self, $app) = @_;
    $app->add_route(
        method => $_,
        regexp => $self->regexp,
        code   => $self->code,
    ) for $self->methods;
}

1;

This handler will serve static files from the specified directory, but it also checks if the file exists before serving it.

Writing A Dancer2 Plugin

Plugins in Dancer2 are reusable components that extend your app's functionality. They are often used for tasks like authentication, database management, or form validation.

All plugins must consume the Dancer2::Core::Role::Plugin role.

Example: Custom Dancer2 Plugin

package Dancer2::Plugin::MyPlugin;
use Dancer2::Plugin;

register 'greet' => sub {
    my ($dsl, $name) = @_;
    return "Hello, $name! Welcome to Danceyland!";
};

register_plugin;

In this example, a greet keyword is created, and can be called within any Dancer2 route to display a greeting. To use the plugin, just include it in your app:

use Dancer2::Plugin::MyPlugin;

get '/hello/:name' => sub {
    return greet( route_parameters->get('name') );
};

Custom Session Storage Mechanisms

Dancer2 allows you to define your own custom session storage mechanism by implementing the Dancer2::Core::Role::SessionFactory role. This is useful if you need to store session data in a format or storage medium that isn’t supported out-of-the-box, such as a proprietary database or external service.

Example: Custom Session Storage

Here’s how you can create a custom session storage engine that stores session data in a simple hash in memory. In practice, you’d likely store data in a more robust medium like a database or external cache.

package Dancer2::Session::MySessionStorage;
use Moo;
with 'Dancer2::Core::Role::SessionFactory';

# Simple in-memory session store (not suitable for production use)
my %session_store;

sub retrieve {
    my ($self, $id) = @_;
    return $session_store{$id};
}

sub create {
    my ($self, $data) = @_;
    my $session_id = $self->generate_session_id;
    $session_store{$session_id} = $data;
    return $session_id;
}

sub destroy {
    my ($self, $id) = @_;
    delete $session_store{$id};
}

sub flush {
    my ($self, $id, $data) = @_;
    $session_store{$id} = $data;
}

1;

Using the Custom Session Storage

To use your custom session storage mechanism, configure it in your config.yml file:

session: "MySessionStorage"

This simple example uses an in-memory hash to store sessions, but you can adapt it to any storage medium, such as Redis, MongoDB, or a relational database. Be sure to implement locking mechanisms and persistence for production usage.

Custom Middleware

Middleware is code that runs before or after the core request handler in Dancer2. It allows you to intercept, modify, or even short-circuit the request/response cycle before it reaches your app’s route handlers or after they return a response.

How Middleware Works

When a request is received, middleware runs in a predefined order:

  1. Before the app handler is executed (before stage).

  2. The app's route handlers process the request.

  3. After the app handler processes the request and returns a response (after stage).

Middleware gives you the ability to modify the request before it's passed to the app handler, or to change the response after it has been generated. You can also prevent the app handler from running altogether and return a custom response directly from the middleware.

Example: Custom Middleware

Here’s an example of custom middleware that runs before and after the app handler. It logs the incoming request, processes the app’s routes, and then modifies the response by appending a footer message.

package Dancer2::Middleware::MyCustomMiddleware;
use Plack::Middleware;
use parent 'Plack::Middleware';

sub call {
    my ($self, $env) = @_;

    # BEFORE the app handler: Log the request method and path
    warn "Incoming request: $env->{REQUEST_METHOD} $env->{PATH_INFO}";

    # Call the app handler (if you want the app to continue processing)
    my $res = $self->app->($env);

    # AFTER the app handler: Modify the response (e.g., add a footer)
    return sub {
        my $respond = shift;
        my $writer = $respond->(
            [
                $res->[0],    # HTTP status code
                $res->[1],    # HTTP headers
                $res->[2],    # HTTP body
            ]
        );

        # Append a footer to the response body
        $writer->write("\n-- Thank you for visiting Danceyland!");
        $writer->close;
    };
}

1;

Using the Custom Middleware

To enable this middleware, modify your app.psgi file to use it with Dancer2’s built-in support for Plack middleware:

use Dancer2;
use MyApp;

builder {
    enable 'Dancer2::Middleware::MyCustomMiddleware';
    MyApp->to_app;
};

How Middleware Can Control the Flow

In the example above, the middleware logs the request before it reaches the app and modifies the response after the app handler runs. However, if you don’t want to call the app handler (for example, to short-circuit the request and return a custom response), you can skip the call to $self->app->($env) and return a response directly from the middleware:

sub call {
    my ($self, $env) = @_;

    # If the request matches a certain condition, bypass the app handler
    if ($env->{PATH_INFO} =~ m{/secret}) {
        return [403, ['Content-Type' => 'text/plain'], ["Forbidden"]];
    }

    # Otherwise, continue to the app handler
    my $res = $self->app->($env);

    # Modify the response as needed
    ...
}

In this case, if the request path contains /secret, the middleware returns a 403 Forbidden response, skipping the app handler entirely.

Order of Operations

Middleware executes in the following order:

  • Any code in the before stage is executed before your app processes the request. You can modify or reject the request here.

  • Your app processes the request and generates a response.

  • Any code in the after stage is executed after the response has been generated. You can modify or append to the response here before it’s sent to the client.

Custom middleware provides great flexibility for pre- and post-processing requests and responses in your Dancer2 app.

AUTHOR

Dancer Core Developers

COPYRIGHT AND LICENSE

This software is copyright (c) 2025 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.