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