lib/Catalyst/Manual/Tutorial/Debugging.pod

   1 =head1 NAME
   2
   3 Catalyst::Manual::Tutorial::Debugging - Catalyst Tutorial  Part 6: Debugging
   4
   5
   6
   7 =head1 OVERVIEW
   8
   9 This is B<Part 6 of 9> for the Catalyst tutorial.
  10
  11 L<Totorial Overview|Catalyst::Manual::Tutorial>
  12
  13 =over 4
  14
  15 =item 1
  16
  17 L<Introduction|Catalyst::Manual::Tutorial::Intro>
  18
  19 =item 2
  20
  21 L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics>
  22
  23 =item 3
  24
  25 L<Basic CRUD|Catalyst::Manual::Tutorial03_BasicCRUD>
  26
  27 =item 4
  28
  29 L<Authentication|Catalyst::Manual::Tutorial::Authentication>
  30
  31 =item 5
  32
  33 L<Authorization|Catalyst::Manual::Tutorial::Authorization>
  34
  35 =item 6
  36
  37 B<Debugging>
  38
  39 =item 7
  40
  41 L<Testing|Catalyst::Manual::Tutorial::Testing>
  42
  43 =item 8
  44
  45 L<AdvancedCRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
  46
  47 =item 9
  48
  49 L<Appendicies|Catalyst::Manual::Tutorial::Appendicies>
  50
  51 =back
  52
  53
  54
  55 =head1 DESCRIPTION
  56
  57 This part of the tutorial takes a brief look at the primary options available for troubleshooting Catalyst applications.
  58
  59 Note that when it comes to debugging and troubleshooting, there are two camps:
  60
  61 =over 4
  62
  63 =item *
  64
  65 Fans of C<log> and C<print> statements embedded in the code.
  66
  67 =item *
  68
  69 Fans of interactive debuggers.
  70
  71 =back
  72
  73 Catalyst is able to easily accommodate both styles of debugging.
  74
  75
  76
  77 =head1 LOG STATEMENTS
  78
  79 Folks in the former group can use Catalyst's C<$c-E<gt>log> facility.  For example, if you add the following code to a controller action method:
  80
  81     $c->log->debug("This is a test log message");
  82
  83 Then the Catalyst development server will display your message along with the other debug output.  To accomplish the same thing in a TTSite view use:
  84
  85     [% Catalyst.log.debug("This is a test log message") %]
  86
  87 You can also use L<Data::Dumper|Data::Dumper> in both Catalyst code
  88 (C<$c-E<gt>log-E<gt>dumper($myvar)>) and TT templates (C<[% Dumper.dump(book) %]> as discussed in earlier parts of the tutorial.
  89
  90
  91
  92 =head1 RUNNING CATALYST UNDER THE PERL DEBUGGER
  93
  94 Members of the interactive debuggers fan club will also be at home with Catalyst applications.  One approach to this style of Perl debugging is to embed breakpoints in your code.  For example, open C<lib/MyApp/Controller/Books.pm> in your editor and add the C<DB::single=1> line as follows inside the C<list> method (I like to "left-justify" my debug statements so I don't forget to remove them, but you can obviously indent them if you prefer):
  95
  96     sub list : Local {
  97         # Retrieve the usual perl OO '$self' for this object. $c is the Catalyst
  98         # 'Context' that's used to 'glue together' the various components
  99         # that make up the application
 100         my ($self, $c) = @_;
 101
 102     $DB::single=1;
 103
 104         # Retrieve all of the book records as book model objects and store in the
 105         # stash where they can be accessed by the TT template
 106         $c->stash->{books} = [$c->model('MyAppDB::Book')->all];
 107
 108         # Set the TT template to use.  You will almost always want to do this
 109         # in your action methods.
 110         $c->stash->{template} = 'books/list.tt2';
 111     }
 112
 113 This causes the Perl Debugger to enter "single step mode" when this command is
 114 encountered (it has no effect when Perl is run without the C<-d> flag).
 115
 116 To now run the Catalyst development server under the Perl debugger, simply
 117 prepend C<perl -d> to the front of C<script/myapp_server.pl>:
 118
 119     $ perl -d script/myapp_server.pl
 120
 121 This will start the interactive debugger and produce output similar to:
 122
 123     $ perl -d script/myapp_server.pl
 124
 125     Loading DB routines from perl5db.pl version 1.27
 126     Editor support available.
 127
 128     Enter h or `h h' for help, or `man perldebug' for more help.
 129
 130     main::(script/myapp_server.pl:14):      my $debug         = 0;
 131
 132       DB<1>
 133
 134 Press the C<c> key and hit C<Enter> to continue executing the Catalyst development server under the debugger.  Although execution speed will be slightly slower than normal, you should soon see the usual Catalyst startup debug information.
 135
 136 Now point your browser to L<http://localhost:3000/books/list> and log in.  Once the breakpoint is encountered in the C<MyApp::Controller::list> method, the console session running the development server will drop to the Perl debugger prompt:
 137
 138     MyApp::Controller::Books::list(/home/me/MyApp/script/../lib/MyApp/Controller/Books.pm:40):
 139     40:         $c->stash->{books} = [$c->model('MyAppDB::Book')->all];
 140
 141       DB<1>
 142
 143 You now have the full Perl debugger at your disposal.  First use the C<next> feature by typing C<n> to execute the C<all> method on the Book model (C<n> jumps over method/subroutine calls; you can also use C<s> to C<single-step> into methods/subroutines):
 144
 145       DB<1> n
 146     SELECT me.id, me.authors, me.title, me.rating FROM books me:
 147     MyApp::Controller::Books::list(/home/me/MyApp/script/../lib/MyApp/Controller/Books.pm:44):
 148     44:         $c->stash->{template} = 'books/list.tt2';
 149
 150       DB<1>
 151
 152 This takes you to the next line of code where the template name is set.  Notice that because we enabled C<DBIX_CLASS_STORAGE_DBI_DEBUG=1> earlier, SQL debug output also shows up in the development server debug output.
 153
 154 Next, list the methods available on our C<Book> model:
 155
 156       DB<1> m $c->model('MyAppDB::Book')
 157     ()
 158     (0+
 159     (bool
 160     MODIFY_CODE_ATTRIBUTES
 161     _attr_cache
 162     _collapse_result
 163     _construct_object
 164     _count
 165     _result_class_accessor
 166     _result_source_accessor
 167     all
 168     carp
 169     <lines removed for brevity>
 170
 171       DB<2>
 172
 173 We can also play with the model directly:
 174
 175       DB<2> x ($c->model('MyAppDB::Book')->all)[1]->title
 176     SELECT me.id, me.title, me.rating FROM books me:
 177     0  'TCP/IP Illustrated, Volume 1'
 178
 179 This uses the Perl debugger C<x> command to display the title of a book.
 180
 181 Next we inspect the C<books> element of the Catalyst C<stash> (the C<4> argument to the C<x> command limits the depth of the dump to 4 levels):
 182
 183       DB<3> x 4 $c->stash->{books}
 184     0  ARRAY(0xa8f3b7c)
 185        0  MyApp::Model::MyAppDB::Book=HASH(0xb8e702c)
 186           '_column_data' => HASH(0xb8e5e2c)
 187              'id' => 1
 188              'rating' => 5
 189              'title' => 'CCSP SNRS Exam Certification Guide'
 190           '_in_storage' => 1
 191     <lines removed for brevity>
 192
 193 Then enter the C<c> command to continue processing until the next breakpoint is hit (or the application exits):
 194
 195       DB<4> c
 196     SELECT author.id, author.first_name, author.last_name FROM ...
 197
 198 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.  Press C<q> to exit the debugger and return to your OS shell prompt:
 199
 200       DB<4> q
 201     $
 202
 203 For more information on using the Perl debugger, please see C<perldebug> and C<perldebtut>.  You can also type C<h> or C<h h> at the debugger prompt to view the built-in help screens.
 204
 205
 206
 207 =head1 AUTHOR
 208
 209 Kennedy Clark, C<hkclark@gmail.com>
 210
 211 Please report any errors, issues or suggestions to the author.
 212
 213 Copyright 2006, Kennedy Clark. All rights reserved.
 214
 215 This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
 216
 217 Version: .94
 218