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 stores any options.
  24
  25 =item 2
  26
  27 When C<< __PACKAGE__->setup >> is called, it evaluates any
  28 options stored (C<-Debug>), and makes the application
  29 inherit from L<Catalyst> (if that hasn't already been done with an
  30 explicit C<< use base 'Catalyst'; >> or C<< extends 'Catalyst'; >>.
  31 Any specified plugins are then loaded, the application module is made to
  32 inherit from the plugin classes. It also sets up a default log
  33 object and ensures that the application module inherits from
  34 C<Catalyst> and from the selected specialized Engine module.
  35
  36 =item 3
  37
  38 Catalyst automatically loads all
  39 components it finds in the C<$class::Controller>, C<$class::C>,
  40 C<$class::Model>, C<$class::M>, C<$class::View> and C<$class::V>
  41 namespaces (using L<Module::Pluggable>). As each is loaded, if it has a
  42 L<COMPONENT|Catalyst::Component/"COMPONENT"> method then this method
  43 will be called, and passed that component's configuration. It then returns
  44 an instance of the component, which becomes the C<$self> when methods in
  45 that component are called later.
  46
  47 =item 4
  48
  49 Each controller has it's C<register_actions> method called. At this point,
  50 the subroutine attributes are retrieved from the
  51 L<metaclass|MooseX::MethodAttributes::Role::Meta::Map>, parsed, and used to
  52 build instances of L<Catalyst::Action>, which are then registered with
  53 the dispatcher.
  54
  55 =back
  56
  57 =head2 Request Lifecycle
  58
  59 For each request Catalyst builds a I<context> object, which includes
  60 information about the request, and then searches the action table for matching
  61 actions.
  62
  63 The handling of a request can be divided into three stages: preparation of the
  64 context, processing of the request, and finalization of the response.  These
  65 are the steps of a Catalyst request in detail; every step can be overloaded to
  66 extend Catalyst.
  67
  68     handle_request
  69       prepare
  70         prepare_request
  71         prepare_connection
  72         prepare_query_parameters
  73         prepare_headers
  74         prepare_cookies
  75         prepare_path
  76         prepare_body (unless parse_on_demand)
  77           prepare_body_parameters
  78           prepare_parameters
  79           prepare_uploads
  80         prepare_action
  81       dispatch
  82       finalize
  83         finalize_uploads
  84         finalize_error (if one happened)
  85         finalize_headers
  86           finalize_cookies
  87         finalize_body
  88
  89 These steps are normally overloaded from engine classes, and may also be
  90 extended by plugins. For more on extending Catalyst, see L<Catalyst::Manual::ExtendingCatalyst>.
  91
  92 The engine class populates the Catalyst request object with
  93 information from the underlying layer (L<PSGI>)
  94 during the prepare phase, then push the generated response information down to
  95 the underlying layer during the finalize phase.
  96
  97 =head1 AUTHORS
  98
  99 Catalyst Contributors, see Catalyst.pm
 100
 101 =head1 COPYRIGHT
 102
 103 This library is free software. You can redistribute it and/or modify it under
 104 the same terms as Perl itself.
 105
 106 =cut