lib/Catalyst/Manual/Internals.pod

   1 =head1 NAME
   2
   3 Catalyst::Manual::Internals - Catalyst Internals
   4
   5 =head1 DESCRIPTION
   6
   7 This document provides an overview of the internals of
   8 Catalyst.  As Catalyst is still developing rapidly, details
   9 may become out of date: please treat this as a guide, and
  10 look at the source for the last word.
  11
  12 The coverage is split into initialization and request lifecycle.
  13
  14 =head2 Initialization
  15
  16 Catalyst initializes itself in two stages (I may be wrong in some of
  17 the details here - AF):
  18
  19 =over 4
  20
  21 =item 1
  22
  23 When the Catalyst module is imported in the main application
  24 module it evaluates any options (C<-Debug>, C<-Engine=XXX>)
  25 and loads any specified plugins, making the application module
  26 inherit from the plugin classes. It also sets up a default log
  27 object and ensures that the application module inherits from
  28 C<Catalyst> and from the selected specialized Engine module.
  29
  30 =item 2
  31
  32 When the application module makes the first call to C<< __PACKAGE__->action() >>
  33 (implemented in C<Catalyst::Engine>), Catalyst automatically loads all
  34 components it finds in the C<$class::Controller>, C<$class::C>,
  35 C<$class::Model>, C<$class::M>, C<$class::View> and C<$class::V>
  36 namespaces (using C<Module::Pluggable::Fast>).  A table of actions is built up
  37 and added to on subsequent calls to C<action()>.
  38
  39 =back
  40
  41
  42 =head2 Request Lifecycle
  43
  44 For each request Catalyst builds a I<context> object, which includes
  45 information about the request, and then searches the action table for matching
  46 actions.
  47
  48 The handling of a request can be divided into three stages: preparation of the
  49 context, processing of the request, and finalization of the response.  These
  50 are the steps of a Catalyst request in detail; every step can be overloaded to
  51 extend Catalyst.
  52
  53     handle_request
  54       prepare
  55         prepare_request
  56         prepare_connection
  57         prepare_query_parameters
  58         prepare_headers
  59         prepare_cookies
  60         prepare_path
  61         prepare_body (unless parse_on_demand)
  62           prepare_body_parameters
  63           prepare_parameters
  64           prepare_uploads
  65         prepare_action
  66       dispatch
  67       finalize
  68         finalize_uploads
  69         finalize_error (if one happened)
  70         finalize_headers
  71           finalize_cookies
  72         finalize_body
  73
  74 These steps are normally overloaded from engine classes, and may also be
  75 extended by plugins.  Extending means using multiple inheritance with L<NEXT>.
  76
  77 The specialized engine classes populate the Catalyst request object with
  78 information from the underlying layer (C<Apache::Request> or C<CGI::Simple>)
  79 during the prepare phase, then push the generated response information down to
  80 the underlying layer during the finalize phase.
  81
  82
  83 =head1 AUTHOR
  84
  85 Sebastian Riedel, C<sri@oook.de>
  86
  87 =head1 COPYRIGHT
  88
  89 This program is free software, you can redistribute it and/or modify it under
  90 the same terms as Perl itself.