The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Dancer2::Manual::Migration - Migrating from Dancer to Dancer2

VERSION

version 0.153000

Migration from Dancer1 to Dancer2

This document covers some changes that users will need to be aware of while upgrading from Dancer (version 1) to Dancer2.

Apps

1. In Dancer2, each module is a separate application with its own namespace and variables. You can set the application name in each of your Dancer2 application modules. Different modules can be tied into the same app by setting the application name to the same value.

For example, to set the appname directive explicitly:

MyApp:

    package MyApp;
    use Dancer2;
    use MyApp::Admin

    hook before => sub {
        var db => 'Users';
    };

    get '/' => sub {...};

    1;

MyApp::Admin:

    package MyApp::Admin;
    use Dancer2 appname => 'MyApp';

    # use a lexical prefix so we don't override it globally
    prefix '/admin' => sub {
        get '/' => sub {...};
    };

    1;

Without the appname directive, MyApp::Admin would not have access to variable db. In fact, when accessing /admin, the before hook would not be executed.

See Dancer2::Cookbook for details.

2. The following modules can be used to speed up an app in Dancer2:

They would need to be installed separately. This is because Dancer2 does not incorporate any C code, but it can get C-code compiled as a module. Thus, these modules can be used for speed improvement provided:

  • You have access to a C interpreter

  • You don't need to fatpack your application

Plugins: plugin_setting

plugin_setting returns the configuration of the plugin. It can no longer be called outside of register or on_plugin_import.

Routes

Dancer2 requires all routes defined via a string to begin with a leading slash /.

For example:

    get '0' => sub {
        return "not gonna fly";
    };

would return an error. The correct way to write this would be to use get '/0'

Tests

Dancer2 recommends the use of Plack::Test.

For example:

    use strict;
    use warnings;

    use Test::More tests => 3;

    use Plack::Test;
    use HTTP::Request::Common;

    use Test2;
    { package Test2; set apphandler => 'PSGI'; set log => 'error'; }

    test_psgi( Test2::dance, sub {
        my $app = shift;

        my $res = $app->( GET '/' );

        ok $res->is_success;

        is $res->code => 200, 'response status is 200 for /';

        like $res->content => qr#<title>Test2</title>#, 'title is okay';
    } );

Other modules that could be used for testing are:

Logs

The logger_format in the Logger role (Dancer2::Core::Role::Logger) is now log_format.

read_logs can no longer be used, as with Dancer2::Test. Instead, Dancer2::Logger::Capture could be used for testing, to capture all logs to an object.

For example:

    use strict;
    use warnings;
    use Test::More import => ['!pass'];
    use Plack::Test;
    use HTTP::Request::Common;

    {
        package App;
        use Dancer2;

        set log       => 'debug';
        set logger    => 'capture';

        get '/' => sub {
            debug 'this is my debug message';
            return 1;
        };
    }

    my $app = Dancer2->psgi_app;
    is( ref $app, 'CODE', 'Got app' );

    test_psgi $app, sub {
        my $cb = shift;

        my $res = $cb->( GET '/' );
        is $res->code, 200;

        my $trap = App->dancer_app->logger_engine->trapper;

        is_deeply $trap->read, [
            { level => 'debug', message => 'this is my debug message' }
        ];
    };

Exports: Tags

The following tags are not needed in Dancer2:

 use Dancer2 qw(:syntax);
 use Dancer2 qw(:tests);
 use Dancer2 qw(:script);

The plackup command should be used instead. It provides a development server and reads the configuration options in your command line utilities.

AUTHOR

Dancer Core Developers

COPYRIGHT AND LICENSE

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