libdancer2-perl 0.152000+dfsg-1 / usr / share / perl5 / Dancer2 / Manual / Migration.pod

package Dancer2::Manual::Migration;
# ABSTRACT: Migrating from Dancer to Dancer2
$Dancer2::Manual::Migration::VERSION = '0.152000';
use strict;
use warnings;

1;

__END__

=pod

=encoding UTF-8

=head1 NAME

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

=head1 VERSION

version 0.152000

=head2 Migration from Dancer1 to Dancer2

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

=head3 Apps

1. In L<Dancer2>, each module is a B<separate application> with its own
namespace and variables. You can set the application name in each of your
L<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:

C<MyApp>:

    package MyApp;
    use Dancer2;
    use MyApp::Admin

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

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

    1;

C<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, C<MyApp::Admin> would not have access
to variable C<db>. In fact, when accessing C</admin>, the before hook would
not be executed.

See L<Dancer2::Cookbook|https://metacpan.org/pod/Dancer2::Cookbook#Using-the-prefix-feature-to-split-your-application>
for details.

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

=over 4

=item * L<URL::Encode::XS>

=item * L<CGI::Deurl::XS>

=item * L<HTTP::Parser::XS>

=back

They would need to be installed separately. This is because L<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:

=over 4

=item * You have access to a C interpreter

=item * You don't need to fatpack your application

=back

=head3 Plugins: plugin_setting

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

=head3 Routes

L<Dancer2> requires all routes defined via a string to begin with a leading
slash C</>.

For example:

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

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

=head3 Tests

Dancer2 recommends the use of L<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:

=over 4

=item * L<Test::TCP>

=item * L<Test::WWW::Mechanize::PSGI>

=back

=head4 Logs

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

C<read_logs> can no longer be used, as with L<Dancer2::Test>. Instead,
L<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' }
        ];
    };

=head3 Exports: Tags

The following tags are not needed in L<Dancer2>:

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

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

=head1 AUTHOR

Dancer Core Developers

=head1 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.

=cut