MigrationDancer2

migration.pod

Migration from Dancer1 to Dancer2

This document covers some changes that users will need to be aware of while upgrading from Dancer1 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:

package myapp;
use Dancer2;
use myapp::admin;

hook before => sub {
    var db => "...";
};

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

1;

package myapp::admin;
use Dancer2 appname => "myapp";

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

1;

Without the appname directive, myapp::admin would not have access to var 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 :

URL::Encode::XS

CGI::Deurl::XS

HTTP::Parser::XS

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:

i) You have access to a C interpreter

ii) 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'

Session Engines: Configuration

In Dancer2, configuration of the session engines is passed to the constructor of the engine. For example:

session: "DBIC"
engines:
  session:
    DBIC:
      dsn:      "DBI:mysql:database=testing;host=127.0.0.1;port=3306" # DBI Data Source Name
      schema_class:    "Interchange6::Schema"  # DBIx::Class schema
      

The following attributes need to be added to your engine class, to make dsn and schema_class read only:

has dsn => (
    is => 'ro',
);

has schema_class => (
    is => 'ro',
);

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:

• Test::TCP

• Test::WWW::Mechanize::PSGI

Logs

read_logs can no longer be used, as with Dancer2::Test. Dancer2::Logger::Capture can 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.