=head1 DESCRIPTION
-This chapter of the tutorial adds role-based authorization to the
-existing authentication implemented in Chapter 5. It provides simple
-examples of how to use roles in both TT templates and controller
-actions. The first half looks at basic authorization concepts. The
-second half looks at how moving your authorization code to your model
+This chapter of the tutorial adds role-based authorization to the
+existing authentication implemented in Chapter 5. It provides simple
+examples of how to use roles in both TT templates and controller
+actions. The first half looks at basic authorization concepts. The
+second half looks at how moving your authorization code to your model
can simplify your code and make things easier to maintain.
You can checkout the source code for this example from the catalyst
=head1 BASIC AUTHORIZATION
-In this section you learn the basics of how authorization works under
+In this section you learn the basics of how authorization works under
Catalyst.
-Debug
ConfigLoader
Static::Simple
-
+
StackTrace
-
+
Authentication
Authorization::Roles
-
+
Session
Session::Store::File
Session::State::Cookie
/;
-Once again, include this additional plugin as a new dependency in
-the Makefile.PL file like this:
+Once again, include this additional plugin as a new dependency in the
+Makefile.PL file like this:
requires 'Catalyst::Plugin::Authorization::Roles';
</p>
This code displays a different combination of links depending on the
-roles assigned to the user.
+roles assigned to the user.
=head2 Limit Books::add to 'admin' Users
B<TIP>: If you want to keep your existing C<url_create> method, you can
create a new copy and comment out the original by making it look like a
-Pod comment. For example, put something like C<=begin> before
+Pod comment. For example, put something like C<=begin> before
C<sub add : Local {> and C<=end> after the closing C<}>.
$ script/myapp_server.pl -r
-Now trying going to L<http://localhost:3000/books/list> and you should
-be taken to the login page (you might have to C<Shift+Reload> or
-C<Ctrl+Reload> your browser and/or click the "User Logout" link on the book
-list page). Try logging in with both C<test01> and C<test02> (both
-use a password of C<mypass>) and notice how the roles information
-updates at the bottom of the "Book List" page. Also try the "User Logout"
-link on the book list page.
+Now trying going to L<http://localhost:3000/books/list> and you should
+be taken to the login page (you might have to C<Shift+Reload> or
+C<Ctrl+Reload> your browser and/or click the "User Logout" link on the
+book list page). Try logging in with both C<test01> and C<test02> (both
+use a password of C<mypass>) and notice how the roles information
+updates at the bottom of the "Book List" page. Also try the "User
+Logout" link on the book list page.
Now the "url_create" URL will work if you are already logged in as user
C<test01>, but receive an authorization failure if you are logged in as
http://localhost:3000/books/url_create/test/1/6
-while logged in as each user. Use one of the "logout" links (or go to
-L<http://localhost:3000/logout> in your browser directly) when you are
+while logged in as each user. Use one of the "logout" links (or go to
+L<http://localhost:3000/logout> in your browser directly) when you are
done.
=head1 ENABLE MODEL-BASED AUTHORIZATION
-Hopefully it's fairly obvious that adding detailed permission checking
-logic to our controllers and view templates isn't a very clean or
-scalable way to build role-based permissions into out application. As
-with many other aspects of MVC web development, the goal is to have
-your controllers and views be an "thin" as possible, with all of the
-"fancy business logic" built into your model.
+Hopefully it's fairly obvious that adding detailed permission checking
+logic to our controllers and view templates isn't a very clean or
+scalable way to build role-based permissions into out application. As
+with many other aspects of MVC web development, the goal is to have your
+controllers and views be an "thin" as possible, with all of the "fancy
+business logic" built into your model.
-For example, let's add a method to our C<Books.pm> Result Class to
-check if a user is allowed to delete a book. Open
-C<lib/MyApp/Schema/Result/Book.pm> and add the following method
-(be sure to add it below the "C<DO NOT MODIFY ...>" line):
+For example, let's add a method to our C<Books.pm> Result Class to check
+if a user is allowed to delete a book. Open
+C<lib/MyApp/Schema/Result/Book.pm> and add the following method (be sure
+to add it below the "C<DO NOT MODIFY ...>" line):
=head2 delete_allowed_by
sub delete_allowed_by {
my ($self, $user) = @_;
-
+
# Only allow delete if user has 'admin' role
return $user->has_role('admin');
}
-Here we call a C<has_role> method on our user object, so we should add
-this method to our Result Class. Open
-C<lib/MyApp/Schema/Result/User.pm> and add the following method below
+Here we call a C<has_role> method on our user object, so we should add
+this method to our Result Class. Open
+C<lib/MyApp/Schema/Result/User.pm> and add the following method below
the "C<DO NOT MODIFY ...>" line:
=head2 has_role
return any(map { $_->role } $self->roles) eq $role;
}
-Let's also add Perl6::Junction to the requirements listed in
+Let's also add Perl6::Junction to the requirements listed in
Makefile.PL:
requires 'Perl6::Junction';
$c->response->redirect($c->uri_for($self->action_for('list')));
}
-Here, we C<detach> to an error page if the user is lacking the
-appropriate permissions. For this to work, we need to make
-arrangements for the '/error_noperms' action to work. Open
+Here, we C<detach> to an error page if the user is lacking the
+appropriate permissions. For this to work, we need to make arrangements
+for the '/error_noperms' action to work. Open
C<lib/MyApp/Controller/Root.pm> and add this method:
=head2 error_noperms
Permissions error screen
=cut
-
+
sub error_noperms :Chained('/') :PathPart('error_noperms') :Args(0) {
my ($self, $c) = @_;
http://localhost:3000/books/url_create/Test/1/4
-Then, while still logged in as C<test01>, click the "Delete" link next
-to one of these books. The book should be removed and you should see
-the usual green "Book deleted" message. Next, click the "User Logout"
-link and log back in as C<test02>. Now try deleting one of the books.
-You should be taken to the red "Permission Denied" message on our
-error page.
+Then, while still logged in as C<test01>, click the "Delete" link next
+to one of these books. The book should be removed and you should see
+the usual green "Book deleted" message. Next, click the "User Logout"
+link and log back in as C<test02>. Now try deleting one of the books.
+You should be taken to the red "Permission Denied" message on our error
+page.
Use one of the 'Logout' links (or go to the
L<http://localhost:3000/logout> URL directly) when you are done.
=head1 DESCRIPTION
-This chapter of the tutorial takes a brief look at the primary options
+This chapter of the tutorial takes a brief look at the primary options
available for troubleshooting Catalyst applications.
Note that when it comes to debugging and troubleshooting, there are two
=head1 LOG STATEMENTS
-Folks in the former group can use Catalyst's C<$c-E<gt>log> facility.
-(See L<Catalyst::Log> for more detail.) For example, if
-you add the following code to a controller action method:
+Folks in the former group can use Catalyst's C<$c-E<gt>log> facility.
+(See L<Catalyst::Log> for more detail.) For example, if you add the
+following code to a controller action method:
$c->log->info("Starting the foreach loop here");
[% c.log.debug("This is a test log message") %]
-As with many other logging facilities, a method is defined for
-each of the following "logging levels" (in increasing order of
+As with many other logging facilities, a method is defined for each of
+the following "logging levels" (in increasing order of
severity/importance):
$c->log->debug
$c->log->error
$c->log->fatal
-You can also use L<Data::Dumper> in both Catalyst code
-(C<use Data::Dumper; $c-E<gt>log-E<gt>debug("\$var is: ".Dumper($var));)>)
+You can also use L<Data::Dumper> in both Catalyst code
+(C<use Data::Dumper; $c-E<gt>log-E<gt>debug("\$var is: ".Dumper($var));)>)
and TT templates (C<[% Dumper.dump(book) %]>.
$c->stash->{template} = 'books/list.tt2';
}
-This causes the Perl Debugger to enter "single step mode" when this command is
-encountered (it has no effect when Perl is run without the C<-d> flag).
+This causes the Perl Debugger to enter "single step mode" when this
+command is encountered (it has no effect when Perl is run without the
+C<-d> flag).
B<NOTE:> The C<DB> here is the Perl Debugger, not the DB model.
$ export DBIC_TRACE=1
-To now run the Catalyst development server under the Perl debugger, simply
-prepend C<perl -d> to the front of C<script/myapp_server.pl>:
+To now run the Catalyst development server under the Perl debugger,
+simply prepend C<perl -d> to the front of C<script/myapp_server.pl>:
$ perl -d script/myapp_server.pl
DB<1>
This takes you to the next line of code where the template name is set.
-Notice that because we enabled C<DBIC_TRACE=1> earlier, SQL debug
-output also shows up in the development server debug information.
+Notice that because we enabled C<DBIC_TRACE=1> earlier, SQL debug output
+also shows up in the development server debug information.
Next, list the methods available on our C<Book> model:
Finally, press C<Ctrl+C> to break out of the development server.
Because we are running inside the Perl debugger, you will drop to the
-debugger prompt.
+debugger prompt.
^CCatalyst::Engine::HTTP::run(/usr/local/share/perl/5.10.0/Catalyst/Engine/HTTP.pm:260):
260: while ( accept( Remote, $daemon ) ) {
DB<4>
-Finally, press C<q> to exit the debugger and return to your OS
-shell prompt:
+Finally, press C<q> to exit the debugger and return to your OS shell
+prompt:
DB<4> q
$
You can also type C<h> or C<h h> at the debugger prompt to view the
built-in help screens.
-For an excellent book covering all aspects of the Perl debugger, we highly
-recommend reading 'Pro Perl Debugging' by Richard Foley.
+For an excellent book covering all aspects of the Perl debugger, we
+highly recommend reading 'Pro Perl Debugging' by Richard Foley.
-Oh yeah, before you forget, be sure to remove the C<DB::single=1> line you
-added above in C<lib/MyApp/Controller/Books.pm>.
+Oh yeah, before you forget, be sure to remove the C<DB::single=1> line
+you added above in C<lib/MyApp/Controller/Books.pm>.
=head1 DEBUGGING MODULES FROM CPAN
-Although the techniques discussed above work well for code you are
-writing, what if you want to use print/log/warn messages or set
-breakpoints in code that you have installed from CPAN (or in module that
-ship with Perl)? One helpful approach is to place a copy of the module
-inside the C<lib> directory of your Catalyst project. When Catalyst
-loads, it will load from inside your C<lib> directory first, only
-turning to the global modules if a local copy cannot be found. You can
-then make modifications such as adding a C<$DB::single=1> to the local
-copy of the module without risking the copy in the original location.
-This can also be a great way to "locally override" bugs in modules while
+Although the techniques discussed above work well for code you are
+writing, what if you want to use print/log/warn messages or set
+breakpoints in code that you have installed from CPAN (or in module that
+ship with Perl)? One helpful approach is to place a copy of the module
+inside the C<lib> directory of your Catalyst project. When Catalyst
+loads, it will load from inside your C<lib> directory first, only
+turning to the global modules if a local copy cannot be found. You can
+then make modifications such as adding a C<$DB::single=1> to the local
+copy of the module without risking the copy in the original location.
+This can also be a great way to "locally override" bugs in modules while
you wait for a fix on CPAN.
-
-Matt Trout has suggested the following shortcut to create a local
-copy of an installed module:
+Matt Trout has suggested the following shortcut to create a local copy
+of an installed module:
mkdir -p lib/Module; cp `perldoc -l Module::Name` lib/Module/
-Note: If you are following along in Debian 6 or Ubuntu, you will
-need to install the C<perl-doc> package to use the C<perldoc> command.
-Use C<sudo aptitude install perl-doc> to do that.
+Note: If you are following along in Debian 6 or Ubuntu, you will need to
+install the C<perl-doc> package to use the C<perldoc> command. Use
+C<sudo aptitude install perl-doc> to do that.
-For example, you could make a copy of
-L<Catalyst::Plugin::Authentication>
-with the following command:
+For example, you could make a copy of
+L<Catalyst::Plugin::Authentication> with the following command:
mkdir -p lib/Catalyst/Plugin; cp \
`perldoc -l Catalyst::Plugin::Authentication` lib/Catalyst/Plugin
You can then use the local copy inside your project to place logging
messages and/or breakpoints for further study of that module.
-B<Note:> Matt has also suggested the following tips for Perl
-debugging:
+B<Note:> Matt has also suggested the following tips for Perl debugging:
=over 4
=head1 TT DEBUGGING
-If you run into issues during the rendering of your template, it might
-be helpful to enable TT C<DEBUG> options. You can do this in a Catalyst
-environment by adding a C<DEBUG> line to the C<__PACKAGE__->config>
+If you run into issues during the rendering of your template, it might
+be helpful to enable TT C<DEBUG> options. You can do this in a Catalyst
+environment by adding a C<DEBUG> line to the C<__PACKAGE__->config>
declaration in C<lib/MyApp/View/HTML.pm>:
__PACKAGE__->config({
DEBUG => 'undef',
});
-There are a variety of options you can use, such as 'undef', 'all',
-'service', 'context', 'parser' and 'provider'. See
-L<Template::Constants> for more information
-(remove the C<DEBUG_> portion of the name shown in the TT docs and
-convert to lower case for use inside Catalyst).
+There are a variety of options you can use, such as 'undef', 'all',
+'service', 'context', 'parser' and 'provider'. See
+L<Template::Constants> for more information (remove the C<DEBUG_>
+portion of the name shown in the TT docs and convert to lower case for
+use inside Catalyst).
-B<NOTE:> B<Please be sure to disable TT debug options before continuing
-with the tutorial> (especially the 'undef' option -- leaving this
-enabled will conflict with several of the conventions used by this
+B<NOTE:> B<Please be sure to disable TT debug options before continuing
+with the tutorial> (especially the 'undef' option -- leaving this
+enabled will conflict with several of the conventions used by this
tutorial to leave some variables undefined on purpose).
Happy debugging.
=head1 DESCRIPTION
-You may have noticed that the Catalyst Helper scripts automatically
-create basic C<.t> test scripts under the C<t> directory. This
-chapter of the tutorial briefly looks at how these tests can be used
-not only to ensure that your application is working correctly at the
-present time, but also provide automated regression testing as you
-upgrade various pieces of your application over time.
+You may have noticed that the Catalyst Helper scripts automatically
+create basic C<.t> test scripts under the C<t> directory. This chapter
+of the tutorial briefly looks at how these tests can be used not only to
+ensure that your application is working correctly at the present time,
+but also provide automated regression testing as you upgrade various
+pieces of your application over time.
You can check out the source code for this example from the Catalyst
Subversion repository as per the instructions in
L<Catalyst::Manual::Tutorial::01_Intro>.
For an excellent introduction to learning the many benefits of testing
-your Perl applications and modules, you might want to read 'Perl Testing:
-A Developer's Notebook' by Ian Langworth and chromatic.
+your Perl applications and modules, you might want to read 'Perl
+Testing: A Developer's Notebook' by Ian Langworth and chromatic.
=head1 RUNNING THE "CANNED" CATALYST TESTS
There are a variety of ways to run Catalyst and Perl tests (for example,
-C<perl Makefile.PL> and C<make test>), but one of the easiest is with the
-C<prove> command. For example, to run all of the tests in the C<t>
+C<perl Makefile.PL> and C<make test>), but one of the easiest is with
+the C<prove> command. For example, to run all of the tests in the C<t>
directory, enter:
$ prove -wl t
-There will be a lot of output because we have the C<-Debug> flag
-enabled in C<lib/MyApp.pm> (see the C<CATALYST_DEBUG=0> tip below for
-a quick and easy way to reduce the clutter). Look for lines like this
-for errors:
+There will be a lot of output because we have the C<-Debug> flag enabled
+in C<lib/MyApp.pm> (see the C<CATALYST_DEBUG=0> tip below for a quick
+and easy way to reduce the clutter). Look for lines like this for
+errors:
# Failed test 'Request should succeed'
# at t/controller_Books.t line 8.
# Looks like you failed 1 test of 3.
-The redirection used by the Authentication plugins will cause several
+The redirection used by the Authentication plugins will cause several
failures in the default tests. You can fix this by making the following
changes:
$ CATALYST_DEBUG=0 prove -wl t/01app.t
-Also note that you can also run tests directly from Perl without C<prove>.
-For example:
+Also note that you can also run tests directly from Perl without
+C<prove>. For example:
$ CATALYST_DEBUG=0 perl -w -Ilib t/01app.t
Although the Catalyst helper scripts provide a basic level of checks
"for free," testing can become significantly more helpful when you write
your own script to exercise the various parts of your application. The
-L<Test::WWW::Mechanize::Catalyst> module
-is very popular for writing these sorts of test cases. This module
-extends L<Test::WWW::Mechanize> (and therefore
-L<WWW::Mechanize>) to allow you to automate the action of
+L<Test::WWW::Mechanize::Catalyst> module is very popular for writing
+these sorts of test cases. This module extends L<Test::WWW::Mechanize>
+(and therefore L<WWW::Mechanize>) to allow you to automate the action of
a user "clicking around" inside your application. It gives you all the
benefits of testing on a live system without the messiness of having to
use an actual web server, and a real person to do the clicking.
The C<live_app.t> test cases uses copious comments to explain each step
of the process. In addition to the techniques shown here, there are a
-variety of other methods available in
-L<Test::WWW::Mechanize::Catalyst> (for
-example, regex-based matching). Consult the documentation for more
+variety of other methods available in L<Test::WWW::Mechanize::Catalyst>
+(for example, regex-based matching). Consult the documentation for more
detail.
B<TIP>: For I<unit tests> vs. the "full application tests" approach used
-by L<Test::WWW::Mechanize::Catalyst>, see
-L<Catalyst::Test>.
+by L<Test::WWW::Mechanize::Catalyst>, see L<Catalyst::Test>.
B<Note:> The test script does not test the C<form_create> and
C<form_create_do> actions. That is left as an exercise for the reader
$ DBIC_TRACE=0 CATALYST_DEBUG=0 prove -vwl t/live_app01.t
-Experiment with the C<DBIC_TRACE>, C<CATALYST_DEBUG> and C<-v>
-settings. If you find that there are errors, use the techniques
-discussed in the "Catalyst Debugging" section (Chapter 7) to isolate
-and fix any problems.
+Experiment with the C<DBIC_TRACE>, C<CATALYST_DEBUG> and C<-v> settings.
+If you find that there are errors, use the techniques discussed in the
+"Catalyst Debugging" section (Chapter 7) to isolate and fix any
+problems.
If you want to run the test case under the Perl interactive debugger,
try a command such as:
Unfortunately, this only shows us the first 50 characters of the HTML
returned by the request -- not enough to determine where the problem
-lies. A simple technique that can be used in such situations is to
-temporarily insert a line similar to the following right after the
+lies. A simple technique that can be used in such situations is to
+temporarily insert a line similar to the following right after the
failed test:
diag $ua1->content;
This will cause the full HTML returned by the request to be displayed.
-Another approach to see the full HTML content at the failure point in
-a series of tests would be to insert a "C<$DB::single=1;> right above
-the location of the failure and run the test under the perl debugger
-(with C<-d>) as shown above. Then you can use the debugger to explore
-the state of the application right before or after the failure.
+Another approach to see the full HTML content at the failure point in a
+series of tests would be to insert a "C<$DB::single=1;> right above the
+location of the failure and run the test under the perl debugger (with
+C<-d>) as shown above. Then you can use the debugger to explore the
+state of the application right before or after the failure.
=head1 SUPPORTING BOTH PRODUCTION AND TEST DATABASES
You may wish to leverage the techniques discussed in this tutorial to
maintain both a "production database" for your live application and a
"testing database" for your test cases. One advantage to
-L<Test::WWW::Mechanize::Catalyst> is that
-it runs your full application; however, this can complicate things when
-you want to support multiple databases.
+L<Test::WWW::Mechanize::Catalyst> is that it runs your full application;
+however, this can complicate things when you want to support multiple
+databases.
=head2 DATABASE CONFIG SWITCHING IN YOUR MODEL CLASS
-One solution is to allow the
-database specification to be overridden with an environment variable.
-For example, open C<lib/MyApp/Model/DB.pm> in your editor and
-change the C<__PACKAGE__-E<gt>config(...> declaration to resemble:
+One solution is to allow the database specification to be overridden
+with an environment variable. For example, open
+C<lib/MyApp/Model/DB.pm> in your editor and change the
+C<__PACKAGE__-E<gt>config(...> declaration to resemble:
my $dsn = $ENV{MYAPP_DSN} ||= 'dbi:SQLite:myapp.db';
__PACKAGE__->config(
variable defined, it will default to the same C<dbi:SQLite:myapp.db> as
before.
+
=head2 DATABASE CONFIG SWITCHING USING MULTIPLE CONFIG FILES
-By utilizing L<Catalyst::Plugin::ConfigLoader>s functionality for loading
-multiple config files based on environment variables you can override your
-default (production) database connection settings.
+By utilizing L<Catalyst::Plugin::ConfigLoader>s functionality for
+loading multiple config files based on environment variables you can
+override your default (production) database connection settings.
-Setting C<$ENV{ MYAPP_CONFIG_LOCAL_SUFFIX }> to 'testing' in your test script
-results in loading of an additional config file named myapp_testing.conf after
-myapp.conf which will override any parameters in myapp.conf.
+Setting C<$ENV{ MYAPP_CONFIG_LOCAL_SUFFIX }> to 'testing' in your test
+script results in loading of an additional config file named
+C<myapp_testing.conf> after C<myapp.conf> which will override any
+parameters in C<myapp.conf>.
-You should set the environment variable in the BEGIN block of your test script
-to make sure it's set before your Catalyst application is started.
+You should set the environment variable in the BEGIN block of your test
+script to make sure it's set before your Catalyst application is
+started.
-The following is an example for a config and test script for a DBIx::Class
-model named MyDB and a controller named Foo:
+The following is an example for a config and test script for a
+DBIx::Class model named MyDB and a controller named Foo:
myapp_testing.conf:
projects / catagits/Catalyst-Manual.git / commitdiff