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