lib/Catalyst/Manual/Internals.pod

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