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